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 August 26, 2020
  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 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 utility acquires an exclusive lock on a
  42 .Ar file ,
  43 creating it if necessary,
  44 .Bf Em
  45 and removing the file on exit unless explicitly told not to.
  46 .Ef
  47 While holding the lock, it executes a
  48 .Ar command
  49 with optional
  50 .Ar arguments .
  51 After the
  52 .Ar command
  53 completes,
  54 .Nm
  55 releases the lock, and removes the
  56 .Ar file
  57 unless the
  58 .Fl k
  59 option is specified.
  60 .Bx Ns -style
  61 locking is used, as described in
  62 .Xr flock 2 ;
  63 the mere existence of the
  64 .Ar file
  65 is not considered to constitute a lock.
  66 .Pp
  67 If the
  68 .Nm
  69 utility is being used to facilitate concurrency between a number
  70 of processes, it is recommended that the
  71 .Fl k
  72 option be used.
  73 This will guarantee lock ordering, as well as implement
  74 a performance enhanced algorithm which minimizes CPU load associated
  75 with concurrent unlink, drop and re-acquire activity.
  76 It should be noted
  77 that if the
  78 .Fl k
  79 option is not used, then no guarantees around lock ordering can be made.
  80 .Pp
  81 The following options are supported:
  82 .Bl -tag -width ".Fl t Ar seconds"
  83 .It Fl k
  84 Causes the lock file to be kept (not removed) after the command
  85 completes.
  86 .It Fl s
  87 Causes
  88 .Nm
  89 to operate silently.
  90 Failure to acquire the lock is indicated only in the exit status.
  91 .It Fl n
  92 Causes
  93 .Nm
  94 to fail if the specified lock
  95 .Ar file
  96 does not exist.
  97 If
  98 .Fl n
  99 is not specified,
 100 .Nm
 101 will create
 102 .Ar file
 103 if necessary.
 104 .It Fl t Ar seconds
 105 Specifies a timeout for waiting for the lock.
 106 By default,
 107 .Nm
 108 waits indefinitely to acquire the lock.
 109 If a timeout is specified with this option,
 110 .Nm
 111 will wait at most the given number of
 112 .Ar seconds
 113 before giving up.
 114 A timeout of 0 may be given, in which case
 115 .Nm
 116 will fail unless it can acquire the lock immediately.
 117 When a lock times out,
 118 .Ar command
 119 is
 120 .Em not
 121 executed.
 122 .It Fl w
 123 Causes
 124 .Nm
 125 to open
 126 .Ar file
 127 for writing rather than reading.
 128 This is necessary on filesystems (including NFSv4) where a file which
 129 has been opened read-only cannot be exclusively locked.
 130 .El
 131 .Pp
 132 In no event will
 133 .Nm
 134 break a lock that is held by another process.
 135 .Sh EXIT STATUS
 136 If
 137 .Nm
 138 successfully acquires the lock, it returns the exit status produced by
 139 .Ar command .
 140 Otherwise, it returns one of the exit codes defined in
 141 .Xr sysexits 3 ,
 142 as follows:
 143 .Bl -tag -width ".Dv EX_CANTCREAT"
 144 .It Dv EX_TEMPFAIL
 145 The specified lock file was already locked by another process.
 146 .It Dv EX_CANTCREAT
 147 The
 148 .Nm
 149 utility
 150 was unable to create the lock file, e.g., because of insufficient access
 151 privileges.
 152 .It Dv EX_UNAVAILABLE
 153 The
 154 .Fl n
 155 option is specified and the specified lock file does not exist.
 156 .It Dv EX_USAGE
 157 There was an error on the
 158 .Nm
 159 command line.
 160 .It Dv EX_OSERR
 161 A system call (e.g.,
 162 .Xr fork 2 )
 163 failed unexpectedly.
 164 .It Dv EX_SOFTWARE
 165 The
 166 .Ar command
 167 did not exit normally,
 168 but may have been signaled or stopped.
 169 .El
 170 .Sh EXAMPLES
 171 The first job takes a lock and sleeps for 5 seconds in the background.
 172 The second job tries to get the lock and timeouts after 1 second (PID numbers
 173 will differ):
 174 .Bd -literal -offset indent
 175 $ lockf mylock sleep 5 & lockf -t 1 mylock echo "Success"
 176 [1] 94410
 177 lockf: mylock: already locked
 178 .Ed
 179 .Pp
 180 The first job takes a lock and sleeps for 1 second in the background.
 181 The second job waits up to 5 seconds to take the lock and echoes the message on
 182 success (PID numbers will differ):
 183 .Bd -literal -offset indent
 184 $ lockf mylock sleep 1 & lockf -t 5 mylock echo "Success"
 185 [1] 19995
 186 Success
 187 [1]+  Done                    lockf mylock sleep 1
 188 .Ed
 189 .Sh SEE ALSO
 190 .Xr flock 2 ,
 191 .Xr lockf 3 ,
 192 .Xr sysexits 3
 193 .Sh HISTORY
 194 A
 195 .Nm
 196 utility first appeared in
 197 .Fx 2.2 .
 198 .Sh AUTHORS
 199 .An John Polstra Aq Mt jdp@polstra.com