locking(2) (XENIX Compatibility Package) locking(2)
NAME
locking - locks or unlocks a file region for reading or writing
SYNOPSIS
cc [flag ...] file ... -lx
locking (int fildes, int 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 become unlocked depending upon the mode in which the
file region was locked.
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) will sleep 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) will sleep until the region of the file has been
released by the locking process, but a read request for that file
region will proceed normally.
A process that attempts to lock a region of a file that contains
areas that have been locked by other processes will sleep if it has
specified the LKLOCK or LKRLCK mode in its lock request, but will
return with the error EACCES if it specified LKNBLCK or LKNBRLCK.
fildes is the value returned from a successful create, 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 has previously locked.
LKLOCK 1 Locks the specified region. The calling process will sleep
until the entire region is available if any part of it has
been locked by a different 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, return the error
EACCES instead of waiting for the region to become
8/91 Page 1
locking(2) (XENIX Compatibility Package) locking(2)
available for locking (nonblocking lockrequest).
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",ORDWR);
lseek(fd, 200L, 0);
locking(fd, LKLOCK, 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
executed with a size of 0.
size is the number of contiguous bytes to be locked for unlocked.
The region to be locked starts at the current offset in the file. If
size is 0, the entire file 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 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
previously 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 (i.e.; either read
permitted or regular lock). If the mode of the overlapping locks
differ, the locked areas will be assigned assuming that the most
recent request must be satisfied. 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 will be locked for read only,
while the remaining region, if any, will remain locked against
reading and writing. There is no arbitrary limit to the number of
regions which may be locked in a file.
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.
Page 2 8/91
locking(2) (XENIX Compatibility Package) locking(2)
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 will be 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.
SEE ALSO
close(2) creat(2), dup(2), lseek(2), open(2), read(2), write(2)
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. If locking the region would cause a deadlock, errno is set
to EDEADLK If an internal lock cannot be allocated, errno is set to
ENOLCK.
8/91 Page 3