| .\" 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 2017-09-15 "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> |
| .PP |
| .BI "int lockf(int " fd ", int " cmd ", off_t " len ); |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR lockf (): |
| .ad l |
| .RS 4 |
| _XOPEN_SOURCE\ >=\ 500 |
| .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED |
| || /* Glibc since 2.19: */ _DEFAULT_SOURCE |
| || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE |
| .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. |
| .PP |
| 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. |
| .PP |
| 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) |
| .PP |
| .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 ) |