dotlock(1)

💖 dotlock — bestie edition 💖

okay so real quick, this is the manual for dotlock, which is the page you're reading, but the actual program it's yapping about is called mutt_dotlock. same vibe, one is the page name, one is the thing you type. iykyk ✨

---

🌸 NAME 🌸

mutt_dotlock — locks mail spool files. that's it. that's the job. she's a lock girlie and she's booked and busy 🎀

---

🦋 SYNOPSIS 🦋

mutt_dotlock [-t|-f|-u|-d] [-p] [-r retries] file

---

✨ DESCRIPTION ✨

okay so mutt_dotlock does the traditional mail spool file locking method, the old-school one, no cap. here's the tea:

to lock file, she creates a file named file.lock. that's the whole ritual. and if she needs to, she operates with group mail privileges — like, she'll put on the group-mail-privileges outfit if the situation calls for it 💅

---

👑 OPTIONS 👑

• -t — just try. she will not actually lock file, she's just peeking 👀 — she'll tell whoever invoked her whether it's at all possible to lock file. window shopping, essentially.
• -f — force the lock. if some other process has been holding a lock on file for longer than a certain amount of time, mutt_dotlock will break that lock by removing the lockfile. she said move 🫶
• -u — unlock. she removes file.lock. bye bestie 💨
• -d — delete. she locks file, removes it if it has length 0, and afterwards removes file.lock. full cleanup arc.
• -p — use privileges. if you give her this one, mutt_dotlock will operate with group mail privileges when creating and deleting lock files.
• -r retries — this one tells mutt_dotlock to try locking retries times before giving up, or — if she was invoked with the -f option — before breaking a lock. the default value is 5. and between each successive locking attempt, mutt_dotlock waits one second. so like, she's patient but she's not that patient.

---

🎀 FILES 🎀

• file.lock — the lock file that mutt_dotlock generates. iconic, honestly.

---

🌈 SEE ALSO 🌈

fcntl(2), flock(2), lockfile(1), mutt(1)

go read those too, they're all part of the lore 📚

---

💀 DIAGNOSTICS 💀

mutt_dotlock says everything she needs to say through her return values. no small talk, just numbers:

• 0 — DL_EX_OK — the program was successful. we love a win 💖
• 1 — DL_EX_ERROR — an unspecified error has occurred, like bad command line parameters, lack of system memory, and the like. vague, mysterious, unhelpful 😭
• 3 — DL_EX_EXIST — the user wants to lock a file which has already been locked by another process. and if mutt_dotlock was invoked with the -f command line option, she won't generate this error — instead she'll break other processes' locks. so rude, so necessary.
• 4 — DL_EX_NEED_RPIVS — this return value only happens if mutt_dotlock was invoked with the -t command line option. it means she will have to use her group mail privileges to lock file.
• 5 — DL_EX_IMPOSSIBLE — this return value also only happens if mutt_dotlock was invoked with the -t command line option. it means she is unable to lock file even with group mail privileges. truly the flop era 😔

---

🧚 NOTES 🧚

mutt_dotlock tries to implement an NFS-safe dotlocking method, which was borrowed from lockfile (1). respectfully, credit given 💜

⚠️ okay this one's important: if the user can't open file for reading with their normal privileges, mutt_dotlock will return the DL_EX_ERROR exit value — this is on purpose, to avoid certain attacks against other users' spool files. the code carefully avoids race conditions when checking permissions; for all the details of that, see the comments in dotlock.c. do not come for her security choices, she's thought about this.

---

🌟 HISTORY 🌟

mutt_dotlock is part of the Mutt mail user agent package. she was created to avoid running mutt with group mail privileges. a queen who solved a problem before it was even a problem 👑

---

💜 AUTHOR 💜

Thomas Roessler <roessler@does-not-exist.org>

---

and that's the whole page, bestie 🫶 this came out of the Unix manual set, AUGUST 1999 — yes, 1999, she's vintage and still slaying, and the page itself is dotlock(1). periodt. 💅✨