lib/libc/gen/lockf.3

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