The Lock(file) command obtains a file lock for file. With no optional arguments an exclusive lock for the entire file is acquired.

If opt1, opt2, ... is bytes=low..high, then the bytes in file position low to high in file are locked.  If relative is also specified, then low and high are considered relative to the current file position.  It is possible to lock regions beyond the end of the file using the bytes argument.  When locking multiple byte ranges in a single file, the bytes ranges should not overlap.

The Lock function returns true if the lock was obtained and false otherwise.  If an error occurs, an exception is raised.

The file locks obtained are exclusive.  Only one process can lock a particular region at any given time.  For cross platform compatibility, locks should be treated as advisory.  An advisory lock does not stop the user from writing into a locked region, it only warns that another process has a lock.  Therefore, if a file is locked, no attempt to access the locked region should be made.  On some systems the locks are mandatory.  An attempt to access a locked region will fail.  In future versions of Maple, these platforms may be changed to use advisory locks.

Be careful opening a file that may be locked. A file should not be opened with overwrite=true if that file may be locked by another process. For details, see Open. With advisory locking, the overwrite=true deletes the contents of the file regardless of file locks.

Maple file locking works over some Network File Systems (NFS).  In general, Maple file locking works if the NFS protocol and the host operating systems support file locking.  This tends not to be true when Windows, Apple, and UNIX machines are mixed.

Locked regions should be unlocked using Unlock. All file locks are released if a file is closed.

You can test if a lock is obtainable using the IsLockable command.  However, if you intend to lock the file, it is better to call Lock and handle a false return value should the lock be unavailable.

To use Maple file locking capabilities in conjunction with other applications, the following operating system dependent information is helpful.  Under Windows, Maple uses the FileLock command from the Win32 API. In UNIX, Maple uses the fcntl style of file locks.

Maple file locking capabilities are based on an operating system's file locking facilities.  Therefore, on some operating systems more advanced functionality is available.  The following options are available only on UNIX: block and type=shared.  As well, it is possible to specify overlapping regions for the bytes argument.

(Valid only on UNIX).  The range given to the bytes option may overlap with regions already locked from the current Maple session.  Doubly locked regions remain locked.  Under UNIX, Maple file locking works as if each byte of a file is flagged as locked or unlocked.  Calling Lock sets the flag to locked.  Similarly, calling Unlock sets the flag to unlocked.  Therefore, locking an already locked byte or unlocking an unlocked byte is not an error.

(Available only on UNIX).  If opt1, opt2, ... is block, then the call to Lock will block until the lock can be obtained.  In this case Lock either returns true or raises an exception on error.

(Available only on UNIX).  If opt1, opt2, ... is type=shared, then the lock will be a shared lock.  Multiple processes may have shared locks for a single region in a file.  However, shared locks cannot overlap with exclusive locks.  Shared locks are often used for processes that need to read from a shared file.  Multiple processes reading from the same region of a file do not cause conflicts.  (Shared locks are often referred to as read locks)  Exclusive locks are then used for processes that need to write to a region of a file.  No other process should be able to access the region while another process is writing to it. (Exclusive locks are also called write locks).  It is also possible to specify type=exclusive to specify an exclusive lock; however, this is the default behavior.

$\mathrm{FileTools}\left[\mathrm{Text}\right]\left[\mathrm{Open}\right]\left(\mathrm{testfile}\right)\:$

$\mathrm{FileTools}\left[\mathrm{Lock}\right]\left(\mathrm{testfile}\,\mathrm{bytes}=10..20\right)$

$\mathrm{true}$

$\mathrm{FileTools}\left[\mathrm{Unlock}\right]\left(\mathrm{testfile}\,\mathrm{bytes}=10..20\right)$