.\" @(#)lockf.3 1.1 86/09/25 SMI; created 4/30/86
.TH LOCKF 3 "9 March 1987"
.UC N2
.SH NAME
lockf \- advisory record locking on files
.SH SYNOPSIS
.nf
.ft B
#include <sys/types.h>
#include <unistd.h>

.ta +1.5i +0.4i
#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 (non-blocking) */
#define F_TEST	3	/* Test section for other process' locks */

int lockf(int \fIfd\fP, int \fIcmd\fP, off_t \fIsize\fP)
.SH DESCRIPTION
.B Lockf
may be used to test, apply, or remove an
.I advisory
record lock on the file associated with the open descriptor \fIfd\fP.
(See \fBfcntl\fP(2) for more information about advisory record locking.)
.PP
A lock is obtained by specifying a
.I cmd
parameter of F_LOCK or F_TLOCK.  To unlock
an existing lock, the F_ULOCK
.I cmd
is used.  F_TEST is used to detect if a lock by another
process is present on the specified segment.
.PP
F_LOCK and F_TLOCK requests differ only by the action taken
if the lock may not be immediately granted.  F_TLOCK will cause
the function to return a -1 and set \fBerrno\fP to EAGAIN
if the section is already locked by another process.  F_LOCK
will cause the process to sleep until the lock may be granted or
a signal is caught.
.PP
\fISize\fP is the number of contiguous bytes to be locked or unlocked.
The lock starts at the current file offset in the file and extends
forward for a positive \fIsize\fP or backward for a negative \fIsize\fP
(preceeding but not including the current offset).  A segment need not
be allocated to the file in order to be locked;  however, a segment may not
extend to a negative offset relative to the beginning of the file.
If \fIsize\fP is
zero, the lock will extend from the current offset through the end-of-file.
If such a lock starts at offset 0, then the entire file will be locked
(regardless of future file extensions).
.SH NOTES
The descriptor \fIfd\fP must have been opened with O_WRONLY or
O_RDWR permission in order to establish locks with this function call.
.PP
All locks associated with a file for a given process are removed
when the file is closed or the process terminates.  Locks are not
inherited by the child process in a \fBfork\fP(2) system call.
.PP
No deadlock detection is performed by this library or by \fBfcntl\fP(2).
If two processes have locked areas that the other process is waiting for,
the processes will wait forever for their lock.
.SH "RETURN VALUE
Zero is returned on success, \-1 on error,
with an error code stored in \fBerrno\fP.
.SH "ERRORS
\fBLockf\fP will fail if one or more of the following are true:
.TP 15
[EBADF]
.I Fd
is not a valid open descriptor.
.TP 15
[EBADF]
.I Cmd
is F_LOCK or F_TLOCK and the process does
not have write permission on the file.
.TP 15
[EINVAL]
Either the current file offset and/or
.I size
have a value out of range for the given file, or
.I cmd
is not one of those specified above.
.TP 15
[EAGAIN]
.I Cmd
is F_TLOCK or F_TEST and the section is already locked by another process.
.TP 15
[EINTR]
.I Cmd
is F_LOCK or F_TEST and a signal interrupted the process while it was waiting
for a reply from the lock manager.
.TP 15
[ENOLCK]
There are no more file lock entries available.
.SH "SEE ALSO"
.BR fcntl (2).