LOCKF(3) Library Functions Manual LOCKF(3)
lockf - record locking on files
int lockf(fd, cmd, size)
int fd, cmd;
lockf() places, removes, and tests for exclusive locks on sections of
files. These locks are either advisory or mandatory depending on the
mode bits of the file. The lock is mandatory if the set-GID bit
(S_ISGID) is set and the group execute bit (S_IXGRP) is clear (see
stat(2V) for information about mode bits). Otherwise, the lock is
If a process holds a mandatory exclusive lock on a segment of a file,
both read and write operations block until the lock is removed (see
An advisory lock does not affect read and write access to the locked
segment. Advisory locks may be used by cooperating processes checking
for locks using F_GETLCK and voluntarily observing the indicated read
and write restrictions.
A locking call on an already locked file section fails, returning an
error value or putting the call to sleep until that file section is
unlocked. All the locks on a process are removed when that process
terminates. See fcntl(2V) for more information about record locking.
fd is an open file descriptor. It must have O_WRONLY or O_RDWR permis-
sion for a successful locking call.
cmd is a control value which specifies the action to be taken. The
accepted values for cmd are defined in <<unistd.h>> as follows:
#define F_ULOCK 0 /* Unlock a previously locked section */
#define F_LOCK 1 /* Lock a section for exclusive use */
#define F_TLOCK 2 /* Test and lock a section (non-blocking) */
#define F_TEST 3 /* Test section for other process' locks */
F_TEST returns -1 and sets errno to EACCES if a lock by another process
already exists on the specified section. Otherwise, it returns 0.
F_LOCK and F_TLOCK lock available file sections. F_ULOCK removes locks
from file sections.
All other values of cmd are reserved for future applications and, until
implemented, return an error.
size is the number of contiguous bytes to be locked or unlocked. The
resource to be locked starts at the current offset in the file and
extends forward size bytes if size is positive, and extends backward
size bytes (the preceding bytes up to but not including the current
offset) if size is negative. If size is zero, the section from the
current offset through the largest file offset is locked (that is, from
the current offset through the present or any future EOF). An area
need not be allocated to the file to be locked, such a lock may exist
after the EOF.
Sections locked with F_LOCK or F_TLOCK may contain all or part of an
already locked section. They may also be partially or completely con-
tained by an already locked section. Where these overlapping or adja-
cent locked sections occur, they are combined into a single section.
If the table of active locks is full, a lock request requiring an addi-
tional table entry fails and an error value is returned.
F_LOCK and F_TLOCK differ only in their response to requests for
unavailable resources. If a section is already locked, F_LOCK directs
the calling process to sleep until the resource is available, F_TLOCK
directs the function to return -1 and set errno to EACCES (see ERRORS).
When a F_ULOCK request releases part of a section with overlapping
locks, the remaining section or sections retain the lock. If F_ULOCK
removes the center of a locked section, the two separate locked sec-
tions remain, but an additional element is required in the table of
active locks. If this table is full, errno is set to ENOLCK and the
requested section is not released.
The danger of a deadlock exists when a process controlling a locked
resource is put to sleep by requesting an unavailable resource. To
avoid this danger, lockf() and fcntl() scan for this conflict before
putting a locked resource to sleep. If a deadlock would result, an
error value is returned.
The sleep process can be interrupted with any signal. alarm(3V) may be
used to provide a timeout facility where needed.
0 on success.
-1 on failure and sets errno to indicate the error.
EACCES cmd is F_TLOCK or F_TEST and the section is already
locked by another process.
Note: In future, lockf() may generate EAGAIN under these
conditions, so applications testing for EACCES should
also test for EAGAIN.
EBADF fd is not a valid open descriptor.
cmd is F_LOCK or F_TLOCK and the process does not have
write permission on the file.
EDEADLK cmd is F_LOCK and a deadlock would occur.
EINTR cmd is F_LOCK and a signal interrupted the process while
it was waiting to complete the lock.
ENOLCK cmd is F_LOCK, F_TLOCK, or F_ULOCK and there are no more
file lock entries available.
chmod(2V), fcntl(2V), flock(2), fork(2V), alarm(3V), lockd(8C)
Mandatory record locks are dangerous. If a runaway or otherwise out-
of-control process should hold a mandatory lock on a file critical to
the system and fail to release that lock, the entire system could hang
or crash. For this reason, mandatory record locks may be removed in a
future SunOS release.n Use advisory record locking whenever possible.
A child process does not inherit locks from its parent on fork(2V).
lockf() locks do not interact in any way with locks granted by flock(),
but are compatible with locks granted by fcntl().
21 January 1990 LOCKF(3)