|
Advisory locking
F_GETLK, F_SETLK and F_SETLKW are used to acquire, release, and test for the exis-
tence of record locks (also known as file-segment or file-region locks). The third
argument lock is a pointer to a structure that has at least the following fields
(in unspecified order).
struct flock {
...
short l_type; /* Type of lock: F_RDLCK,
F_WRLCK, F_UNLCK */
short l_whence; /* How to interpret l_start:
SEEK_SET, SEEK_CUR, SEEK_END */
off_t l_start; /* Starting offset for lock */
off_t l_len; /* Number of bytes to lock */
pid_t l_pid; /* PID of process blocking our lock
(F_GETLK only) */
...
};
The l_whence, l_start, and l_len fields of this structure specify the range of
bytes we wish to lock. l_start is the starting offset for the lock, and is inter-
preted relative to either: the start of the file (if l_whence is SEEK_SET); the
current file offset (if l_whence is SEEK_CUR); or the end of the file (if l_whence
is SEEK_END). In the final two cases, l_start can be a negative number provided
the offset does not lie before the start of the file. l_len is a non-negative
integer (but see the NOTES below) specifying the number of bytes to be locked.
Bytes past the end of the file may be locked, but not bytes before the start of the
file. Specifying 0 for l_len has the special meaning: lock all bytes starting at
the location specified by l_whence and l_start through to the end of file, no mat-
ter how large the file grows.
The l_type field can be used to place a read (F_RDLCK) or a write (F_WRLCK) lock on
a file. Any number of processes may hold a read lock (shared lock) on a file
region, but only one process may hold a write lock (exclusive lock). An exclusive
lock excludes all other locks, both shared and exclusive. A single process can
hold only one type of lock on a file region; if a new lock is applied to an
already-locked region, then the existing lock is converted to the new lock type.
(Such conversions may involve splitting, shrinking, or coalescing with an existing
lock if the byte range specified by the new lock does not precisely coincide with
the range of the existing lock.)
F_SETLK
Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when
l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and
l_len fields of lock. If a conflicting lock is held by another process,
this call returns -1 and sets errno to EACCES or EAGAIN.
F_SETLKW
As for F_SETLK, but if a conflicting lock is held on the file, then wait for
that lock to be released. If a signal is caught while waiting, then the
call is interrupted and (after the signal handler has returned) returns
immediately (with return value -1 and errno set to EINTR).
immediately (with return value -1 and errno set to EINTR).
F_GETLK
On input to this call, lock describes a lock we would like to place on the
file. If the lock could be placed, fcntl() does not actually place it, but
returns F_UNLCK in the l_type field of lock and leaves the other fields of
the structure unchanged. If one or more incompatible locks would prevent
this lock being placed, then fcntl() returns details about one of these
locks in the l_type, l_whence, l_start, and l_len fields of lock and sets
immediately (with return value -1 and errno set to EINTR).
F_GETLK
On input to this call, lock describes a lock we would like to place on the
file. If the lock could be placed, fcntl() does not actually place it, but
returns F_UNLCK in the l_type field of lock and leaves the other fields of
the structure unchanged. If one or more incompatible locks would prevent
this lock being placed, then fcntl() returns details about one of these
locks in the l_type, l_whence, l_start, and l_len fields of lock and sets
l_pid to be the PID of the process holding that lock.
In order to place a read lock, fd must be open for reading. In order to place a
write lock, fd must be open for writing. To place both types of lock, open a file
read-write.
As well as being removed by an explicit F_UNLCK, record locks are automatically
released when the process terminates or if it closes any file descriptor referring
to a file on which locks are held. This is bad: it means that a process can lose
the locks on a file like /etc/passwd or /etc/mtab when for some reason a library
function decides to open, read and close it.
Record locks are not inherited by a child created via fork(2), but are preserved
across an execve(2).
Because of the buffering performed by the stdio(3) library, the use of record lock-
ing with routines in that package should be avoided; use read(2) and write(2)
instead. | 