⎕NLOCK Lock/Unlock a file or a segment of a file

The ⎕NLOCK function allows the user to lock a file or a segment of a file. Setting a file lock prevents another user from locking the same file or segment in an incompatible mode.

The syntax of ⎕NLOCK is ({} means optional) :

          ⎕NLOCK TIE, MODE {,COUNT {,STARTBYTE {,TIMEOUT}}}

TIE specifies the file to lock or unlock

MODE specifies the lock operation to perform, as follows:

          0 - unlock file or segment
          1 - establish a read lock on a file or segment
          2 - establish a write lock on a file or segment

COUNT specifies the length in bytes of the segment to lock or unlock. The default value of ¯1 will set a lock from the specified start position to the current and any future end of file.

STARTBYTE specifies the offset from the start of the file at which the lock segment begins. A value of ¯1 (default) specifies the start of the file.

TIMEOUT is used to specify a request timeout value in milliseconds (see below). A value of ¯1 specifies no timeout. The default value of 10000 is chosen to specify a sensible 10 second default.

The implementation of ⎕NLOCK differs slightly on AIX and Linux systems from other APLX systems. Under AIX and Linux, file locking facilities provide controlled multi-user file access for cooperating processes which agree on a locking scheme; locks do not prevent another user who ignores the scheme from reading or writing the file. That is, a write lock set on a segment of a file prevents another user from setting a write lock on the same file segment, but does not prevent writing data to the segment.

Two lock modes are supported. A read lock prevents other users from write- locking the file or segment. A write lock prevents other users from read-locking or write-locking the file or segment. An attempt to use ⎕NLOCK to set a lock on a file or segment which is already locked in an incompatible mode by another user will fail with a FILE I/O ERROR, and the ⎕NERROR message gives details of the reason for the failure. To set a read lock the file must be tied in a mode which permits reading; to set a write lock the file must be tied in a mode which permits reading and writing.

Using ⎕NLOCK it is possible to lock a whole file or a specified segment. The extent of the segment to lock is specified by a combination of the COUNT and STARTBYTE parameters. By using a COUNT value of ¯1 it is possible to set a lock which extends from the specified start position to the current and any future end of file. It is also valid to specify a lock segment which starts beyond the current end of file. It is possible to have locks on several segments of a file simultaneously.

Locking a segment which is already locked by the user causes the old lock type to be removed and the new lock type to take effect. Changing or unlocking a portion from the middle of a larger locked segment leaves a smaller segment at either end.

The TIMEOUT parameter is used to specify a timeout value for the lock request. If the requested lock cannot be immediately granted because another user has locked the segment in an incompatible mode, the process will sleep for TIMEOUT milliseconds waiting for the segment to become free. If a TIMEOUT value of 0 is specified, the lock request will give an error immediately if the lock cannot be granted. A value of ¯1 causes the process to sleep forever. The default value of 10000 causes the process to sleep for up to ten seconds. A process that is sleeping while waiting for a lock can be woken with an interrupt.

The host locking mechanism detects deadlock situations. If a lock request cannot be immediately granted because another process has the segment locked, and the other process is sleeping on a request for a segment which the user has locked, the potential for a deadlock exists. In this case the requested lock will be refused. Note however that deadlocks are not always detected in a distributed file system. When such deadlocks are possible ⎕NLOCK should always be used with a timeout value.

All locks set on a file are automatically cleared by ⎕NUNTIE, )CLEAR and )OFF. If the same file is tied on more than one tie number, untying it on any tie will clear all the locks set on the file.

Note that there is a limit on the total number of locks a process may have at one time; this limit is imposed by the host operating system.

Examples:

Set exclusive lock on the whole of the file tied on tie number 100. All other users are prevented from locking any current or future segment of the file:

     ⎕NLOCK 100 2

Try to get a read lock on the first 1000 bytes of the file, with a timeout value of 2 seconds:

     ⎕NLOCK 100 1 1000 0 2000

Release all locks on the file:

     ⎕NLOCK 100 0