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