lockf(3C) lockf(3C)
NAME
lockf, lockf64 - lock file records
SYNOPSIS
#include <unistd.h>
int lockf(int fildes, int function, offt size);
int lockf64(int fildes, int function, off64t 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.
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 previously locked section */
#define FLOCK 1 /* lock section for exclusive use */
#define FTLOCK 2 /* test & lock section for exclusive use */
#define FTEST 3 /* test section for other 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 determine 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 nega-
tive 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 point of the
offset through size bytes or to the end of file if size is 0. When
Page 1 Reliant UNIX 5.44 Printed 11/98
lockf(3C) lockf(3C)
this situation occurs in the present section or in adjacent ones, the
sections are combined to form one 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 addi-
tional 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.
An FULOCK request in which size is non-zero and the offset of the
last byte of the requested section is the maximum value for an object
of type offt, when the process has an existing lock in which size is
0 and which includes the last byte of the requested section, will be
treated as a request to unlock from the start of the requested section
with a size equal to 0. Otherwise an FULOCK request will attempt to
unlock only the requested section.
A potential for deadlock occurs if a process controlling a locked
resource is put to sleep by requesting another process' locked
resource. Thus calls to lockf() or fcntl() scan for possible deadlocks
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()
system call may be used to provide a timeout facility in applications
that require this facility.
The interaction between fcntl() and lockf() locks is unspecified.
Blocking on a section is interrupted by any signal.
There is no functional difference between lockf() and lockf64(),
except for the interpretation of off64t [see lfs(5)].
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
lockf() will fail if one or more of the following are true:
EBADF fildes is not a valid open descriptor.
Page 2 Reliant UNIX 5.44 Printed 11/98
lockf(3C) lockf(3C)
EACCES or EAGAIN
function is FTLOCK or FTEST and the section is already
locked by another process.
EDEADLK function is FLOCK and a deadlock would occur.
ENOLK function is FLOCK, FTLOCK, or FULOCK and the number of
entries in the lock table would exceed the number allo-
cated on the system.
ECOMM fildes is on a remote machine and the link to that machine
is no longer active.
EINTR A signal was caught during execution of the function.
The lockf() function may fail if:
EAGAIN The function argument is FLOCK or FTLOCK and the file is
mapped with mmap().
EDEADLK or ENOLCK
The function argument is FLOCK, FTLOCK, or FULOCK, and
the request would cause the number of locks to exceed a
system-imposed limit.
EOPNOTSUPP or EINVAL
The implementation does not support the locking of files
of the type indicated by the fildes argument.
EINVAL The function argument is not one of FLOCK, FTLOCK,
FTEST or FULOCK; or size plus the current file offset is
less than 0.
EOVERFLOW The offset of the first, or if size is not 0 then the
last, byte in the requested section cannot be represented
correctly in an object of type offt.
RESULT
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 or write data that is
or was locked. The standard I/O package is the most common reason for
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 pro-
cess, portable application programs should expect and test for either
value.
Page 3 Reliant UNIX 5.44 Printed 11/98
lockf(3C) lockf(3C)
SEE ALSO
alarm(2), chmod(2), close(2), creat(2), fcntl(2), open(2), read(2),
write(2), unistd(4), lfs(5).
Page 4 Reliant UNIX 5.44 Printed 11/98