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 2007-07-26 "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 _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500
  37 .SH DESCRIPTION
  38 Apply, test or remove a POSIX lock on a section of an open file.
  39 The file is specified by
  40 .IR fd ,
  41 a file descriptor open for writing, the action by
  42 .IR cmd ,
  43 and the section consists of byte positions
  44 .IR pos .. pos + len \-1
  45 if
  46 .I len
  47 is positive, and
  48 .IR pos \- len .. pos \-1
  49 if
  50 .I len
  51 is negative, where
  52 .I pos
  53 is the current file position, and if
  54 .I len
  55 is zero, the section extends from the current file position to
  56 infinity, encompassing the present and future end-of-file positions.
  57 In all cases, the section may extend past current end-of-file.
  58 .LP
  59 On Linux, this call is just an interface for
  60 .BR fcntl (2).
  61 (In general, the relation between
  62 .BR lockf ()
  63 and
  64 .BR fcntl (2)
  65 is unspecified.)
  66 .LP
  67 Valid operations are given below:
  68 .TP
  69 .B F_LOCK
  70 Set an exclusive lock on the specified section of the file.
  71 If (part of) this section is already locked, the call
  72 blocks until the previous lock is released.
  73 If this section overlaps an earlier locked section,
  74 both are merged.
  75 File locks are released as soon as the process holding the locks
  76 closes some file descriptor for the file.
  77 A child process does not inherit these locks.
  78 .TP
  79 .B F_TLOCK
  80 Same as
  81 .B F_LOCK
  82 but the call never blocks and returns an error instead if the file is
  83 already locked.
  84 .TP
  85 .B F_ULOCK
  86 Unlock the indicated section of the file.
  87 This may cause a locked section to be split into two locked sections.
  88 .TP
  89 .B F_TEST
  90 Test the lock: return 0 if the specified section
  91 is unlocked or locked by this process; return \-1, set
  92 .I errno
  93 to
  94 .BR EAGAIN
  95 .RB ( EACCES
  96 on some other systems),
  97 if another process holds a lock.
  98 .SH "RETURN VALUE"
  99 On success, zero is returned.
 100 On error, \-1 is returned, and
 101 .I errno
 102 is set appropriately.
 103 .SH ERRORS
 104 .TP
 105 .BR EACCES " or " EAGAIN
 106 The file is locked and
 107 .B F_TLOCK
 108 or
 109 .B F_TEST
 110 was specified, or the operation is prohibited because the file has
 111 been memory-mapped by another process.
 112 .TP
 113 .B EBADF
 114 .I fd
 115 is not an open file descriptor.
 116 .TP
 117 .B EDEADLK
 118 The command was
 119 .B T_LOCK
 120 and this lock operation would cause a deadlock.
 121 .TP
 122 .B EINVAL
 123 An invalid operation was specified in
 124 .IR fd .
 125 .TP
 126 .B ENOLCK
 127 Too many segment locks open, lock table is full.
 128 .SH "CONFORMING TO"
 129 SVr4, POSIX.1-2001
 130 .SH "SEE ALSO"
 131 .BR fcntl (2),
 132 .BR flock (2)
 133 .br
 134 There are also
 135 .I locks.txt
 136 and
 137 .I mandatory.txt
 138 in
 139 .IR /usr/src/linux/Documentation .