MAILOCK(3)

💌 MAILOCK — the maillock(3) glow-up 💌

okay bestie, sit down, hydrate, and let me tell you about mailbox lockfiles ✨ this is maillock(3) from the Linux Programmer's Manual, and it's literally the girlies who keep your mail from getting trampled when everybody's writing at once. no cap.

✨ NAME ✨

maillock, mailunlock, touchlock — manage mailbox lockfiles 🎀

🌸 SYNOPSIS 🌸

#include <maillock.h>

cc [ flag ... ] file ... -llockfile [ library ]

int maillock( const char *user, int retrycnt );
void mailunlock( void );
void touchlock( void );

🦋 DESCRIPTION 🦋

so maillock tries to create a lockfile for the user's mailbox in an NFS-safe (or at least NFS-resistant) way 💅 the whole algorithm is documented over in lockfile_create(3) if you wanna go read the lore.

the mailbox is typically hanging out in /var/mail, which means the lockfile name becomes /var/mail/USERNAME.lock — iconic, consistent, we love her. but if the environment variable $MAIL is set, and it ends with the same username that you passed to maillock(), then that file gets taken as the mailbox to lock instead. plot twist 🌈

now here's the tea: there is genuinely no good way to see if a lockfile is stale 😭 so the rule is — if the lockfile is older than 5 minutes, it gets removed. which is exactly why touchlock exists: while you're holding the lock, you have to refresh it regularly (every minute or so) by calling touchlock (). don't skip your skincare, don't skip your touchlock 🧖♀️

and finally, mailunlock removes the lockfile. clean up after yourself, queen 👑

💖 RETURN VALUES 💖

maillock returns one of these status codes, and yes we're listing all of them, periodt:

#define L_SUCCESS   0    /* Lockfile created                     */
#define L_NAMELEN   1    /* Recipient name too long (> 13 chars) */
#define L_TMPLOCK   2    /* Error creating tmp lockfile          */
#define L_TMPWRITE  3    /* Can't write pid int tmp lockfile     */
#define L_MAXTRYS   4    /* Failed after max. number of attempts */
#define L_ERROR     5    /* Unknown error; check errno           */
#define L_RMSTALE   8    /* Failed to remove stale lockfile       */

🎀 NOTES 🎀

okay important stuff, bestie, don't scroll past this 🙈

• these functions are not thread safe. like, at all. if you need thread safe functions, or you need to lock other mailbox-(like) files that aren't in the standard location, use lockfile_create(3) instead. she's the upgrade 💅
• these functions call lockfile_create(3) to do the actual work. that function might spawn a set group-id executable to do the real locking if the current process doesn't have enough privileges 👀 so yeah, permissions drama, as always.
• there are some issues with flushing the kernel's attribute cache if you're using NFS — go read the lockfile_create(3) manpage for that whole saga. iykyk 😭

🍓 FILES 🍓

• /var/mail/user.lock
• /usr/lib/liblockfile.so.1

👑 AUTHOR 👑

Miquel van Smoorenburg — we stan a legend 🫶

🌈 SEE ALSO 🌈

• lockfile_create(3)
• lockfile_touch (3)
• lockfile_remove(3)

and that's the whole vibe check, bestie 💜 this page came from the Linux Manpage crew, dated 28 March 2001 — yeah, she's vintage, and she still ate. go lock your mailboxes responsibly ✨💌