locking(S) 6 January 1993 locking(S) Name locking - locks or unlocks a file region for reading or writing Syntax cc . . . -lx #include <sys/types.h> #include <sys/locking.h> int locking (fildes, mode, size); int fildes, mode; long size; Description locking allows a specified number of bytes in a file to be controlled by the locking process. Other processes which attempt to read or write a portion of the file containing the locked region may sleep until the area becomes unlocked depending upon the mode in which the file region was locked. A file must be open with read or read/write permission for a read lock to be performed. Write or read/write permission is required for a write lock. If either of these conditions are not met, the lock fails with the error EINVAL. A process that attempts to write to or read a file region that has been locked against reading and writing by another process (using the LKLOCK or LKNBLCK mode) sleeps until the region of the file has been released by the locking process. A process that attempts to write to a file region that has been locked against writing by another process (using the LKRLCK or LKNBRLCK mode) sleeps until the region of the file has been released by the locking pro- cess, but a read request for that file region proceeds normally. A process that attempts to lock a region of a file that contains areas that have been locked by other processes sleeps if it has specified the LKLOCK or LKRLCK mode in but returns with the error EACCES if it speci- fied LKNBLCK or LKNBRLCK. fildes is the value returned from a successful creat, open, dup, or pipe system call. mode specifies the type of lock operation to be performed on the file region. The available values for mode are: LKUNLCK 0 Unlocks the specified region. The calling process releases a region of the file it had previously locked. LKLOCK 1 Locks the specified region. The calling process sleeps until the entire region is available if any part of it has been locked by a dif- ferent process. The region is then locked for the calling process and no other process may read or write in any part of the locked region. (lock against read and write). LKNBLCK 2 Locks the specified region. If any part of the region is already locked by a different process, EACCES is returned instead of waiting for the region to become available for locking (nonblocking lockre- quest). LKRLCK 3 Same as LKLOCK except that the locked region may be read by other processes (read permitted lock). LKNBRLCK 4 Same as LKNBLCK except that the locked region may be read by other processes (nonblocking, read permitted lock). The locking utility uses the current file pointer position as the starting point for the locking of the file segment. So a typical sequence of commands to lock a specific range within a file might be as follows: fd=open(``datafile'',O_RDWR); lseek(fd, 200L, 0); locking(fd, LK_LOCK, 200L); Accordingly, to lock or unlock an entire file a seek to the beginning of the file (position 0) must be done and then a locking call must be exe- cuted with a size of 0. size is the number of contiguous bytes to be locked or unlocked. The region to be locked starts at the current offset in the file. If size is 0, the entire file (up to a maximum of 2 to the power of 30 bytes) is locked or unlocked. size may extend beyond the end of the file, in which case only the process issuing the lock call may access or add information to the file within the boundary defined by size. The potential for a deadlock occurs when a process controlling a locked area is put to sleep by accessing another process' locked area. Thus calls to locking, read, or write scan for a deadlock prior to sleeping on a locked region. An EDEADLK (or EDEADLOCK) error return is made if sleeping on the locked region would cause a deadlock. Lock requests may, in whole or part, contain or be contained by a previ- ously locked region for the same process. When this occurs, or when adjacent regions are locked, the regions are combined into a single area if the mode of the lock is the same (that is, either read permitted or regular lock). If the mode of the overlapping locks differ, the locked areas are assigned assuming that the most recent request must be satis- fied. Thus if a read only lock is applied to a region, or part of a region, that had been previously locked by the same process against both reading and writing, the area of the file specified by the new lock is locked for read only, while the remaining region, if any, remains locked against reading and writing. There is no arbitrary limit to the number of regions that may be locked in a file. There is, however, a system- wide limit on the total number of locked regions. This limit is 200 for UNIX style systems. Unlock requests may, in whole or part, release one or more locked regions controlled by the process. When regions are not fully released, the remaining areas are still locked by the process. Release of the center section of a locked area requires an additional locked element to hold the separated section. If the lock table is full, an error is returned, and the requested region is not released. Only the process which locked the file region may unlock it. An unlock request for a region that the process does not have locked, or that is already unlocked, has no effect. When a process terminates, all locked regions controlled by that process are unlocked. If a process has done more than one open on a file, all locks put on the file by that process are released on the first close of the file. Although no error is returned if locks are applied to special files or pipes, read/write operations on these types of files will ignore the locks. Locks may not be applied to a directory. Diagnostics locking returns the value (int) -1 if an error occurs. If any portion of the region has been locked by another process for the LKLOCK and LKRLCK actions and the lock request is to test only, errno is set to EAGAIN when used with UNIX System V binaries. If the binary using this routine is a UNIX 3.0 binary, this errno is set to EACCES. If the file specified is a directory, errno is set to EACCES. If locking the region would cause a deadlock, errno is set to EDEADLK (or EDEADLOCK). If there are no more free internal locks, errno is set to EDEADLK (or EDEADLOCK). See also close(S), creat(S), dup(S), lseek(S), open(S), read(S), write(S) Standards conformance locking is not part of any currently supported standard; it is an exten- sion of AT&T System V provided by the Santa Cruz Operation.