LOCKMAIL(1)

💖 LOCKMAIL(1) 💖

okay so bestie, this is lockmail(1), and honestly? it's giving backstage-pass energy for your mailbox. it's a lil helper utility, written by S. Varshavchik, and it's about to be your new fave. let's get into it 🫶

---

🌸 NAME 🌸

lockmail — create mail lock files

---

✨ SYNOPSIS ✨

lockmail [-r] [-t timeout] {lockfile} {program} [argument...]

---

🦋 DESCRIPTION 🦋

so lockmail is a lil helper utility for working with mailbox files. and here's the thing, bestie: mailbox files have to be locked, otherwise other apps will just barge in and modify the mailbox at the same time like it's an open house. rude. 💀

the problem? different systems use different locking conventions. so lockmail uses two of the most common locking mechanisms in use, which should work reliably on most systems. iconic of it, honestly.

lockfile is the pathname to an existing mailbox file. by default, if the mailbox is already locked, lockmail tries to lock it every five seconds, and will give up after three minutes. no cap.

once the mailbox is successfully locked, lockmail runs program as a child process, with any optional arguments. and when program terminates, lockmail removes the mailbox lock and terminates itself. clean exit, no mess, we love to see it ✨

---

💅 OPTIONS 💅

• -r — if a regular lock fails, try a read-only lock instead. use this one to lock mailbox files that live in a read-only directory. slay.
• -t timeout — if the lock attempt fails, keep trying for up to timeout seconds. heads up tho: the actual timeout gets rounded up to the next five second interval, because a lock attempt is only tried every five seconds. so like, math is happening. 🧮

---

🔒 DESCRIPTION (part two: the locking lore) 🔒

this section briefly describes the locking mechanism used by lockmail. and bestie, lockmail does not play. it uses three different locking conventions in order to maximize compatibility with other mail software:

• C-Client folder locks
• dot-locks
• file locks

🎀 C-Client folder locks 🎀

mail software based on the C-Client library creates lock files named /tmp/.dddddd.iiiiii. here, dddddd and iiiiii are the device number and the inode number of the mailbox file (the st_dev and st_ino fields in the inode), written in hexadecimal. love a hex moment.

if the process ID saved in the C-Client folder lock file is not valid, lockmail concludes that it's a stale lock file, and will remove it. bye girl 👋

🚨 Note a race condition exists where a C-Client process is killed after it creates a lock file, but before saving its process ID in the lock file. the race window is very small, but it exists. and the C-Client library does not appear to ever clear out the lock file. 😭 lockmail attempts to resolve this race condition by deleting zero-length lock files that are at least five minutes old.

🌸 dot-locks 🌸

lockmail also creates, and honors, dot-lock files. dot-lock files are first created as temporary files, then linked to lockfile.lock. the link operation fails if the dot-lock file already exists. sneaky but effective.

lockmail uses an enhanced method of dot-locking, where its process ID, and the name of the server where lockmail is running, are also saved in its dot-lock file.

if the operation fails because there's an existing dot-lock file that was created by another lockmail process on the same server, and the process ID no longer exists, then that stale dot-lock file is removed immediately. in all other situations, a dot-lock file older than five minutes is considered stale, and removed.

🚨 Note a failure to create a dot-lock file is silently ignored if the reason for the failure is that lockmail doesn't have write permission in the dot-lock file's directory. and here's why that matters: the incoming mail spool directory (usually /var/mail) typically does not have global write permissions, so the attempt to create the dot-lock file in the spool directory will fail, and lockmail will be perfectly content with using file-locking only. it's fine. it's chill. it's whatever. 😌

👑 File locks 👑

the final locking mechanism lockmail uses is the operating system's file locking facility.

if lockmail fails to obtain all three locks, it will sleep for five seconds and try again. the only exception is a failure to create a dot-lock because of no write access to the dot-lock file's directory — that one is ignored.

and if lockmail still fails to obtain all required locks within the amount of time specified by the -t option (or its default value), lockmail will terminate with the EX_TEMPFAIL exit code. periodt. 💀

lockmail runs program after obtaining the last file lock, waits until program terminates, and releases all locks. ⚠️ program must terminate before any of the locks obtained by lockmail expire and are considered stale. then lockmail terminates with the same exit code as program. matching energy, fr fr.

---

🔥 EXIT STATUS 🔥

lockmail terminates with the same exit status as program.

lockmail terminates with the EX_TEMPFAIL exit status if it was unable to obtain a lock, or if program was killed by a signal. yes, even then. 🫠

---

🌈 SEE ALSO 🌈

maildrop(1)[1], sendmail(8).

---

💜 AUTHOR 💜

Sam Varshavchik Author

---

📝 NOTES 📝

1. maildrop(1) http://www.courier-mta.org/maildrop.html

---

and that's the whole vibe check, bestie 💖 this page came to you from Courier Mail Server, dated 01/10/2026, and it's called LOCKMAIL(1). go lock something. responsibly. 🎀🦋✨