lockf.2 (2010 09)

l
lockf(2) lockf(2)
NAME
lockf - provide semaphores and record locking on files
SYNOPSIS
#include <unistd.h>
int lockf(int fildes, int function, off_t size);
DESCRIPTION
The lockf() function allows regions of a file to be used as semaphores (advisory locks) or restricts
access to only the locking process (enforcement-mode record locks). Other processes that attempt to
access the locked resource either return an error or sleep until the resource becomes unlocked. All locks
for a process are released upon the first close of the file, even if the process still has the file opened, and
all locks held by a process are released when the process terminates.
fildes is an open file descriptor. The file descriptor must have been opened with write-only permission
(
O_WRONLY) or read-write permission (O_RDWR
) in order to establish a lock with this function call (see
open(2)).
If the calling process is a member of a group that has the
PRIV_LOCKRDONLY
privilege (see get-
privgrp (2)), it can also use
lockf() to lock files opened with read-only permission (
O_RDONLY).
function is a control value that specifies the action to be taken. Permissible values for function are
defined in
<unistd.h> as follows:
#define F_ULOCK 0 /* unlock a region */
#define F_LOCK 1 /* lock a region */
#define F_TLOCK 2 /* test and lock a region */
#define F_TEST 3 /* test region for lock */
All other values of function are reserved for future extensions and result in an error return if not imple-
mented.
F_TEST is used to detect whether a lock by another process is present on the specified region.
lockf()
returns zero if the region is accessible and −1 if it is not; in which case
errno is set to [EACCES].
F_LOCK and F_TLOCK both lock a region of a file if the region is available. F_ULOCK
removes locks
from a region of the file.
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 for a positive size, and backward for a negative size (the
preceding bytes up to but not including the current offset). If size is zero, the region from the current
offset through the end of the largest possible file is locked (that is, from the current offset through the
present or any future end-of-file). An area need not be allocated to the file in order to be locked, because
such locks can exist past the end of the file.
Regions locked with
F_LOCK or F_TLOCK can, in whole or in part, contain or be contained by a previ-
ously locked region for the same process. When this occurs or if adjacent regions occur, the regions are
combined into a single region. If the request requires that a new element be added to the table of active
locks but the table is already full, an error is returned, and the new region is not locked.
F_LOCK and F_TLOCK requests differ only by the action taken if the resource is not available: F_LOCK
causes the calling process to sleep until the resource is available, whereas F_TLOCK returns an
[EACCES] error if the region is already locked by another process.
F_ULOCK requests can, in whole or part, release one or more locked regions controlled by the process.
When regions are not fully released, the remaining regions are still locked by the process. Releasing the
center section of a locked region requires an additional element in the table of active locks. If this table is
full, an [EDEADLK] error is returned, and the requested region is not released.
Regular files with the file mode of
S_ENFMT, not having the group execute bit set, will have an enforce-
ment policy enabled. With enforcement enabled, reads and writes that would access a locked region sleep
until the entire region is available if O_NDELAY is clear, but return −1 with errno set if O_NDELAY is
set. File access by other system functions, such as exec(), are not subject to the enforcement policy.
Locks on directories, pipes, and special files are advisory only; no enforcement policy is used.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1