lockf(3)lockf(3)NAMElockf - Lock and unlocks regions of open file descriptors
SYNOPSIS
#include <unistd.h>
int lockf(
int filedes,
int request,
off_t size );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
lockf(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the file to which the lock is to be applied or removed. The
file descriptor is returned by a successful open() or fcntl() function.
Specifies one of the following constants for the lockf() function:
Unlocks a previously locked region in the file. 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. Same as F_LOCK, except that the request returns an error if the
region overlaps a locked region. Tests to see if another process has
already locked a region. The lockf() function returns 0 (zero) if the
region is unlocked. If the region is locked, then -1 is returned and
errno is set to [EACCES]. The number of bytes to be locked or unlocked
for the lockf() function. The region starts at the current location in
the open file and extends forward if size is positive and backward
ifsize is negative. If the size parameter is 0 (zero), the region
starts at the current location and extends forward to the maximum pos‐
sible file size, including the unallocated space after the end of the
file.
DESCRIPTION
The lockf() function locks and unlocks sections of an open file. Unlike
the fcntl() function, however, its interface is limited to setting only
write (exclusive) locks.
Although the lockf() and fcntl() functions are different, the implemen‐
tations are fully integrated. Therefore, locks obtained from one func‐
tion are honored and enforced by the other lock function.
Each lock is either an enforced lock or an advisory lock, and must also
be either a read lock or a write lock.
Locks on a file are advisory or enforced depending on the mode of the
file (see the chmod() function.) A given file can have advisory or
enforced locks, but not both. See the sys/mode.h header file for a
description of file attributes.
When a process holds an enforced exclusive lock on a section of a file,
no other process can access that section of the file with theread() or
write() functions. In addition, the open(), truncate(), and ftruncate()
functions cannot truncate the locked section of the file. If another
process attempts to read or modify the locked section of the file, it
sleeps until the section is unlocked or returns with an error indica‐
tion.
The file descriptor on which an exclusive lock is being placed must
have been opened with write access.
Some general rules about file locking include the following: Changing
or unlocking part of a file in the middle of a locked section leaves
two smaller sections locked at each end of the originally locked sec‐
tion. All locks associated with a file for a given process are removed
when the process closes any file descriptor for that file. Locks are
not inherited by a child process after running a fork() function.
Locks can start and extend beyond the current end of a file, but cannot
be negative relative to the beginning of the file. A lock can be set to
extend to the end of the file by setting the l_len field to 0 (zero).
If a lock is specified with the l_start field set to 0 and the l_whence
field set to SEEK_SET, the whole file is locked.
Advisory file region locking is supported over NFS, provided the lock‐
ing daemon (rpc.lockd) and status monitor daemon (rpc.statd) are run‐
ning.
NOTES
Buffered I/O does not work properly when used with file locking. Do not
use the standard I/O package routines on files that will be locked.
Deadlocks due to file locks in a distributed system are not always
detected. When such deadlocks are possible, the programs requesting
the locks should set time-out timers.
RETURN VALUES
Upon successful completion, a value of 0 (zero) is returned. Otherwise,
a value of -1 is returned and errno is set to indicate the error.
ERRORS
If the lockf() function fails, errno may be set to one of the following
values: The file region is locked and F_TEST was specified; or the file
region is locked and F_TLOCK was specified. The filedes parameter is
not a valid open file descriptor; or the request parameter is F_LOCK or
F_TLOCK and filedes is not a valid file descriptor open for writing.
The lock is blocked by some lock from another process. Putting the
calling process to sleep while waiting for that lock to become free
would cause a deadlock. The request parameter is F_TLOCK and the
lockf() function was interrupted by a signal which was caught. The
request parameter is not valid or size plus the current file offset is
less than 0 (zero). The request parameter is F_LOCK, F_TLOCK, or
F_UNLOCK and satisfying the lock or unlock request would exceed the
configurable system limit of NLOCK_RECORD.
[Tru64 UNIX] If using NFS, the server is out of resources or
the file handle is stale.
SEE ALSO
Functions: chmod(2), close(2), exec(2), fcntl(2), flock(2), fork(2),
open(2), read(2), write(2)
Commands: rpc.lockd(8), rpc.statd(8)
Standards: standards(5)lockf(3)
