man3/lockf.3

   1 .\" Copyright 1997 Nicolás Lichtmaier <nick@debian.org>
   2 .\" Created Thu Aug  7 00:44:00 ART 1997
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Added section stuff, aeb, 2002-04-22.
  26 .\" Corrected include file, drepper, 2003-06-15.
  27 .\"
  28 .TH LOCKF 3 2019-03-06 "GNU" "Linux Programmer's Manual"
  29 .SH NAME
  30 lockf \- apply, test or remove a POSIX lock on an open file
  31 .SH SYNOPSIS
  32 .B #include <unistd.h>
  33 .PP
  34 .BI "int lockf(int " fd ", int " cmd ", off_t " len );
  35 .PP
  36 .in -4n
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .in
  40 .PP
  41 .BR lockf ():
  42 .ad l
  43 .RS 4
  44 _XOPEN_SOURCE\ >=\ 500
  45 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  46     || /* Glibc since 2.19: */ _DEFAULT_SOURCE
  47     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  48 .RE
  49 .ad
  50 .SH DESCRIPTION
  51 Apply, test or remove a POSIX lock on a section of an open file.
  52 The file is specified by
  53 .IR fd ,
  54 a file descriptor open for writing, the action by
  55 .IR cmd ,
  56 and the section consists of byte positions
  57 .IR pos .. pos + len \-1
  58 if
  59 .I len
  60 is positive, and
  61 .IR pos \- len .. pos \-1
  62 if
  63 .I len
  64 is negative, where
  65 .I pos
  66 is the current file position, and if
  67 .I len
  68 is zero, the section extends from the current file position to
  69 infinity, encompassing the present and future end-of-file positions.
  70 In all cases, the section may extend past current end-of-file.
  71 .PP
  72 On Linux,
  73 .BR lockf ()
  74 is just an interface on top of
  75 .BR fcntl (2)
  76 locking.
  77 Many other systems implement
  78 .BR lockf ()
  79 in this way, but note that POSIX.1 leaves the relationship between
  80 .BR lockf ()
  81 and
  82 .BR fcntl (2)
  83 locks unspecified.
  84 A portable application should probably avoid mixing calls
  85 to these interfaces.
  86 .PP
  87 Valid operations are given below:
  88 .TP
  89 .B F_LOCK
  90 Set an exclusive lock on the specified section of the file.
  91 If (part of) this section is already locked, the call
  92 blocks until the previous lock is released.
  93 If this section overlaps an earlier locked section,
  94 both are merged.
  95 File locks are released as soon as the process holding the locks
  96 closes some file descriptor for the file.
  97 A child process does not inherit these locks.
  98 .TP
  99 .B F_TLOCK
 100 Same as
 101 .B F_LOCK
 102 but the call never blocks and returns an error instead if the file is
 103 already locked.
 104 .TP
 105 .B F_ULOCK
 106 Unlock the indicated section of the file.
 107 This may cause a locked section to be split into two locked sections.
 108 .TP
 109 .B F_TEST
 110 Test the lock: return 0 if the specified section
 111 is unlocked or locked by this process; return \-1, set
 112 .I errno
 113 to
 114 .B EAGAIN
 115 .RB ( EACCES
 116 on some other systems),
 117 if another process holds a lock.
 118 .SH RETURN VALUE
 119 On success, zero is returned.
 120 On error, \-1 is returned, and
 121 .I errno
 122 is set appropriately.
 123 .SH ERRORS
 124 .TP
 125 .BR EACCES " or " EAGAIN
 126 The file is locked and
 127 .B F_TLOCK
 128 or
 129 .B F_TEST
 130 was specified, or the operation is prohibited because the file has
 131 been memory-mapped by another process.
 132 .TP
 133 .B EBADF
 134 .I fd
 135 is not an open file descriptor; or
 136 .I cmd
 137 is
 138 .B F_LOCK
 139 or
 140 .BR F_TLOCK
 141 and
 142 .I fd
 143 is not a writable file descriptor.
 144 .TP
 145 .B EDEADLK
 146 The command was
 147 .B F_LOCK
 148 and this lock operation would cause a deadlock.
 149 .TP
 150 .B EINTR
 151 While waiting to acquire a lock, the call was interrupted by
 152 delivery of a signal caught by a handler; see
 153 .BR signal (7).
 154 .TP
 155 .B EINVAL
 156 An invalid operation was specified in
 157 .IR cmd .
 158 .TP
 159 .B ENOLCK
 160 Too many segment locks open, lock table is full.
 161 .SH ATTRIBUTES
 162 For an explanation of the terms used in this section, see
 163 .BR attributes (7).
 164 .TS
 165 allbox;
 166 lb lb lb
 167 l l l.
 168 Interface       Attribute       Value
 169 T{
 170 .BR lockf ()
 171 T}      Thread safety   MT-Safe
 172 .TE
 173 .SH CONFORMING TO
 174 POSIX.1-2001, POSIX.1-2008, SVr4.
 175 .SH SEE ALSO
 176 .BR fcntl (2),
 177 .BR flock (2)
 178 .PP
 179 .I locks.txt
 180 and
 181 .I mandatory-locking.txt
 182 in the Linux kernel source directory
 183 .IR Documentation/filesystems
 184 (on older kernels, these files are directly under the
 185 .I Documentation
 186 directory, and
 187 .I mandatory-locking.txt
 188 is called
 189 .IR mandatory.txt )