2004-11-03 13:51:07 +00:00
|
|
|
|
.\" Copyright 1997 Nicol<6F>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.
|
|
|
|
|
.\"
|
_exit.2, brk.2, capget.2, chdir.2, chmod.2, chown.2, chroot.2, getdtablesize.2, gethostname.2, getpagesize.2, getsid.2, killpg.2, mknod.2, mknodat.2, poll.2, posix_fadvise.2, pread.2, readlink.2, setpgid.2, setreuid.2, sigaltstack.2, stat.2, symlink.2, sync.2, truncate.2, vfork.2, wait.2, wait4.2, a64l.3, abs.3, acos.3, acosh.3, asin.3, asinh.3, atan.3, atan2.3, atoi.3, cbrt.3, ceil.3, copysign.3, cosh.3, dirfd.3, div.3, ecvt.3, erf.3, erfc.3, exp.3, exp2.3, fabs.3, fdim.3, ffs.3, floor.3, fma.3, fmax.3, fmin.3, fmod.3, fpclassify.3, frexp.3, ftw.3, fwide.3, gcvt.3, getcwd.3, getdate.3, getgrent.3, gethostid.3, getpass.3, getpwent.3, getsubopt.3, getw.3, hypot.3, ilogb.3, index.3, isalpha.3, isgreater.3, iswblank.3, j0.3, ldexp.3, lockf.3, log.3, log10.3, log1p.3, logb.3, lrint.3, lround.3, mkstemp.3, mktemp.3, modf.3, mq_receive.3, mq_send.3, nan.3, nextafter.3, posix_fallocate.3, posix_memalign.3, printf.3, qecvt.3, random.3, realpath.3, remainder.3, remquo.3, rint.3, round.3, scalb.3, scalbln.3, scanf.3, siginterrupt.3, signbit.3, sigset.3, sinh.3, sqrt.3, strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strfry.3, strpbrk.3, strsep.3, strspn.3, strstr.3, strtod.3, strtok.3, strtol.3, strtoul.3, strxfrm.3, tanh.3, tgamma.3, trunc.3, ttyslot.3, ualarm.3, usleep.3, wprintf.3, armscii-8.7, cp1251.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-3.7, iso_8859-5.7, iso_8859-6.7, iso_8859-8.7, koi8-u.7: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-19 17:19:13 +00:00
|
|
|
|
.TH LOCKF 3 2010-09-20 "GNU" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.SH NAME
|
|
|
|
|
lockf \- apply, test or remove a POSIX lock on an open file
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
.B #include <unistd.h>
|
|
|
|
|
.sp
|
2006-01-14 17:14:10 +00:00
|
|
|
|
.BI "int lockf(int " fd ", int " cmd ", off_t " len );
|
2007-07-08 12:11:40 +00:00
|
|
|
|
.sp
|
|
|
|
|
.in -4n
|
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
|
.in
|
|
|
|
|
.sp
|
|
|
|
|
.BR lockf ():
|
2010-09-18 09:14:55 +00:00
|
|
|
|
.ad l
|
|
|
|
|
.RS 4
|
|
|
|
|
_BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
|
|
|
|
|
_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
|
|
|
|
|
.RE
|
|
|
|
|
.ad
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.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
|
2005-07-06 08:00:30 +00:00
|
|
|
|
.IR pos .. pos + len \-1
|
2005-07-06 07:53:36 +00:00
|
|
|
|
if
|
|
|
|
|
.I len
|
|
|
|
|
is positive, and
|
2005-07-06 08:00:30 +00:00
|
|
|
|
.IR pos \- len .. pos \-1
|
2005-07-06 07:53:36 +00:00
|
|
|
|
if
|
|
|
|
|
.I len
|
|
|
|
|
is negative, where
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.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
|
2009-07-25 05:57:14 +00:00
|
|
|
|
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-2001 leaves the relationship between
|
2005-10-19 06:54:38 +00:00
|
|
|
|
.BR lockf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
|
and
|
2007-05-12 00:30:29 +00:00
|
|
|
|
.BR fcntl (2)
|
2009-07-25 05:57:14 +00:00
|
|
|
|
locks unspecified.
|
|
|
|
|
A portable application should probably avoid mixing calls
|
|
|
|
|
to these interfaces.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.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
|
2007-04-12 22:42:49 +00:00
|
|
|
|
closes some file descriptor for the file.
|
|
|
|
|
A child process does not inherit these locks.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.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
|
2007-09-20 16:26:31 +00:00
|
|
|
|
.B EAGAIN
|
2006-02-10 20:27:59 +00:00
|
|
|
|
.RB ( EACCES
|
|
|
|
|
on some other systems),
|
2004-11-03 13:51:07 +00:00
|
|
|
|
if another process holds a lock.
|
|
|
|
|
.SH "RETURN VALUE"
|
2007-04-12 22:42:49 +00:00
|
|
|
|
On success, zero is returned.
|
|
|
|
|
On error, \-1 is returned, and
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.I errno
|
|
|
|
|
is set appropriately.
|
|
|
|
|
.SH ERRORS
|
|
|
|
|
.TP
|
2006-02-10 20:27:59 +00:00
|
|
|
|
.BR EACCES " or " EAGAIN
|
2004-11-03 13:51:07 +00:00
|
|
|
|
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"
|
2008-07-15 13:39:17 +00:00
|
|
|
|
SVr4, POSIX.1-2001.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
|
.BR fcntl (2),
|
|
|
|
|
.BR flock (2)
|
|
|
|
|
.br
|
|
|
|
|
There are also
|
|
|
|
|
.I locks.txt
|
|
|
|
|
and
|
2009-03-29 18:27:50 +00:00
|
|
|
|
.I mandatory-locking.txt
|
|
|
|
|
in the kernel source directory
|
2009-07-25 05:57:14 +00:00
|
|
|
|
.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 .)
|