DOTLOCKFILE(1)

💖 DOTLOCKFILE — bestie's guide to lockfiles 💖

okay so first things first, the tea: this is dotlockfile(1) from the Cistron Utilities crew. yeah. the Cistron girlies. iconic of them honestly.

---

✨ NAME ✨

dotlockfile — the utility that manages lockfiles, fr fr. it's giving "I keep your stuff safe so two programs don't fight over it" energy 👑

---

🌸 SYNOPSIS 🌸

dotlockfile -l [-r retries] [-i interval] [-p] [-q] <-m | lockfile>
dotlockfile -l [-r retries] [-i interval] [-p] [-q] <-m | lockfile> [-P]
cmd args ...
dotlockfile -u | -t

like, copy that exactly bestie, don't get cute with it 💅

---

🦋 DESCRIPTION 🦋

so dotlockfile is a command line utility that reliably creates, tests and removes lockfiles. and when I say reliably I mean RELIABLY — it works on local and NFS filesystems, because the two crucial steps (testing whether a lockfile already exists, and then creating it) are performed atomically by a single call to link(2). one call. no window for anybody to sneak in between. that's the whole magic trick ✨

if you wanna know the algorithm it uses, the manpage lockfile_create(3) spills all the deets.

it's installed with the attribute SETGID mail, which means it can also lock and unlock mailboxes even when the mailspool directory is only writable by group mail. so yes, it can do the thing you can't do yourself. main character energy, honestly.

the name dotlockfile comes from the way mailboxes are locked for updates on a lot of UNIX systems: a lockfile gets created with the same filename as the mailbox but with the string ".lock" appended.

and the reason it's called dotlockfile and not something shorter? the names dotlock and lockfile were already taken — hence the name dotlockfile :). the struggle was real 🙈

---

💅 OPTIONS 💅

• -l — create a lockfile if no preexisting valid lockfile is found; otherwise wait and retry according to option -r. the retry interval can be explicitly set with option -i. and plot twist: -l is the default, so you can literally just leave it off. no cap.

a lockfile is treated as valid,

• if it holds the process-id of a running process,
• or if it does not hold any process-id and has been touched less than 5 minutes ago (timestamp is younger than 5 minutes).

• -r retries — the number of times dotlockfile retries to acquire the lock if it failed the first time, before giving up. the initial sleep after failing to acquire the lock is 5 seconds. after each retry the sleep interval is increased incrementally by 5 seconds, up to a maximum sleep of 60 seconds between tries — unless it's overridden by -i. the default number of retries is 5. to try only once, use -r 0. to try indefinitely, use -r -1 (yes, negative one, she's committed 😭).
• -i interval — sets a consistent retry interval. no more escalating naps, just one steady vibe.
• -u — remove a lockfile. bye bestie 👋
• -t — touch an existing lockfile (update the timestamp). useful for lockfiles on NFS filesystems. for lockfiles on local filesystems the -p option is preferable.
• -p — write the process-id of the calling process (or of dotlockfile itself if a command is executed) into the lockfile. also, when testing for an existing lockfile, check the contents for the process-id of a running process to verify if the lockfile is still valid. obviously this is only useful for lockfiles on local filesystems.
• -m — lock or unlock the current user's mailbox. the path to the mailbox is the default system mailspool directory (usually /var/mail) with the username as gotten from getpwuid() appended. if the environment variable $MAIL is set, that is used instead. then the string ".lock" is appended to get the name of the actual lockfile.
• -q — don't print warnings or errors to the standard error output. used internally by liblockfile when it spawns dotlockfile as a helper program. she's shy 🤫
• -P — on a successful "lock and spawn command", don't exit with status zero, but pass through the exit value of the spawned command.
• lockfile — the lockfile to be created or removed. must not be specified if the -m option is given. pick a lane bestie.
• command argument ... — create lockfile, run the command, wait for it to exit, and remove lockfile. the full babysitting package 🫶

---

⭐ RETURN VALUE ⭐

zero on success, non-zero on failure. when locking (the default, or with the -l option), dotlockfile returns the same values as the library function lockfile_create(3).

and here's a lil ray of sunshine: unlocking a non-existent lockfile is not an error. she's forgiving like that.

unless the -P option was supplied, when a command is executed, the return value does not correspond with that of the command that was run. if locking and unlocking was successful, the exit status is zero.

---

🌈 NOTES 🌈

the lockfile is created exactly as named on the command line. the extension ".lock" is not automatically appended. you say what you mean, she does what you say.

this utility is a lot like the lockfile(1) utility included with procmail, and the mutt_dotlock(1) utility included with mutt. however, the command-line arguments differ, and so does the return status. it is believed that dotlockfile is the most flexible implementation, since it automatically detects when it needs to use privileges to lock a mailbox, and does it safely. like she just knows. iykyk 💜

oh and psa: the above mentioned lockfile_create(3) manpage lives in the liblockfile-dev package.

---

💀 BUGS 💀

none known.

(genuinely. not one. she's flawless and she knows it 💅✨)

---

🔥 SEE ALSO 🔥

• lockfile_create(3)
• maillock(3)

---

👑 AUTHOR 👑

Miquel van Smoorenburg

---

okay that's the whole page, bestie, you're basically a lockfile expert now, go lock something (responsibly) 🎀

shoutout to the very last line of the original: this was DOTLOCKFILE(1) dated January 10, 2017, and yeah, she's still out here serving. vintage but never outdated 🌸🦋💖