usr.bin/lockf/lockf.1

   1 .\"
   2 .\" Copyright (C) 1998 John D. Polstra.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY JOHN D. POLSTRA AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL JOHN D. POLSTRA OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd November 25, 2023
  26 .Dt LOCKF 1
  27 .Os
  28 .Sh NAME
  29 .Nm lockf
  30 .Nd execute a command while holding a file lock
  31 .Sh SYNOPSIS
  32 .Nm
  33 .Op Fl knsw
  34 .Op Fl t Ar seconds
  35 .Ar file
  36 .Ar command
  37 .Op Ar arguments
  38 .Nm
  39 .Op Fl s
  40 .Op Fl t Ar seconds
  41 .Ar fd
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 utility acquires an exclusive lock on a
  46 .Ar file ,
  47 creating it if necessary,
  48 .Bf Em
  49 and removing the file on exit unless explicitly told not to.
  50 .Ef
  51 While holding the lock, it executes a
  52 .Ar command
  53 with optional
  54 .Ar arguments .
  55 After the
  56 .Ar command
  57 completes,
  58 .Nm
  59 releases the lock, and removes the
  60 .Ar file
  61 unless the
  62 .Fl k
  63 option is specified.
  64 .Bx Ns -style
  65 locking is used, as described in
  66 .Xr flock 2 ;
  67 the mere existence of the
  68 .Ar file
  69 is not considered to constitute a lock.
  70 .Pp
  71 .Nm
  72 may also be used to operate on a file descriptor instead of a file.
  73 If no
  74 .Ar command
  75 is supplied, then
  76 .Ar fd
  77 must be a file descriptor.
  78 The version with a
  79 .Ar command
  80 may also be used with a file descriptor by supplying it as a path
  81 .Pa /dev/fd/N ,
  82 where N is the desired file descriptor.
  83 The
  84 .Fl k
  85 option is implied when a file descriptor is in use, and the
  86 .Fl n
  87 and
  88 .Fl w
  89 options are silently ignored.
  90 This can be used to lock inside a shell script.
  91 .Pp
  92 If the
  93 .Nm
  94 utility is being used to facilitate concurrency between a number
  95 of processes, it is recommended that the
  96 .Fl k
  97 option be used.
  98 This will guarantee lock ordering, as well as implement
  99 a performance enhanced algorithm which minimizes CPU load associated
 100 with concurrent unlink, drop and re-acquire activity.
 101 It should be noted
 102 that if the
 103 .Fl k
 104 option is not used, then no guarantees around lock ordering can be made.
 105 .Pp
 106 The following options are supported:
 107 .Bl -tag -width ".Fl t Ar seconds"
 108 .It Fl k
 109 Causes the lock file to be kept (not removed) after the command
 110 completes.
 111 .It Fl s
 112 Causes
 113 .Nm
 114 to operate silently.
 115 Failure to acquire the lock is indicated only in the exit status.
 116 .It Fl n
 117 Causes
 118 .Nm
 119 to fail if the specified lock
 120 .Ar file
 121 does not exist.
 122 If
 123 .Fl n
 124 is not specified,
 125 .Nm
 126 will create
 127 .Ar file
 128 if necessary.
 129 .It Fl t Ar seconds
 130 Specifies a timeout for waiting for the lock.
 131 By default,
 132 .Nm
 133 waits indefinitely to acquire the lock.
 134 If a timeout is specified with this option,
 135 .Nm
 136 will wait at most the given number of
 137 .Ar seconds
 138 before giving up.
 139 A timeout of 0 may be given, in which case
 140 .Nm
 141 will fail unless it can acquire the lock immediately.
 142 When a lock times out,
 143 .Ar command
 144 is
 145 .Em not
 146 executed.
 147 .It Fl w
 148 Causes
 149 .Nm
 150 to open
 151 .Ar file
 152 for writing rather than reading.
 153 This is necessary on filesystems (including NFSv4) where a file which
 154 has been opened read-only cannot be exclusively locked.
 155 .El
 156 .Pp
 157 In no event will
 158 .Nm
 159 break a lock that is held by another process.
 160 .Sh EXIT STATUS
 161 If
 162 .Nm
 163 successfully acquires the lock, it returns the exit status produced by
 164 .Ar command .
 165 Otherwise, it returns one of the exit codes defined in
 166 .Xr sysexits 3 ,
 167 as follows:
 168 .Bl -tag -width ".Dv EX_CANTCREAT"
 169 .It Dv EX_TEMPFAIL
 170 The specified lock file was already locked by another process.
 171 .It Dv EX_CANTCREAT
 172 The
 173 .Nm
 174 utility
 175 was unable to create the lock file, e.g., because of insufficient access
 176 privileges.
 177 .It Dv EX_UNAVAILABLE
 178 The
 179 .Fl n
 180 option is specified and the specified lock file does not exist.
 181 .It Dv EX_USAGE
 182 There was an error on the
 183 .Nm
 184 command line.
 185 .It Dv EX_OSERR
 186 A system call (e.g.,
 187 .Xr fork 2 )
 188 failed unexpectedly.
 189 .It Dv EX_SOFTWARE
 190 The
 191 .Ar command
 192 did not exit normally,
 193 but may have been signaled or stopped.
 194 .El
 195 .Sh EXAMPLES
 196 The first job takes a lock and sleeps for 5 seconds in the background.
 197 The second job tries to get the lock and timeouts after 1 second (PID numbers
 198 will differ):
 199 .Bd -literal -offset indent
 200 $ lockf mylock sleep 5 & lockf -t 1 mylock echo "Success"
 201 [1] 94410
 202 lockf: mylock: already locked
 203 .Ed
 204 .Pp
 205 The first job takes a lock and sleeps for 1 second in the background.
 206 The second job waits up to 5 seconds to take the lock and echoes the message on
 207 success (PID numbers will differ):
 208 .Bd -literal -offset indent
 209 $ lockf mylock sleep 1 & lockf -t 5 mylock echo "Success"
 210 [1] 19995
 211 Success
 212 [1]+  Done                    lockf mylock sleep 1
 213 .Ed
 214 Lock a file and run a script, return immediately if the lock is not
 215 available. Do not delete the file afterward so lock order is
 216 guaranteed.
 217 .Pp
 218 .Dl $ lockf -t 0 -k /tmp/my.lock myscript
 219 .Pp
 220 Protect a section of a shell script with a lock, wait up to 5 seconds
 221 for it to become available.
 222 Note that the shell script has opened the lock file
 223 .Fa /tmp/my.lock ,
 224 and
 225 .Nm
 226 is performing the lock call exclusively via the passed in file descriptor (9).
 227 In this case
 228 .Fl k
 229 is implied, and
 230 .Fl w
 231 has no effect because the file has already been opened by the shell.
 232 This example assumes that
 233 .Ql >
 234 is implemented in the shell by opening and truncating
 235 .Pa /tmp/my.lock ,
 236 rather than by replacing the lock file.
 237 .Bd -literal -offset indent
 238 (
 239         lockf -s -t 5 9
 240         if [ $? -ne 0 ]; then
 241                 echo "Failed to obtain lock"
 242                 exit 1
 243         fi
 244
 245         echo Start
 246         # Do some stuff
 247         echo End
 248 ) 9>/tmp/my.lock
 249 .Ed
 250 .Sh SEE ALSO
 251 .Xr flock 2 ,
 252 .Xr lockf 3 ,
 253 .Xr sysexits 3
 254 .Sh HISTORY
 255 A
 256 .Nm
 257 utility first appeared in
 258 .Fx 2.2 .
 259 .Sh AUTHORS
 260 .An John Polstra Aq Mt jdp@polstra.com