LOCKF(1)

💅 LOCKF(1) — the lock-y one 💅

ok so real talk, bestie: this is a page from the General Commands Manual, and it's about lockf. she's lowkey the friend who holds your spot in line and will Not let anyone else have it. let's get into it 🫶

---

✨ NAME ✨

lockf — run a command while you're holding onto a file lock 🔒

---

🎀 SYNOPSIS 🎀

lockf [-knsw] [-t seconds] file command [arguments]
lockf [-s] [-t seconds] fd

---

🦋 DESCRIPTION 🦋

okay so picture this: lockf grabs an exclusive lock on a file, and it'll create that file if it doesn't exist yet. then when it bounces out, it deletes the file — unless you explicitly told it not to. while it's holding the lock, it runs a command with whatever optional arguments you handed over. the moment the command finishes, lockf drops the lock and removes the file, unless you passed -k. the locking style is BSD-style, exactly like flock(2) describes — and heads up, the file merely existing does not count as a lock. like, existing ≠ locking, periodt. 💀

lockf can also work on a file descriptor instead of a file. so if you don't give it a command, then fd has to be a file descriptor. the command-having version can also target a file descriptor — just pass it as the path /dev/fd/N, where N is the file descriptor you want. when a file descriptor is in play, -k is implied, and -n and -w get silently ignored (they just sit there like 🙈). this is the move for locking inside a shell script, iykyk. 🐚

if you're using lockf to make a bunch of processes play nice and share nicely, the manpage recommends using -k. why? because it guarantees lock ordering, and it also kicks in a performance-enhanced algorithm that minimizes CPU load from all that concurrent unlink, drop and re-acquire activity. slay, honestly. ⭐ that said, be aware: if you don't use -k, then no guarantees around lock ordering can be made. none. zero. ngl that's a little scary bestie 😭

the following options are supported:

---

🔥 OPTIONS 🔥

• -k — keeps the lock file around after the command finishes (so like, it does NOT get removed). king behavior for concurrency 👑
• -s — makes lockf operate silently. if it fails to grab the lock, the only clue you get is the exit status. she's mysterious like that 🤫
• -n — makes lockf fail if the specified lock file doesn't already exist. if you don't pass -n, lockf will create the file if necessary. ✨
• -t seconds — sets a timeout for waiting on the lock. by default lockf waits indefinitely to acquire it (iconic patience honestly). if you give a timeout, lockf waits at most that many seconds before giving up. a timeout of 0 is allowed, in which case lockf fails unless it can grab the lock immediately — no waiting, no vibes, just go 🏃‍♀️ when a lock times out, the command is not executed. important!!
• -w — makes lockf open file for writing instead of reading. this is necessary on filesystems (including NFSv4) where a file opened read-only cannot be exclusively locked. so like, rw or gtfo 💅

and listen: in no event will lockf break a lock that's held by another process. she would never. that's not her brand. 🚫

---

💀 EXIT STATUS 💀

if lockf successfully acquires the lock, it returns the exit status produced by command. otherwise it returns one of the exit codes defined in sysexits(3), as follows:

• EX_TEMPFAIL — the specified lock file was already locked by another process. (oop, someone got there first 😬)
• EX_CANTCREAT — lockf was unable to create the lock file, e.g., because of insufficient access privileges.
• EX_UNAVAILABLE — the -n option is specified and the specified lock file does not exist.
• EX_USAGE — there was an error on the lockf command line.
• EX_OSERR — a system call (e.g., fork(2)) failed unexpectedly.
• EX_SOFTWARE — the command did not exit normally, but may have been signaled or stopped.

---

🌸 EXAMPLES 🌸

exhibit a: the first job takes a lock and sleeps for 5 seconds in the background. the second job tries to get the lock and times out after 1 second (PID numbers will differ):

$ lockf mylock sleep 5 & lockf -t 1 mylock echo "Success"
[1] 94410
lockf: mylock: already locked

exhibit b: 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

exhibit c: lock a file and run a script, and return immediately if the lock isn't available. don't delete the file afterward so lock order is guaranteed. 🧚

$ lockf -t 0 -k /tmp/my.lock myscript

exhibit d: protect a section of a shell script with a lock, and 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 example assumes that > is implemented in the shell by opening and truncating /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) — go read those too, bestie, they're the supporting cast 🫶

---

🌈 HISTORY 🌈

a lockf utility first appeared in FreeBSD 2.2. she's been serving looks since the 90s, no cap 💜

---

🍓 AUTHORS 🍓

John Polstra <jdp@polstra.com> — thank you for this icon, we stan 💖

---

and that's the whole page, bestie!! 🎀 this little gem is from Debian, dated November 25, 2023 — go forth, hold your locks, and remember: -k or chaos 💅✨🦋