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