locking(2) SYSTEM CALLS 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) with sleep
until the region of the file has been released by the lock-
ing process. A process that attempts to write to a file
region that has been locked against writing by another pro-
cess (using the LKRLCK or LKNBRLCK mode) will sleep until
the region of the file has been released by the locking pro-
cess, 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 opera-
tion 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 pro-
cess. 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 available for locking (nonblock-
ing lockrequest).
Last change: XENIX Compatibility Package 1
locking(2) SYSTEM CALLS locking(2)
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 per-
mitted 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 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 control-
ling a locked area is put to sleep by accessing another pro-
cess' 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 pro-
cess 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. 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,
Last change: XENIX Compatibility Package 2
locking(2) SYSTEM CALLS locking(2)
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 inter-
nal lock cannot be allocated, errno is set to ENOLCK.
Last change: XENIX Compatibility Package 3