mirror of https://github.com/mkerrisk/man-pages
140 lines
3.6 KiB
Groff
140 lines
3.6 KiB
Groff
.\" Copyright 1997 Nicolás Lichtmaier <nick@debian.org>
|
|
.\" Created Thu Aug 7 00:44:00 ART 1997
|
|
.\"
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
.\" the License, or (at your option) any later version.
|
|
.\"
|
|
.\" The GNU General Public License's references to "object code"
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
.\" document formatting or typesetting system, including
|
|
.\" intermediate and printed output.
|
|
.\"
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" Added section stuff, aeb, 2002-04-22.
|
|
.\" Corrected include file, drepper, 2003-06-15.
|
|
.\"
|
|
.TH LOCKF 3 2007-07-26 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
lockf \- apply, test or remove a POSIX lock on an open file
|
|
.SH SYNOPSIS
|
|
.B #include <unistd.h>
|
|
.sp
|
|
.BI "int lockf(int " fd ", int " cmd ", off_t " len );
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR lockf ():
|
|
_BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500
|
|
.SH DESCRIPTION
|
|
Apply, test or remove a POSIX lock on a section of an open file.
|
|
The file is specified by
|
|
.IR fd ,
|
|
a file descriptor open for writing, the action by
|
|
.IR cmd ,
|
|
and the section consists of byte positions
|
|
.IR pos .. pos + len \-1
|
|
if
|
|
.I len
|
|
is positive, and
|
|
.IR pos \- len .. pos \-1
|
|
if
|
|
.I len
|
|
is negative, where
|
|
.I pos
|
|
is the current file position, and if
|
|
.I len
|
|
is zero, the section extends from the current file position to
|
|
infinity, encompassing the present and future end-of-file positions.
|
|
In all cases, the section may extend past current end-of-file.
|
|
.LP
|
|
On Linux, this call is just an interface for
|
|
.BR fcntl (2).
|
|
(In general, the relation between
|
|
.BR lockf ()
|
|
and
|
|
.BR fcntl (2)
|
|
is unspecified.)
|
|
.LP
|
|
Valid operations are given below:
|
|
.TP
|
|
.B F_LOCK
|
|
Set an exclusive lock on the specified section of the file.
|
|
If (part of) this section is already locked, the call
|
|
blocks until the previous lock is released.
|
|
If this section overlaps an earlier locked section,
|
|
both are merged.
|
|
File locks are released as soon as the process holding the locks
|
|
closes some file descriptor for the file.
|
|
A child process does not inherit these locks.
|
|
.TP
|
|
.B F_TLOCK
|
|
Same as
|
|
.B F_LOCK
|
|
but the call never blocks and returns an error instead if the file is
|
|
already locked.
|
|
.TP
|
|
.B F_ULOCK
|
|
Unlock the indicated section of the file.
|
|
This may cause a locked section to be split into two locked sections.
|
|
.TP
|
|
.B F_TEST
|
|
Test the lock: return 0 if the specified section
|
|
is unlocked or locked by this process; return \-1, set
|
|
.I errno
|
|
to
|
|
.B EAGAIN
|
|
.RB ( EACCES
|
|
on some other systems),
|
|
if another process holds a lock.
|
|
.SH "RETURN VALUE"
|
|
On success, zero is returned.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.BR EACCES " or " EAGAIN
|
|
The file is locked and
|
|
.B F_TLOCK
|
|
or
|
|
.B F_TEST
|
|
was specified, or the operation is prohibited because the file has
|
|
been memory-mapped by another process.
|
|
.TP
|
|
.B EBADF
|
|
.I fd
|
|
is not an open file descriptor.
|
|
.TP
|
|
.B EDEADLK
|
|
The command was
|
|
.B T_LOCK
|
|
and this lock operation would cause a deadlock.
|
|
.TP
|
|
.B EINVAL
|
|
An invalid operation was specified in
|
|
.IR fd .
|
|
.TP
|
|
.B ENOLCK
|
|
Too many segment locks open, lock table is full.
|
|
.SH "CONFORMING TO"
|
|
SVr4, POSIX.1-2001.
|
|
.SH "SEE ALSO"
|
|
.BR fcntl (2),
|
|
.BR flock (2)
|
|
.br
|
|
There are also
|
|
.I locks.txt
|
|
and
|
|
.I mandatory.txt
|
|
in
|
|
.IR /usr/src/linux/Documentation .
|