FLOCK(2)

💖 FLOCK(2) 💖

okay bestie, welcome to the flock(2) manual page — yes, that's a section 2 system call, we're in the System Calls Manual today and it's giving ✨kernel core✨ energy. grab a boba, we're locking files.

---

✨ NAME ✨

flock — apply or remove an advisory lock on an open file 🎀

---

📚 LIBRARY 📚

Standard C Library (libc, -lc). yeah. the basics. the girlies. 💅

---

🦋 SYNOPSIS 🦋

#include <sys/file.h>
#define   LOCK_SH        0x01      /* shared file lock */
#define   LOCK_EX        0x02      /* exclusive file lock */
#define   LOCK_NB        0x04      /* do not block when locking */
#define   LOCK_UN        0x08      /* unlock file */

int
flock(int fd, int operation);

the way that's just the whole vibe up front, no cap. 🌸

---

👑 DESCRIPTION 👑

so. the flock() system call applies or removes an advisory lock on the file associated with the file descriptor fd. that's the whole gig.

you apply a lock by passing an operation argument that's either LOCK_SH or LOCK_EX, and you can optionally add LOCK_NB on top. wanna unlock an existing lock? operation should be LOCK_UN. periodt.

here's the flag lineup, one by one, because we don't skip anything in this house:

• LOCK_SH — 0x01, the shared file lock 💖
• LOCK_EX — 0x02, the exclusive file lock 👑
• LOCK_NB — 0x04, do not block when locking 🛑
• LOCK_UN — 0x08, unlock the file 🔓

now, about "advisory" — it's advisory, bestie. advisory locks let cooperating processes do consistent operations on files, but they do not guarantee consistency. like, i.e., processes may still access files without using advisory locks, possibly resulting in inconsistencies. it's a vibe agreement, not a bodyguard. 😭

the locking mechanism allows two types of locks: shared locks and exclusive locks. at any time multiple shared locks may be applied to a file, but at no time are multiple exclusive locks — or both shared and exclusive locks — allowed simultaneously on a file. one exclusive, that's the rule, don't fight it. 💀

a shared lock may be upgraded to an exclusive lock, and vice versa, simply by specifying the appropriate lock type. what happens under the hood? the previous lock gets released and the new lock gets applied — possibly after other processes have gained and released the lock. so like, you might be waiting in line behind the group chat. 🙈

requesting a lock on an object that's already locked normally causes the caller to be blocked until the lock may be acquired. but if LOCK_NB is included in operation, that does not happen — instead the call will fail and the error EWOULDBLOCK will be returned. no waiting, just rejection. iconic honestly.

---

📝 NOTES 📝

locks are on files, not file descriptors. read that again, bestie, it matters.

file descriptors duplicated through dup(2) or fork(2) do not result in multiple instances of a lock — they're multiple references to a single lock. and here's the wild part: if a process holding a lock on a file forks, and the child explicitly unlocks the file, the parent will lose its lock. family drama, literally. 😭

the flock(), fcntl(2), and lockf(3) locks are compatible 🫶. processes using different locking interfaces can cooperate over the same file safely. however, only one of such interfaces should be used within the same process. and: if a file is locked by a process through flock(), any record within the file will be seen as locked from the viewpoint of another process using fcntl(2) or lockf(3), and vice versa. cross-compatible, no cap. ✨

processes blocked awaiting a lock may be awakened by signals. ⚡

---

🫶 RETURN VALUES 🫶

• the flock() function returns the value 0 if successful — slay 💅
• otherwise the value -1 is returned, and the global variable errno is set to indicate the error 😔

---

💀 ERRORS 💀

the flock() system call fails if:

• [EWOULDBLOCK] — the file is locked and the LOCK_NB option was specified. 🙅
• [EBADF] — the argument fd is an invalid descriptor.
• [EINVAL] — the argument fd refers to an object other than a file.
• [EOPNOTSUPP] — the argument fd refers to an object that does not support file locking.
• [ENOLCK] — a lock was requested, but no locks are available.

---

🌈 SEE ALSO 🌈

close(2), dup(2), execve(2), fcntl(2), fork(2), open(2), flopen(3), lockf(3)

go read them, bestie, the lore is deep. 📖

---

⭐ HISTORY ⭐

the flock() system call appeared in 4.2BSD. ancient. legendary. the blueprint. 👑

---

and that's the whole page, fr fr 💖 this edition came from the Debian crew, dated November 9, 2011, filed under FLOCK(2) — so when you're done locking and unlocking like the main character you are, go touch some grass, hydrate, and remember: advisory means advisory. mwah. 🎀🦋✨