lockf - Lock and unlocks regions of open file descriptors
#include <unistd.h>
int lockf(
int filedes,
int request,
off_t size );
Interfaces documented on this reference page conform to
industry standards as follows:
lockf(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
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 possible file size,
including the unallocated space after the end of the file.
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 implementations are fully integrated. Therefore, locks
obtained from one function 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 indication.
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 section. 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 locking daemon (rpc.lockd) and status monitor
daemon (rpc.statd) are running.
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.
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.
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.
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)
[ Back ] |
