LOCKF(S) XENIX System V LOCKF(S)
Name
lockf - Provide semaphores and record locking on files.
Syntax
#include <unistd.h>
int lockf(fildes, function, size)
long size;
int fildes, function;
Description
lockf locks a specified region of the file given by the file
descriptor, fildes, against access by all other processes.
Other processes which attempt to use the locked region will
either return an error or wait until the region is unlocked.
More than one region in a file can be locked. When the
process closes the file (or terminates), all locks are
removed. See fcntl(S) for more information about record
locking.
fildes is an open file descriptor. The file descriptor must
have O_WRONLY or O_RDWR permission in order to establish a
lock with the lockf function call.
The function argument specifies what action to take. The
possible values are defined in <unistd.h> and as follows:
F_ULOCK
Unlock a previously locked region.
F_LOCK
Lock the region for exclusive use. If the region is
not available, the calling process sleeps until the
region is available.
F_TLOCK
Test for locks, then lock the region for exclusive use.
If the region is not available, lockf returns
immediately and sets errno to EAGAIN .
F_TEST
Test the region for other processes' locks. This
argument is used to determine whether or not another
process has placed a lock on the specified region.
The size argument is the number of contiguous bytes to be
locked or unlocked. The region to be locked starts at the
current position in the file and extends forward for a
positive size and backward for a negative size (the
preceding bytes up to but not including the current offset).
If the size is 0, the region extends from the current
position in the file to the current or future end of the
Page 1 (printed 8/7/87)
LOCKF(S) XENIX System V LOCKF(S)
file. An area does not need to be allocated to the file in
order to be locked as such locks may exist past the end-of-
file.
The sections locked with F_LOCK or F_TLOCK may, in whole or
in part, contain or be contained by a previously locked
region for the same process. When this occurs, or if
overlapping regions occur, the regions are combined. If the
request requires that a new element be added to the table of
active locks and this table is already full, an [EDEADLK]
(or [EDEADLOCK]) error is returned and the new region is not
locked.
F_LOCK and F_TLOCK requests differ only by the action taken
if the resource is not available. F_LOCK will cause the
calling process to sleep until the resource is available.
F_TLOCK will cause the function to return a -1 and set errno
to [EAGAIN] error if the region is already locked by another
process.
F_ULOCK requests may, in whole or in part, release one or
more locked regions controlled by the process. When regions
are not fully released, the remaining regions are still
locked by the process. Releasing the center region of a
locked region requires an additional element in the table of
active locks. If this table is full, an [EDEADLK] (or
[EDEADLOCK]) error is returned and the requested region is
not released.
A potential for deadlock occurs if a process controlling a
locked resource is put to sleep by accessing another
process's locked resource. Therefore, calls to lockf(S) or
fcntl(S) scan for a deadlock prior to sleeping on a locked
resource. An [EDEADLK] (or [EDEADLOCK]) error return is
made if sleeping on the locked resource would cause a
deadlock.
Sleeping on a resource is interrupted with any signal. The
alarm(S) routine may be used to provide a timeout facility
in applications that require this facility.
The lockf routine will fail if one or more of the following
are true:
fildes is not a valid open descriptor. [EBADF]
cmd is F_TLOCK or F_TEST and the region is already
locked by another process. [EAGAIN]
cmd is F_LOCK or F_TLOCK and a deadlock occurs. Also
the cmd is either of the above or F_ULOCK, and there
are not enough entries in the system lock table to
Page 2 (printed 8/7/87)
LOCKF(S) XENIX System V LOCKF(S)
honor the request. [EDEADLK] or [EDEADLOCK]
Return Values
When the lock routine is successfully completed, a value of
0 is returned. Otherwise, a value of -1 is returned and
errno is set to indicate the error.
See Also
alarm(S), chmod(S), close(S), creat(S), fcntl(S), open(S),
read(S), write(S),
Notes
Record and file locking should not be used in combination
with the standard I/O routines, such as fopen(S), fread(S),
and fwrite(S). Instead, the more primitive, non-buffered
routines such as open(S) should be used. Unexpected results
may occur in processes that do buffering in the user address
space. The process may later read/write data which is or
was locked.
Page 3 (printed 8/7/87)