lockf
Purpose
Locks a region of a file for exclusive access.
Syntax
#include <sys/lockf.h>
int lockf (fildes, request, size)
int fildes, request;
off_t size;
Description
The lockf system call locks and unlocks regions of an
open file. If Distributed Services is installed on your
system, this file can reside on another node. lockf is
used to synchronize simultaneous access to a file by mul-
tiple processes. Only one process at a time can hold a
lock on any given region of a file. Two types of locks
are provided: enforced and advisory.
When a process holds an enforced lock on a region of a
file, no other process can access that region with the
read or write system calls. In addition, creat and open
are prevented from truncating the file. If another
process attempts to read or write the region, then it
sleeps until the region is unlocked. However, if the
system detects that sleeping would cause deadlock, then
the read or write system call fails, setting errno to
EDEADLK. If another process attempts to truncate the
file with either the creat or open system call, then that
system call fails and sets errno to EACCES.
When a process holds an advisory lock on a region of a
file, no other process can lock that region, or an over-
lapping region, with lockf. The read, write, creat, and
open system calls are not affected. This means that
processes must voluntarily call lockf in order to make
advisory locks effective.
Warning: Buffered I/O does not work properly when used
with file locking. In particular, do not use the
Standard I/O Library (libc.a) routines on files that are
going to be locked, since these routines use buffered
I/O.
To select enforced locking, the S_ENFMT bit must be set
in the access permission code (or mode) of the file.
Otherwise locking is advisory. Thus, a given file can
have advisory or enforced locks, but not both.
The fildes parameter to lockf is an open file descriptor
obtained from a successful call to open, creat, dup, or
pipe system call.
The size parameter is the number of bytes to be locked or
unlocked. The region starts at the current location in
the open file and extends forward if size is positive, or
backward if size is negative. If the size parameter is
0, then the region starts at the current location and
extends forward to the maximum possible file size,
including the unallocated space after the end-of-file.
Unallocated "holes" in the file can also be locked. (See
"fclear" about "holes" in files.)
The request parameter is one of the following constants:
F_ULOCK Unlocks a previously locked region in the
file.
F_LOCK Locks the region for exclusive use. This
request causes the calling process to sleep if
the region overlaps a locked region, and to
resume when it is granted the lock.
F_TLOCK Tests to see if another process has locked the
specified region, and, if not, locks the
region for exclusive use. If the region is
already locked, then lockf fails and sets
errno to EACCES.
F_TEST Tests to see if another process has already
locked a region. lockf returns 0 if the
region is unlocked. If the region is locked,
then -1 is returned and errno is set to
EACCES.
The system keeps a table of the locked regions for each
file. This table can hold a limited number of entries.
When the same process locks two regions that are next to
each other in the file, lockf combines the lock table
entries to conserve space in the lock table. An unlock
request in the middle of a locked region leaves two
locked regions, which can cause the lock table to over-
flow. When a lock or unlock request cannot be satisfied
because the lock table is full, the lockf subroutine
fails.
When a process closes a file, all of its locks on that
file are removed. When a process terminates, all of the
locks that it holds are removed.
All locks applied to directories, special files, and
pipes are treated as advisory locks. However, locking
directories is not recommended. Only advisory locks are
supported for mapped files. An attempt to apply an
enforced lock to a mapped file causes the lockf system
call to fail and set errno to EMFILE. (For information
about mapped files, see "shmat.")
A child process does not inherit the locks of its parent
process.
Notes:
1. Locks may be set by fcntl in addition to lockf.
2. The lockf system call sets only write (exclusive)
locks.
3. When using Distributed Services, deadlocks due to
file locks are not always detected. When such dead-
locks are possible, the programs requesting the locks
should set timeout timers.
Return Value
Upon successful completion, lockf returns a value of 0.
If lockf fails, a value of -1 is returned and errno is
set to indicate the error.
Diagnostics
The lockf system call fails if one or more of the fol-
lowing are true:
EBADF fildes is not a valid open file descriptor.
EINVAL request is not valid.
EACCES F_TEST or F_TLOCK fails because another
process has already locked the region.
Note: Because in the future, errno may be
set to EAGAIN rather than to EACCES for the
error described above, programs should
expect and test for both values.
EMFILE The file is mapped and enforced locking is
enabled.
EDEADLK Deadlock will occur or the lock table is
full. Deadlocks are not always detected
when remotely mounted files are locked.
If Distributed Services is installed on your system,
lockf can also fail if one or more of the following are
true:
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EAGAIN The server is too busy to accept the
request.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "close," "creat," "dup," "fcntl.h,"
"open," "read, readx," "write, writex," and "standard
i/o library."