lib/libc/gen/lockf.3

   1 .\" $NetBSD: lockf.3,v 1.10 2008/04/30 13:10:50 martin Exp $
   2 .\"
   3 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Klaus Klein and S.P. Zeidler.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd September 11, 2013
  31 .Dt LOCKF 3
  32 .Os
  33 .Sh NAME
  34 .Nm lockf
  35 .Nd record locking on files
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In unistd.h
  40 .Ft int
  41 .Fn lockf "int fd" "int function" "off_t size"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn lockf
  45 function allows sections of a file to be locked with advisory-mode locks.
  46 Calls to
  47 .Fn lockf
  48 from other processes which attempt to lock the locked file section will
  49 either return an error value or block until the section becomes unlocked.
  50 All the locks for a process are removed when the process terminates.
  51 .Pp
  52 The argument
  53 .Fa fd
  54 is an open file descriptor.
  55 The file descriptor must have been opened either for write-only
  56 .Dv ( O_WRONLY )
  57 or read/write
  58 .Dv ( O_RDWR )
  59 operation.
  60 .Pp
  61 The
  62 .Fa function
  63 argument is a control value which specifies the action to be taken.
  64 The permissible values for
  65 .Fa function
  66 are as follows:
  67 .Bl -tag -width F_ULOCKXX -compact -offset indent
  68 .It Sy Function
  69 .Sy Description
  70 .It Dv F_ULOCK
  71 unlock locked sections
  72 .It Dv F_LOCK
  73 lock a section for exclusive use
  74 .It Dv F_TLOCK
  75 test and lock a section for exclusive use
  76 .It Dv F_TEST
  77 test a section for locks by other processes
  78 .El
  79 .Pp
  80 .Dv F_ULOCK
  81 removes locks from a section of the file;
  82 .Dv F_LOCK
  83 and
  84 .Dv F_TLOCK
  85 both lock a section of a file if the section is available;
  86 .Dv F_TEST
  87 detects if a lock by another process is present on the specified section.
  88 .Pp
  89 The
  90 .Fa size
  91 argument is the number of contiguous bytes to be locked or
  92 unlocked.
  93 The section to be locked or unlocked starts at the current
  94 offset in the file and extends forward for a positive size or backward
  95 for a negative size (the preceding bytes up to but not including the
  96 current offset).
  97 However, it is not permitted to lock a section that
  98 starts or extends before the beginning of the file.
  99 If
 100 .Fa size
 101 is 0, the section from the current offset through the largest possible
 102 file offset is locked (that is, from the current offset through the
 103 present or any future end-of-file).
 104 .Pp
 105 The sections locked with
 106 .Dv F_LOCK
 107 or
 108 .Dv F_TLOCK
 109 may, in whole or in part, contain or be contained by a previously
 110 locked section for the same process.
 111 When this occurs, or if adjacent
 112 locked sections would occur, the sections are combined into a single
 113 locked section.
 114 If the request would cause the number of locks to
 115 exceed a system-imposed limit, the request will fail.
 116 .Pp
 117 .Dv F_LOCK
 118 and
 119 .Dv F_TLOCK
 120 requests differ only by the action taken if the section is not
 121 available.
 122 .Dv F_LOCK
 123 blocks the calling process until the section is available.
 124 .Dv F_TLOCK
 125 makes the function fail if the section is already locked by another
 126 process.
 127 .Pp
 128 File locks are released on first close by the locking process of any
 129 file descriptor for the file.
 130 .Pp
 131 .Dv F_ULOCK
 132 requests release (wholly or in part) one or more locked sections
 133 controlled by the process.
 134 Locked sections will be unlocked starting
 135 at the current file offset through
 136 .Fa size
 137 bytes or to the end of file if size is 0.
 138 When all of a locked section
 139 is not released (that is, when the beginning or end of the area to be
 140 unlocked falls within a locked section), the remaining portions of
 141 that section are still locked by the process.
 142 Releasing the center
 143 portion of a locked section will cause the remaining locked beginning
 144 and end portions to become two separate locked sections.
 145 If the
 146 request would cause the number of locks in the system to exceed a
 147 system-imposed limit, the request will fail.
 148 .Pp
 149 An
 150 .Dv F_ULOCK
 151 request in which size is non-zero and the offset of the last byte of
 152 the requested section is the maximum value for an object of type
 153 off_t, when the process has an existing lock in which size is 0 and
 154 which includes the last byte of the requested section, will be treated
 155 as a request to unlock from the start of the requested section with a
 156 size equal to 0.
 157 Otherwise an
 158 .Dv F_ULOCK
 159 request will attempt to unlock only the requested section.
 160 .Pp
 161 A potential for deadlock occurs if a process controlling a locked
 162 region is put to sleep by attempting to lock the locked region of
 163 another process.
 164 This implementation detects that sleeping until a
 165 locked region is unlocked would cause a deadlock and fails with an
 166 .Er EDEADLK
 167 error.
 168 .Pp
 169 The
 170 .Fn lockf ,
 171 .Xr fcntl 2 ,
 172 and
 173 .Xr flock 2
 174 locks are compatible.
 175 Processes using different locking interfaces can cooperate
 176 over the same file safely.
 177 However, only one of such interfaces should be used within
 178 the same process.
 179 If a file is locked by a process through
 180 .Xr flock 2 ,
 181 any record within the file will be seen as locked
 182 from the viewpoint of another process using
 183 .Xr fcntl 2
 184 or
 185 .Fn lockf ,
 186 and vice versa.
 187 .Pp
 188 Blocking on a section is interrupted by any signal.
 189 .Sh RETURN VALUES
 190 .Rv -std lockf
 191 In the case of a failure, existing locks are not changed.
 192 .Sh ERRORS
 193 The
 194 .Fn lockf
 195 function
 196 will fail if:
 197 .Bl -tag -width Er
 198 .It Bq Er EAGAIN
 199 The argument
 200 .Fa function
 201 is
 202 .Dv F_TLOCK
 203 or
 204 .Dv F_TEST
 205 and the section is already locked by another process.
 206 .It Bq Er EBADF
 207 The argument
 208 .Fa fd
 209 is not a valid open file descriptor.
 210 .Pp
 211 The argument
 212 .Fa function
 213 is
 214 .Dv F_LOCK
 215 or
 216 .Dv F_TLOCK ,
 217 and
 218 .Fa fd
 219 is not a valid file descriptor open for writing.
 220 .It Bq Er EDEADLK
 221 The argument
 222 .Fa function
 223 is
 224 .Dv F_LOCK
 225 and a deadlock is detected.
 226 .It Bq Er EINTR
 227 The argument
 228 .Fa function
 229 is F_LOCK
 230 and
 231 .Fn lockf
 232 was interrupted by the delivery of a signal.
 233 .It Bq Er EINVAL
 234 The argument
 235 .Fa function
 236 is not one of
 237 .Dv F_ULOCK ,
 238 .Dv F_LOCK ,
 239 .Dv F_TLOCK
 240 or
 241 .Dv F_TEST .
 242 .Pp
 243 The argument
 244 .Fa fd
 245 refers to a file that does not support locking.
 246 .It Bq Er ENOLCK
 247 The argument
 248 .Fa function
 249 is
 250 .Dv F_ULOCK ,
 251 .Dv F_LOCK
 252 or
 253 .Dv F_TLOCK ,
 254 and satisfying the lock or unlock request would result in the number
 255 of locked regions in the system exceeding a system-imposed limit.
 256 .El
 257 .Sh SEE ALSO
 258 .Xr fcntl 2 ,
 259 .Xr flock 2
 260 .Sh STANDARDS
 261 The
 262 .Fn lockf
 263 function conforms to
 264 .St -xpg4.2 .