original/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 2014-02-11 "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 .sp
  34 .BI "int lockf(int " fd ", int " cmd ", off_t " len );
  35 .sp
  36 .in -4n
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .in
  40 .sp
  41 .BR lockf ():
  42 .ad l
  43 .RS 4
  44 _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  45 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  46 .RE
  47 .ad
  48 .SH DESCRIPTION
  49 Apply, test or remove a POSIX lock on a section of an open file.
  50 The file is specified by
  51 .IR fd ,
  52 a file descriptor open for writing, the action by
  53 .IR cmd ,
  54 and the section consists of byte positions
  55 .IR pos .. pos + len \-1
  56 if
  57 .I len
  58 is positive, and
  59 .IR pos \- len .. pos \-1
  60 if
  61 .I len
  62 is negative, where
  63 .I pos
  64 is the current file position, and if
  65 .I len
  66 is zero, the section extends from the current file position to
  67 infinity, encompassing the present and future end-of-file positions.
  68 In all cases, the section may extend past current end-of-file.
  69 .LP
  70 On Linux,
  71 .BR lockf ()
  72 is just an interface on top of
  73 .BR fcntl (2)
  74 locking.
  75 Many other systems implement
  76 .BR lockf ()
  77 in this way, but note that POSIX.1-2001 leaves the relationship between
  78 .BR lockf ()
  79 and
  80 .BR fcntl (2)
  81 locks unspecified.
  82 A portable application should probably avoid mixing calls
  83 to these interfaces.
  84 .LP
  85 Valid operations are given below:
  86 .TP
  87 .B F_LOCK
  88 Set an exclusive lock on the specified section of the file.
  89 If (part of) this section is already locked, the call
  90 blocks until the previous lock is released.
  91 If this section overlaps an earlier locked section,
  92 both are merged.
  93 File locks are released as soon as the process holding the locks
  94 closes some file descriptor for the file.
  95 A child process does not inherit these locks.
  96 .TP
  97 .B F_TLOCK
  98 Same as
  99 .B F_LOCK
 100 but the call never blocks and returns an error instead if the file is
 101 already locked.
 102 .TP
 103 .B F_ULOCK
 104 Unlock the indicated section of the file.
 105 This may cause a locked section to be split into two locked sections.
 106 .TP
 107 .B F_TEST
 108 Test the lock: return 0 if the specified section
 109 is unlocked or locked by this process; return \-1, set
 110 .I errno
 111 to
 112 .B EAGAIN
 113 .RB ( EACCES
 114 on some other systems),
 115 if another process holds a lock.
 116 .SH RETURN VALUE
 117 On success, zero is returned.
 118 On error, \-1 is returned, and
 119 .I errno
 120 is set appropriately.
 121 .SH ERRORS
 122 .TP
 123 .BR EACCES " or " EAGAIN
 124 The file is locked and
 125 .B F_TLOCK
 126 or
 127 .B F_TEST
 128 was specified, or the operation is prohibited because the file has
 129 been memory-mapped by another process.
 130 .TP
 131 .B EBADF
 132 .I fd
 133 is not an open file descriptor; or
 134 .I cmd
 135 is
 136 .B F_LOCK
 137 or
 138 .BR F_TLOCK
 139 and
 140 .I fd
 141 is not a writable file descriptor.
 142 .TP
 143 .B EDEADLK
 144 The command was
 145 .B F_LOCK
 146 and this lock operation would cause a deadlock.
 147 .TP
 148 .B EINVAL
 149 An invalid operation was specified in
 150 .IR cmd .
 151 .TP
 152 .B ENOLCK
 153 Too many segment locks open, lock table is full.
 154 .SH CONFORMING TO
 155 SVr4, POSIX.1-2001.
 156 .SH SEE ALSO
 157 .BR fcntl (2),
 158 .BR flock (2)
 159
 160 .I locks.txt
 161 and
 162 .I mandatory-locking.txt
 163 in the Linux kernel source directory
 164 .IR Documentation/filesystems
 165 (on older kernels, these files are directly under the
 166 .I Documentation
 167 directory, and
 168 .I mandatory-locking.txt
 169 is called
 170 .IR mandatory.txt )
 171 .SH COLOPHON
 172 This page is part of release 3.67 of the Linux
 173 .I man-pages
 174 project.
 175 A description of the project,
 176 information about reporting bugs,
 177 and the latest version of this page,
 178 can be found at
 179 \%http://www.kernel.org/doc/man\-pages/.