dotlock(1)

💖 dotlock(1) 💖

okay bestie, pull up a chair, we're talking about lbdb_dotlock — the little Unix manual that lives in User Manuals, section 1. yes it's giving "ancient mail server energy" but honestly? it's iconic. let's go. 🎀

---

✨ NAME ✨

lbdb_dotlock — lock mail spool files. that's it. that's the job. protect the spool, protect the vibe. 💅

---

✨ SYNOPSIS ✨

lbdb_dotlock [-t|-f|-u|-d] [-r retries] file

so it's lbdb_dotlock, then ONE of -t, -f, -u or -d (pick a lane, bestie 💀), then optionally -r retries if you're feeling spicy, and then the file you're doing all this to. periodt.

---

✨ DESCRIPTION ✨

so basically, dotlock is out here implementing the traditional mail spool file locking method. the whole trick is lowkey elegant: to lock file, it creates a file called file.lock. that's the entire personality. one file begets another file. slay. ✨

---

✨ OPTIONS ✨

• -t — just try. dotlock won't actually lock the file, it'll just tell the invoking process whether locking file is even possible at all. it's giving "hypothetically, could we?" 🦋
• -f — force the lock. if some other process has been holding a lock on file for longer than a certain amount of time, dotlock will break that lock by removing the lockfile. ruthless. no cap. 💀
• -u — unlock. dotlock removes file.lock. bye bestie 👋
• -d — delete. dotlock locks file, removes it if it has length 0, and afterwards removes file.lock. multi-step main character behavior 🌟
• -r retries — this one tells dotlock to try locking retries times before giving up, or — if it was invoked with the -f command line option — before breaking a lock. the default value is 5. and between each successive locking attempt, dotlock waits one second. patience is a virtue, i guess 🧚

---

✨ FILES ✨

• file.lock — the lock file that dotlock generates. it's the whole point. the moment. the icon. 👑

---

✨ SEE ALSO ✨

fcntl(2), flock(2), lockfile(1), lbdb-fetchaddr(1) — go read those too, i'm not gatekeeping 🫶

---

✨ DIAGNOSTICS ✨

dotlock gives all its diagnostics in its return values, so like, watch the exit code, bestie:

1. 0 - DL_EX_OK — the program was successful. we love to see it. 🎉
2. 1 - DL_EX_ERROR — an unspecified error happened, like bad command line parameters, not enough system memory, that kind of thing. it's giving chaos 😭
3. 3 - DL_EX_EXIST — the user wants to lock a file that some other process has already locked. BUT if dotlock was invoked with the -f command line option, it won't generate this error — instead it'll break those other processes' locks. bold. 🔥
4. 4 - DL_EX_NEED_RPIVS — this return value only shows up if dotlock was invoked with the -t command line option. it means dotlock is gonna have to use its group mail privileges to lock file.
5. 5 - DL_EX_IMPOSSIBLE — this return value also only shows up with the -t command line option. it means dotlock is straight up unable to lock file. rip. 💀

---

✨ NOTES ✨

dotlock tries to implement an NFS-safe dotlocking method, which was borrowed from lockfile(1). we love a collab. 🤝

⚠️ okay this part matters: if the user can't open file for reading with their normal privileges, dotlock will return the DL_EX_ERROR exit value — and that's on purpose, to avoid certain attacks against other users' spool files. the code carefully avoids race conditions when checking permissions; for all the gory details, see the comments in dotlock.c. 🕵️♀️

---

✨ HISTORY ✨

dotlock is part of the Mutt mail user agent package. it was created to avoid running mutt with group mail privileges. a humble origin story honestly 🌸

---

✨ AUTHOR ✨

Thomas Roessler <roessler@guug.de> — ty king 🫡

---

and that's the whole page, bestie!! this one came from Unix, dated JANUARY 2016 💜 so yeah, shoutout to that source and that date, they're literally the whole footer energy. now go lock your spool files responsibly. mwah 💋✨🎀