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 .\" $FreeBSD$
  31 .\"
  32 .Dd September 11, 2013
  33 .Dt LOCKF 3
  34 .Os
  35 .Sh NAME
  36 .Nm lockf
  37 .Nd record locking on files
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In unistd.h
  42 .Ft int
  43 .Fn lockf "int fd" "int function" "off_t size"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn lockf
  47 function allows sections of a file to be locked with advisory-mode locks.
  48 Calls to
  49 .Fn lockf
  50 from other processes which attempt to lock the locked file section will
  51 either return an error value or block until the section becomes unlocked.
  52 All the locks for a process are removed when the process terminates.
  53 .Pp
  54 The argument
  55 .Fa fd
  56 is an open file descriptor.
  57 The file descriptor must have been opened either for write-only
  58 .Dv ( O_WRONLY )
  59 or read/write
  60 .Dv ( O_RDWR )
  61 operation.
  62 .Pp
  63 The
  64 .Fa function
  65 argument is a control value which specifies the action to be taken.
  66 The permissible values for
  67 .Fa function
  68 are as follows:
  69 .Bl -tag -width F_ULOCKXX -compact -offset indent
  70 .It Sy Function
  71 .Sy Description
  72 .It Dv F_ULOCK
  73 unlock locked sections
  74 .It Dv F_LOCK
  75 lock a section for exclusive use
  76 .It Dv F_TLOCK
  77 test and lock a section for exclusive use
  78 .It Dv F_TEST
  79 test a section for locks by other processes
  80 .El
  81 .Pp
  82 .Dv F_ULOCK
  83 removes locks from a section of the file;
  84 .Dv F_LOCK
  85 and
  86 .Dv F_TLOCK
  87 both lock a section of a file if the section is available;
  88 .Dv F_TEST
  89 detects if a lock by another process is present on the specified section.
  90 .Pp
  91 The
  92 .Fa size
  93 argument is the number of contiguous bytes to be locked or
  94 unlocked.
  95 The section to be locked or unlocked starts at the current
  96 offset in the file and extends forward for a positive size or backward
  97 for a negative size (the preceding bytes up to but not including the
  98 current offset).
  99 However, it is not permitted to lock a section that
 100 starts or extends before the beginning of the file.
 101 If
 102 .Fa size
 103 is 0, the section from the current offset through the largest possible
 104 file offset is locked (that is, from the current offset through the
 105 present or any future end-of-file).
 106 .Pp
 107 The sections locked with
 108 .Dv F_LOCK
 109 or
 110 .Dv F_TLOCK
 111 may, in whole or in part, contain or be contained by a previously
 112 locked section for the same process.
 113 When this occurs, or if adjacent
 114 locked sections would occur, the sections are combined into a single
 115 locked section.
 116 If the request would cause the number of locks to
 117 exceed a system-imposed limit, the request will fail.
 118 .Pp
 119 .Dv F_LOCK
 120 and
 121 .Dv F_TLOCK
 122 requests differ only by the action taken if the section is not
 123 available.
 124 .Dv F_LOCK
 125 blocks the calling process until the section is available.
 126 .Dv F_TLOCK
 127 makes the function fail if the section is already locked by another
 128 process.
 129 .Pp
 130 File locks are released on first close by the locking process of any
 131 file descriptor for the file.
 132 .Pp
 133 .Dv F_ULOCK
 134 requests release (wholly or in part) one or more locked sections
 135 controlled by the process.
 136 Locked sections will be unlocked starting
 137 at the current file offset through
 138 .Fa size
 139 bytes or to the end of file if size is 0.
 140 When all of a locked section
 141 is not released (that is, when the beginning or end of the area to be
 142 unlocked falls within a locked section), the remaining portions of
 143 that section are still locked by the process.
 144 Releasing the center
 145 portion of a locked section will cause the remaining locked beginning
 146 and end portions to become two separate locked sections.
 147 If the
 148 request would cause the number of locks in the system to exceed a
 149 system-imposed limit, the request will fail.
 150 .Pp
 151 An
 152 .Dv F_ULOCK
 153 request in which size is non-zero and the offset of the last byte of
 154 the requested section is the maximum value for an object of type
 155 off_t, when the process has an existing lock in which size is 0 and
 156 which includes the last byte of the requested section, will be treated
 157 as a request to unlock from the start of the requested section with a
 158 size equal to 0.
 159 Otherwise an
 160 .Dv F_ULOCK
 161 request will attempt to unlock only the requested section.
 162 .Pp
 163 A potential for deadlock occurs if a process controlling a locked
 164 region is put to sleep by attempting to lock the locked region of
 165 another process.
 166 This implementation detects that sleeping until a
 167 locked region is unlocked would cause a deadlock and fails with an
 168 .Er EDEADLK
 169 error.
 170 .Pp
 171 The
 172 .Fn lockf ,
 173 .Xr fcntl 2 ,
 174 and
 175 .Xr flock 2
 176 locks are compatible.
 177 Processes using different locking interfaces can cooperate
 178 over the same file safely.
 179 However, only one of such interfaces should be used within
 180 the same process.
 181 If a file is locked by a process through
 182 .Xr flock 2 ,
 183 any record within the file will be seen as locked
 184 from the viewpoint of another process using
 185 .Xr fcntl 2
 186 or
 187 .Fn lockf ,
 188 and vice versa.
 189 .Pp
 190 Blocking on a section is interrupted by any signal.
 191 .Sh RETURN VALUES
 192 .Rv -std lockf
 193 In the case of a failure, existing locks are not changed.
 194 .Sh ERRORS
 195 The
 196 .Fn lockf
 197 function
 198 will fail if:
 199 .Bl -tag -width Er
 200 .It Bq Er EAGAIN
 201 The argument
 202 .Fa function
 203 is
 204 .Dv F_TLOCK
 205 or
 206 .Dv F_TEST
 207 and the section is already locked by another process.
 208 .It Bq Er EBADF
 209 The argument
 210 .Fa fd
 211 is not a valid open file descriptor.
 212 .Pp
 213 The argument
 214 .Fa function
 215 is
 216 .Dv F_LOCK
 217 or
 218 .Dv F_TLOCK ,
 219 and
 220 .Fa fd
 221 is not a valid file descriptor open for writing.
 222 .It Bq Er EDEADLK
 223 The argument
 224 .Fa function
 225 is
 226 .Dv F_LOCK
 227 and a deadlock is detected.
 228 .It Bq Er EINTR
 229 The argument
 230 .Fa function
 231 is F_LOCK
 232 and
 233 .Fn lockf
 234 was interrupted by the delivery of a signal.
 235 .It Bq Er EINVAL
 236 The argument
 237 .Fa function
 238 is not one of
 239 .Dv F_ULOCK ,
 240 .Dv F_LOCK ,
 241 .Dv F_TLOCK
 242 or
 243 .Dv F_TEST .
 244 .Pp
 245 The argument
 246 .Fa fd
 247 refers to a file that does not support locking.
 248 .It Bq Er ENOLCK
 249 The argument
 250 .Fa function
 251 is
 252 .Dv F_ULOCK ,
 253 .Dv F_LOCK
 254 or
 255 .Dv F_TLOCK ,
 256 and satisfying the lock or unlock request would result in the number
 257 of locked regions in the system exceeding a system-imposed limit.
 258 .El
 259 .Sh SEE ALSO
 260 .Xr fcntl 2 ,
 261 .Xr flock 2
 262 .Sh STANDARDS
 263 The
 264 .Fn lockf
 265 function conforms to
 266 .St -xpg4.2 .