mirror of https://github.com/mkerrisk/man-pages
183 lines
4.5 KiB
Groff
183 lines
4.5 KiB
Groff
.\" Copyright 1997 Nicolás Lichtmaier <nick@debian.org>
|
|
.\" Created Thu Aug 7 00:44:00 ART 1997
|
|
.\"
|
|
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
|
|
.\" 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.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, see
|
|
.\" <http://www.gnu.org/licenses/>.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" Added section stuff, aeb, 2002-04-22.
|
|
.\" Corrected include file, drepper, 2003-06-15.
|
|
.\"
|
|
.TH LOCKF 3 2015-03-02 "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 ():
|
|
.ad l
|
|
.RS 4
|
|
_BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
|
|
_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
|
|
.RE
|
|
.ad
|
|
.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,
|
|
.BR lockf ()
|
|
is just an interface on top of
|
|
.BR fcntl (2)
|
|
locking.
|
|
Many other systems implement
|
|
.BR lockf ()
|
|
in this way, but note that POSIX.1 leaves the relationship between
|
|
.BR lockf ()
|
|
and
|
|
.BR fcntl (2)
|
|
locks unspecified.
|
|
A portable application should probably avoid mixing calls
|
|
to these interfaces.
|
|
.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; or
|
|
.I cmd
|
|
is
|
|
.B F_LOCK
|
|
or
|
|
.BR F_TLOCK
|
|
and
|
|
.I fd
|
|
is not a writable file descriptor.
|
|
.TP
|
|
.B EDEADLK
|
|
The command was
|
|
.B F_LOCK
|
|
and this lock operation would cause a deadlock.
|
|
.TP
|
|
.B EINVAL
|
|
An invalid operation was specified in
|
|
.IR cmd .
|
|
.TP
|
|
.B ENOLCK
|
|
Too many segment locks open, lock table is full.
|
|
.SH ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.TS
|
|
allbox;
|
|
lb lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR lockf ()
|
|
T} Thread safety MT-Safe
|
|
.TE
|
|
.SH CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008, SVr4.
|
|
.SH SEE ALSO
|
|
.BR fcntl (2),
|
|
.BR flock (2)
|
|
|
|
.I locks.txt
|
|
and
|
|
.I mandatory-locking.txt
|
|
in the Linux kernel source directory
|
|
.IR Documentation/filesystems
|
|
(on older kernels, these files are directly under the
|
|
.I Documentation
|
|
directory, and
|
|
.I mandatory-locking.txt
|
|
is called
|
|
.IR mandatory.txt )
|