FreeBSD Manual Pages
LOCKF(1) General Commands Manual LOCKF(1) NAME lockf -- execute a command while holding a file lock SYNOPSIS lockf [-knpsTw] [-t seconds] file command [arguments] lockf [-s] [-t seconds] fd DESCRIPTION The lockf utility acquires an exclusive lock on a file, creating it if nec- essary, and removing the file on exit unless explicitly told not to. While holding the lock, it executes a command with optional arguments. After the command completes, lockf releases the lock, and removes the file unless the -k option is specified. BSD-style locking is used, as described in flock(2); the mere existence of the file is not considered to constitute a lock. lockf may also be used to operate on a file descriptor instead of a file. If no command is supplied, then fd must be a file descriptor. The version with a command may also be used with a file descriptor by supplying it as a path /dev/fd/N, where N is the desired file descriptor. The -k option is implied when a file descriptor is in use, and the -n and -w options are silently ignored. This can be used to lock inside a shell script. If the lockf utility is being used to facilitate concurrency between a num- ber of processes, it is recommended that the -k option be used. This will guarantee lock ordering, as well as implement a performance enhanced algo- rithm which minimizes CPU load associated with concurrent unlink, drop and re-acquire activity. It should be noted that if the -k option is not used, then no guarantees around lock ordering can be made. The following options are supported: -k Causes the lock file to be kept (not removed) after the command completes. -n Causes lockf to fail if the specified lock file does not exist. If -n is not specified, lockf will create file if necessary. -p Write the pid of the command to file. This option will cause lockf to open file for writing rather than reading. -s Causes lockf to operate silently. Failure to acquire the lock is indicated only in the exit status. -T Upon receipt of a SIGTERM, forward a SIGTERM along to the command before cleaning up the file and exiting. By default, lockf effectively orphans the command after cleaning up the file. -t seconds Specifies a timeout for waiting for the lock. By default, lockf waits indefinitely to acquire the lock. If a timeout is specified with this option, lockf will wait at most the given number of seconds before giving up. A timeout of 0 may be given, in which case lockf will fail unless it can acquire the lock immediately. When a lock times out, command is not exe- cuted. -w Causes lockf to open file for writing rather than reading. This is necessary on filesystems (including NFSv4) where a file which has been opened read-only cannot be exclusively locked. In no event will lockf break a lock that is held by another process. EXIT STATUS If lockf successfully acquires the lock, it returns the exit status pro- duced by command. Otherwise, it returns one of the exit codes defined in sysexits(3), as follows: EX_OSERR (61) A system call, e.g., fork(2), failed unexpectedly. EX_USAGE (64) There was an error on the lockf command line. EX_UNAVAILABLE (69) The -n option is specified and the specified lock file does not exist. EX_SOFTWARE (70) The command did not exit normally, but may have been signaled or stopped. EX_CANTCREAT (73) The lockf utility was unable to create the lock file, e.g., because of insufficient access privileges. EX_TEMPFAIL (75) The specified lock file was already locked by another process. EXAMPLES The first job takes a lock and sleeps for 5 seconds in the background. The second job tries to get the lock and timeouts after 1 second (PID numbers will differ): $ lockf mylock sleep 5 & lockf -t 1 mylock echo "Success" [1] 94410 lockf: mylock: already locked The first job takes a lock and sleeps for 1 second in the background. The second job waits up to 5 seconds to take the lock and echoes the message on success (PID numbers will differ): $ lockf mylock sleep 1 & lockf -t 5 mylock echo "Success" [1] 19995 Success [1]+ Done lockf mylock sleep 1 Lock a file and run a script, return immediately if the lock is not avail- able. Do not delete the file afterward so lock order is guaranteed. $ lockf -t 0 -k /tmp/my.lock myscript Protect a section of a shell script with a lock, wait up to 5 seconds for it to become available. Note that the shell script has opened the lock file /tmp/my.lock, and lockf is performing the lock call exclusively via the passed in file descriptor (9). In this case -k is implied, and -w has no effect because the file has already been opened by the shell. This ex- ample assumes that `>' is implemented in the shell by opening and truncat- ing /tmp/my.lock, rather than by replacing the lock file. ( lockf -s -t 5 9 if [ $? -ne 0 ]; then echo "Failed to obtain lock" exit 1 fi echo Start # Do some stuff echo End ) 9>/tmp/my.lock SEE ALSO flock(2), lockf(3), sysexits(3) HISTORY A lockf utility first appeared in FreeBSD 2.2. AUTHORS John Polstra <jdp@polstra.com> FreeBSD ports 15.quarterly February 26, 2026 LOCKF(1)
NAME | SYNOPSIS | DESCRIPTION | EXIT STATUS | EXAMPLES | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lockf&sektion=1&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>