100 lines
4.8 KiB
Groff
100 lines
4.8 KiB
Groff
|
|
NAME
|
|
lockf - record locking on files
|
|
SYNTAX
|
|
# include <unistd.h>
|
|
lockf (fildes, function, size) long size; int fildes,
|
|
function;
|
|
DESCRIPTION
|
|
The lockf command will allow sections of a file to be locked
|
|
(advisory write locks). (Mandatory or enforcement mode
|
|
record locks are not currently available.) Locking calls
|
|
from other processes which attempt to lock the locked file
|
|
section will either return an error value or be put to sleep
|
|
until the resource becomes unlocked. All the locks for a
|
|
process are removed when the process terminates. See
|
|
fcntl(2) for more information about record locking.
|
|
Fildes is an open file descriptor. The file descriptor must
|
|
have O_WRONLY or O_RDWR permission in order to establish
|
|
lock with this function call.
|
|
Function is a control value which specifies the action to be
|
|
taken. The permissible values for function 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 for exclusive use */
|
|
#define F_TEST 3 /* Test section for other processes locks */
|
|
All other values of function are reserved for future
|
|
extensions and will result in an error return if not
|
|
implemented.
|
|
F_TEST is used to detect if a lock by another process is
|
|
present on the specified section. F_LOCK and F_TLOCK both
|
|
lock a section of a file if the section is available.
|
|
F_UNLOCK removes locks from a section 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
|
|
section from the current offset through the largest file
|
|
offset is locked (i.e., 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, as such locks
|
|
may exist past the end-of-file.
|
|
|
|
The sections locked with F_LOCK or F_TLOCK may, in whole or
|
|
in part, contain or be contained by a previously locked
|
|
section for the same process. When this occurs, or if
|
|
adjacent sections occur, the sections are combined into a
|
|
single section. If the request requires that a new element
|
|
be added to the table of active locks and this table is
|
|
already full, an error is returned, and the new section is
|
|
not locked.
|
|
F_LOCK and F_TLOCK requests differ only by the action taken
|
|
if the resource is not available. F_LOCK will cause the
|
|
calling process to sleep until the resource is available.
|
|
F_TLOCK will cause the function to return a -1 and set errno
|
|
to [EACCESS] error if the section is already locked by
|
|
another process.
|
|
F_ULOCK requests may, in whole or in part, release one or
|
|
more locked sections controlled by the process. When
|
|
sections are not fully released, the remaining sections are
|
|
still locked by the process. Releasing the center section
|
|
of a locked section requires an additional element in the
|
|
table of active locks. If this table is full, an [EDEADLK]
|
|
error is returned and the requested section is not released.
|
|
A potential for deadlock occurs if a process controlling a
|
|
locked resource is put to sleep by accessing another
|
|
process's locked resource. Thus calls to lock or fcntl scan
|
|
for a deadlock prior to sleeping on a locked resource. An
|
|
error return is made if sleeping on the locked resource
|
|
would cause a deadlock.
|
|
Sleeping on a resource is interrupted with any signal. The
|
|
alarm(2) command may be used to provide a timeout facility
|
|
in applications which require this facility.
|
|
The lockf utility will fail if one or more of the following
|
|
are true:
|
|
[EBADF]
|
|
Fildes is not a valid open descriptor.
|
|
[EACCESS]
|
|
Cmd is F_TLOCK or F_TEST and the section is already
|
|
locked by another process.
|
|
[EDEADLK]
|
|
Cmd is F_LOCK or F_TLOCK and a deadlock would occur.
|
|
Also the cmd is either of the above or F_ULOCK and the
|
|
number of entries in the lock table would exceed the
|
|
number allocated on the system.
|
|
SEE ALSO
|
|
alarm(2), close(2), creat(2), fcntl(2), intro(2), open(2),
|
|
read(2), write(2).
|
|
RETURN VALUE
|
|
Upon successful completion, a value of 0 is returned.
|
|
Otherwise, a value of -1 is returned and errno is set to
|
|
indicate the error.
|
|
CAVEATS
|
|
Unexpected results may occur in processes that do buffering
|
|
in the user address space. The process may later read/write
|
|
data which is/was locked. The standard I/O package is the
|
|
most common source of unexpected buffering.
|
|
|