FLOCK(2) BSD Programmer's Manual FLOCK(2)NAME
flock - apply or remove an advisory lock on an open file
SYNOPSIS
#include <fcntl.h>
int
flock(int fd, int operation);
DESCRIPTIONFlock() applies or removes an advisory lock on the file associated with
the file descriptor fd. The operation parameter is created from the or'd
operation bit masks defined in <fcntl.h>:
#define LOCK_SH 0x01 /* shared file lock */
#define LOCK_EX 0x02 /* exclusive file lock */
#define LOCK_NB 0x04 /* don't block when locking */
#define LOCK_UN 0x08 /* unlock file */
A lock is applied by specifying either LOCK_SH or LOCK_EX with the op-
tional inclusion of LOCK_NB. To unlock an existing lock, operation should
be LOCK_UN.
Advisory locks allow cooperating processes to perform consistent opera-
tions on files, but do not guarantee consistency (i.e., processes may
still access files without using advisory locks possibly resulting in in-
consistencies).
The locking mechanism allows two types of locks: shared locks and
exclusive locks. At any time multiple shared locks may be applied to a
file, but at no time are multiple exclusive, or both shared and exclu-
sive, locks allowed simultaneously on a file.
A shared lock may be upgraded to an exclusive lock, and vice versa, sim-
ply by specifying the appropriate lock type; this results in the previous
lock being released and the new lock applied (possibly after other pro-
cesses have gained and released the lock).
Requesting a lock on an object that is already locked normally causes the
caller to be blocked until the lock may be acquired. If LOCK_NB is in-
cluded in operation, then this will not happen; instead the call will
fail and the error EWOULDBLOCK will be returned.
NOTES
Locks are on files, not file descriptors. That is, file descriptors du-
plicated through dup(2) or fork(2) do not result in multiple instances of
a lock, but rather multiple references to a single lock. If a process
holding a lock on a file forks and the child explicitly unlocks the file,
the parent will lose its lock.
Processes blocked awaiting a lock may be awakened by signals.
RETURN VALUES
Zero is returned if the operation was successful; on an error a -1 is re-
turned and an error code is left in the global location errno.
ERRORS
The flock() call fails if:
[EWOULDBLOCK] The file is locked and the LOCK_NB option was specified.
[EBADF] The argument fd is an invalid descriptor.
[EINVAL] The argument fd refers to an object other than a file.
SEE ALSOopen(2), close(2), dup(2), execve(2), fork(2)HISTORY
The flock function call appeared in 4.2BSD.
4.2 Berkeley Distribution December 11, 1993 2