locking(2XNX) (XENIX System Compatibility) locking(2XNX)
NAME
locking - (XENIX) lock or unlock a file region for reading or
writing
SYNOPSIS
cc [flag . . . ] flag . . . -lx
int 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 LK_LOCK or LK_NBLCK mode) with 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 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:
LK_UNLCK 0
Unlocks the specified region. The calling process
releases a region of the file it has 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
Copyright 1994 Novell, Inc. Page 1
locking(2XNX) (XENIX System Compatibility) locking(2XNX)
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 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's
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
Copyright 1994 Novell, Inc. Page 2
locking(2XNX) (XENIX System Compatibility) locking(2XNX)
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 (that is, 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 or 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. 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.
Return Values
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. 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.
Copyright 1994 Novell, Inc. Page 3
locking(2XNX) (XENIX System Compatibility) locking(2XNX)
REFERENCES
close(2), creat(2), dup(2), lseek(2), open(2), read(2),
write(2)
Copyright 1994 Novell, Inc. Page 4