macOS flock Alternative: lockf Ships, mkdir Races

My publisher takes a lock before it writes anything. Ten launchd slots a day call the same script, and if two of them ever overlapped they would read the same "how many posts today" count, pick the same topic, and publish it twice. The lock is four lines of shell. It has been in production since 2026-07-23.

It is a mkdir. I wrote it that way because macOS does not ship flock, and the answers I found all pointed at mkdir as the portable atomic primitive. That part is correct. What I missed is that macOS ships a tool that does the entire job properly, and it has been sitting in /usr/bin the whole time.

What macOS actually has, checked one binary at a time

This is macOS 26.4.1 (build 25E253). I ran which against every locking utility I could name:

Tool	Result
flock	missing
timeout	missing
lockfile (procmail)	missing
dotlockfile, setlock, chpst, lckdo, sem	missing
shlock	/usr/bin/shlock — 101,888 bytes, root:wheel
lockf	/usr/bin/lockf — 118,672 bytes, root:wheel

lockf(1) is the one that matters. Its man page, dated November 25 2023, describes it as "execute a command while holding a file lock," and then says the thing I needed to read three weeks ago: "BSD-style locking is used, as described in flock(2); the mere existence of the file is not considered to constitute a lock." The man page's own example is the cron case verbatim — lockf -t 0 -k /tmp/my.lock myscript.

It came from FreeBSD 2.2, while on Linux the equivalent utility is flock(1) from util-linux — which is what every tutorial is written against. So "flock macOS" returns install it from MacPorts or use mkdir, the only atomic operation in the shell. Write-ups naming lockf exist, but they are not what the question surfaces. I took the mkdir answer.

The mkdir lock, and what 178 runs did to it

Here is the production code from ops/schedule/daily-content.sh, unchanged:

LOCK=ops/schedule/.daily-content.lock
if ! mkdir "$LOCK" 2>/dev/null; then
  if [ -n "$(find "$LOCK" -maxdepth 0 -mmin +180 2>/dev/null)" ]; then
    echo "... stale lock reclaimed" >> "$LOG"
    rm -rf "$LOCK"; mkdir "$LOCK" 2>/dev/null || exit 0
  else
    echo "... previous run still active — skipping this slot" >> "$LOG"
    exit 0
  fi
fi
trap 'rm -rf "$LOCK"' EXIT

The comment I left above it says mkdir is atomic, so it works as a lock without another tool. True of the mkdir. Not true of the five lines underneath it.

The log is 361,732 bytes and holds 178 finish records from 2026-07-23 to today: 135 exit 0, 42 exit 1, and one exit 139 on 2026-08-08 at 21:00, which is SIGSEGV. Against that, the lock's own two messages:

• previous run still active — skipping this slot: 0 occurrences, ever
• stale lock reclaimed: 1 occurrence, at 2026-08-10 13:30

Pairing each successful finish with its nearest preceding slot gives the run durations: median 27 minutes, mean 28.0, p90 42, longest ever 76. Slots are 90 minutes apart. Nothing has ever come close to colliding, which is why the contention branch has never executed. And my stale threshold — 180 minutes — is 6.7× the longest run in the record.

The one time it fired, the machine had rebooted

The 13:30 reclaim on 2026-08-10 has a gap in front of it. The previous finish line is 2026-08-09 18:27. Between them sit six scheduled slots that wrote nothing at all to the log — not a finish, not even a skip. last reboot explains it:

reboot time    Mon Aug 10 18:38
reboot time    Mon Aug 10 12:16
reboot time    Tue Jul 21 15:47

Two reboots that day. The 13:30 slot was the first to actually execute after the 12:16 boot, and it found a lock directory older than three hours. A run took the lock, the machine went down, the process died without its EXIT trap ever running, and the lock survived the reboot — because it is a directory on a disk, and directories outlive machines.

A kernel lock cannot do that. After a reboot there is no process and no open file descriptor, so there is nothing holding anything. I confirmed it directly: I left a lock file on disk, ran lockf -t 0 -k against it, and it acquired immediately with exit 0. Existence is not a lock.

And I cannot tell you which run stranded that lock, because a mkdir lock records nothing — no PID, no owner, no start time beyond a directory mtime. The missing forensic evidence is the design flaw, stated as an absence.

Two bugs in the repair path

The stale-reclaim branch is supposed to rescue exactly that reboot case. I reproduced it in /tmp with a faithful copy of the production logic and backdated lock directories. It has two defects.

