lockf(3C) (C Programming Language Utilities) lockf(3C)
NAME
lockf - record locking on files
SYNOPSIS
#include <unistd.h>
int lockf (int fildes, int function, long size);
DESCRIPTION
lockf allows sections of a file to be locked; advisory or mandatory
write locks depending on the mode bits of the file [see chmod(2)].
Locking calls from other processes that 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
OWRONLY or ORDWR permission in order to establish locks with this
function call.
function is a control value that specifies the action to be taken.
The permissible values for function are defined in <unistd.h> as
follows:
#define FULOCK 0 /* Unlock a previously locked section */
#define FLOCK 1 /* Lock a section for exclusive use */
#define FTLOCK 2 /* Test and lock a section for exclusive use */
#define FTEST 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.
FTEST is used to detect if a lock by another process is present on
the specified section. FLOCK and FTLOCK both lock a section of a
file if the section is available. FULOCK 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 or unlocked 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 FLOCK or FTLOCK may, in whole or in part,
contain or be contained by a previously locked section for the same
process. Locked sections will be unlocked starting at the the point
of the offset through size bytes or to the end of file if size is
8/91 Page 1
lockf(3C) (C Programming Language Utilities) lockf(3C)
(offt) 0. When this situation occurs, or if this situation occurs
in adjacent sections, 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.
FLOCK and FTLOCK requests differ only by the action taken if the
resource is not available. FLOCK will cause the calling process to
sleep until the resource is available. FTLOCK will cause the
function to return a -1 and set errno to EACCES if the section is
already locked by another process.
FULOCK 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 errno is set to ENOLK and the requested section is not
released.
A potential for deadlock occurs if a process controlling a locked
resource is put to sleep by requesting another process's locked
resource. Thus calls to lockf 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)
system call may be used to provide a timeout facility in applications
that require this facility.
lockf will fail if one or more of the following are true:
EBADF fildes is not a valid open descriptor.
EAGAIN cmd is FTLOCK or FTEST and the section is already locked by
another process.
EDEADLK
cmd is FLOCK and a deadlock would occur.
ENOLK cmd is FLOCK, FTLOCK, or FULOCK and the number of entries in
the lock table would exceed the number allocated on the
system.
ECOMM fildes is on a remote machine and the link to that machine is
no longer active.
SEE ALSO
intro(2), chmod(2), close(2), creat(2), fcntl(2), open(2), read(2),
write(2).
Page 2 8/91
lockf(3C) (C Programming Language Utilities) lockf(3C)
DIAGNOSTICS
Upon successful completion, a value of 0 is returned. Otherwise, a
value of -1 is returned and errno is set to indicate the error.
NOTES
Unexpected results may occur in processes that do buffering in the
user address space. The process may later read/write data that
is/was locked. The standard I/O package is the most common source of
unexpected buffering.
Because in the future the variable errno will be set to EAGAIN rather
than EACCES when a section of a file is already locked by another
process, portable application programs should expect and test for
either value.
8/91 Page 3