LOCKING(S) XENIX System V LOCKING(S)
Name
locking - Locks or unlocks a file region for reading or
writing.
Syntax
#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 will fail 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 LK_LOCK or LK_NBLCK 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
LK_RLCK or LK_NBRLCK 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 LK_LOCK or LK_RLCK mode in its
lock request, but will return with the error EACCES if it
specified LK_NBLCK or LK_NBRLCK.
fildes is the value returned from a successful creat, open,
dup, or pipe system call.
Page 1 (printed 8/7/87)
LOCKING(S) XENIX System V LOCKING(S)
mode specifies the type of lock operation to be performed on
the file region. The available values for mode are:
LK_UNLCK 0
Unlocks the specified region. The calling process
releases a region of the file it had previously locked.
LK_LOCK 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).
LK_NBLCK 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 (nonblocking lockrequest).
LK_RLCK 3
Same as LK_LOCK except that the locked region may be
read by other processes (read permitted lock).
LK_NBRLCK 4
Same as LK_NBLCK 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 executed 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.
Page 2 (printed 8/7/87)
LOCKING(S) XENIX System V LOCKING(S)
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 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. There is however a system-wide limit on
the total number of locked regions. This limit is 200 for
XENIX 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 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
creat(S), open(S), read(S), write(S), dup(S), close(S),
lseek(S)
Diagnostics
Page 3 (printed 8/7/87)
LOCKING(S) XENIX System V LOCKING(S)
locking returns the value (int) -1 if an error occurs. If
any portion of the region has been locked by another process
for the LK_LOCK and LK_RLCK actions and the lock request is
to test only, errno is set to EAGAIN when used with System
V binaries. If the binary using this routine is a 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).
Notes
This routine must be linked with the linker option -lx.
Page 4 (printed 8/7/87)