The reclaim is not atomic. rm -rf "$LOCK"; mkdir "$LOCK" is two operations. With two runs in that branch at once, B's rm -rf deletes A's freshly created lock, and B's mkdir then succeeds:

[A] stale lock reclaimed
[A] >>> HOLDS LOCK (would publish now)
[B] stale lock reclaimed
[B] >>> HOLDS LOCK (would publish now)

Two holders. The atomicity of mkdir — the entire reason I chose it — is thrown away by the line written to repair it.

The trap does not check ownership. trap 'rm -rf "$LOCK"' EXIT removes whatever directory sits at that path. So if a hung run gets its lock reclaimed while it is still alive, its eventual exit deletes the new holder's lock, and a third run walks in:

[A] >>> HOLDS LOCK
[B] stale lock reclaimed (previous holder is actually still alive)
[B] >>> HOLDS LOCK
[A] work done
[A] EXIT trap removed the lock dir     <- deletes B's lock
[C] >>> HOLDS LOCK                     <- C enters while B still runs

One stale reclaim, two separate overlaps.

Both of these need conditions my schedule has not produced. Two runs entering the stale branch in the same instant requires slots closer together than 90 minutes, and a live reclaim requires a run past 180 minutes when the record maximum is 76. Neither has happened in production. The bugs are real in the code; the timetable is what has been hiding them.

What lockf does instead

Every one of those problems is a consequence of storing lock state in the filesystem. lockf stores it in the kernel:

• lockf -t 0 mylock cmd with a live holder fails immediately: lockf: mylock: already locked, exit 75 — EX_TEMPFAIL from sysexits(3). That is a clean "skip this slot" signal, distinguishable from a real error.
• SIGKILL the holder and the lock is available the same instant. The zero-byte file remains; it was never the lock.
• There is no stale window to tune, because there is no staleness. No find -mmin, no trap, no reclaim.

Use -k to keep the lock file. The man page is explicit that this guarantees lock ordering and avoids the churn of concurrent unlink-and-reacquire.

And the 1986 one

shlock is also installed, and its man page opens by deprecating itself: "The shlock command is deprecated, and lockf(1) should be used instead." It was written for the first NNTP distribution, released March 1986. It takes the middle road — it writes the holder's PID into the lock file and validates it with kill(2) signal 0, so it reclaims dead holders without a timer.

It mostly works. Killing a holder and retrying gave exit 1 at 0.1s and 0.3s, then exit 0 at 0.5s and every delay above — a sub-second guard against stealing a lock another process is mid-way through taking. That guard reads the inode change time, not the modification time, which is why backdating a lock file with touch -t appears to do nothing: touch moves mtime and cannot move ctime. Its documented failure is PID reuse, and macOS sharpens it: a lock file containing 1 is immortal, because PID 1 is launchd. shlock reports process 1 is alive, extant lock is valid, forever.

Not fixed yet

The replacement is one line — lockf -t 0 -k "$LOCK" ... wrapping the inner script — and I have not applied it. Rewriting the lock on the script publishing this post, from inside that same run, is how a fleet loses a weekend. It is queued. What changed today is that 180 minutes is no longer a number I trust: it exists only to paper over two filesystem states a kernel lock never creates.

Related traps from the same rig: idempotency guards for LLM cron jobs sit inside this lock as the second layer, launchd StartCalendarInterval missed runs explain the six empty slots on 8/10, a launchd job that failed silently is the death that strands a mkdir lock, and Claude Code exit code 1 covers the 42 non-zero runs in this log. The scheduler choice itself is in launchd vs cron on macOS.

Sources: the tool inventory, run statistics, and reboot timeline come from this machine — which against macOS 26.4.1, 178 finish records in ops/schedule/content.log (2026-07-23 to 2026-08-15), and last reboot. The race and SIGKILL results are controlled reproductions run in /tmp against copies of the production logic, not observations of live failures; the production lock was not touched and the temporary files were removed. Neither race has occurred in production, and the lockf replacement is not deployed. I could not attribute the 2026-08-10 stranded lock to a specific run, because the lock stores no PID. Downtime across the six silent slots is inferred from the absent log lines plus the boot records rather than proven slot by slot. The explanation for shlock's sub-second refusal comes from its -d output and the ctime experiment; I did not read its source. Man page quotations are from lockf(1) and shlock(1) as shipped on macOS 26.4.