F_GETLEASE(2const)

🦋 F_GETLEASE, F_SETLEASE — the lease manual, bestie edition

okay so bestie, you're in the F_GETLEASE(2const) page 💖 this is a section-2-const situation, and we're talking about leases — yes, file leases, not apartment leases, though honestly both are about who gets to touch the thing.

📚 LIBRARY

Standard C library (libc, -lc). yep that's it, that's the whole vibe.

✨ SYNOPSIS

#define _GNU_SOURCE
#include <fcntl.h>

int fcntl(int fd, F_SETLEASE, int arg);
int fcntl(int fd, F_GETLEASE);

both of these are fcntl() operations, so like, same function, different little command word. iykyk 💅

💖 DESCRIPTION

So here's the tea, bestie. 🌸 F_SETLEASE and F_GETLEASE are how you establish a new lease and retrieve the current lease on the open file description that fd points at.

And what even IS a lease? Okay so — a file lease is a whole mechanism where the process holding the lease (we call her the "lease holder", main character energy 👑) gets notified — by receiving a signal, no cap — when some other process (the "lease breaker", booo 🍅) tries to open(2) or truncate(2) the file that fd refers to. literally a little doorbell that rings when someone's about to mess with your file.

🔥 F_SETLEASE

Sets or removes a file lease, depending on which of these values you put in the integer arg:

• F_RDLCK — Establish a read lease. This means the calling process gets notified when the file is opened for writing or is truncated. Heads up though: a read lease can only go on a file descriptor that's opened read-only. 🎀
• F_WRLCK — Establish a write lease. This one notifies the caller when the file is opened for reading or writing, or is truncated. And a write lease may only be placed on a file if there are no other open file descriptors for the file. not one. zero. periodt. 💀
• F_UNLCK — Remove our lease from the file. bye bestie 🫶

---

okay important structural lore: leases are associated with an open file description (peep open(2)). What that means in practice is that duplicate file descriptors — the ones born from things like fork(2) or dup(2) — all refer to the same lease, and you can modify or release that lease using any of those descriptors. Also, the lease gets released either by an explicit F_UNLCK operation on any of those duplicate descriptors, or when all of those descriptors have been closed. so like, it's not per-fd, it's per-open-file-description. slay ✨

Also! Leases may be taken out only on regular files. And an unprivileged process may only take out a lease on a file whose UID (owner) matches the filesystem UID of the process. If you've got the CAP_LEASE capability though? go off, you can take out leases on arbitrary files. 👑

🌈 F_GETLEASE

Tells you what type of lease is hanging out with the file descriptor fd, by returning either F_RDLCK, F_WRLCK, or F_UNLCK — meaning a read lease, a write lease, or no lease at all. And arg is ignored here, don't even worry about it. 🙈

---

😭 the lease break storyline (this is the good part)

When a process — our lease breaker — performs an open(2) or truncate(2) that conflicts with a lease established via F_SETLEASE, the kernel blocks the system call and notifies the lease holder by sending it a signal (SIGIO by default). ✨

Then the lease holder is supposed to respond to that signal by doing whatever cleanup is required so another process can access the file (e.g., flushing cached buffers), and then either remove or downgrade her lease.

Here's how, no confusion:

• A lease is removed by performing an F_SETLEASE operation specifying arg as F_UNLCK.
• If the lease holder currently holds a write lease on the file, and the lease breaker is opening the file for reading, then it's enough for the lease holder to just downgrade the lease to a read lease — done by performing an F_SETLEASE operation specifying arg as F_RDLCK.

If the lease holder fails to downgrade or remove the lease within the number of seconds specified in /proc/sys/fs/lease-break-time, then the kernel forcibly removes or downgrades her lease. the kernel said "time's up bestie" 💀

Once a lease break has been initiated, F_GETLEASE returns the target lease type (either F_RDLCK or F_UNLCK, depending on what would be compatible with the lease breaker) — and it keeps returning that until the lease holder voluntarily downgrades or removes the lease, or the kernel forcibly does so after the lease break timer expires. 🕐

Once the lease has been voluntarily or forcibly removed or downgraded, and assuming the lease breaker hasn't unblocked its system call, the kernel permits the lease breaker's system call to proceed. 🌟

🫶 the interrupt lore (all the edge cases, we keep them)

• If the lease breaker's blocked open(2) or truncate(2) is interrupted by a signal handler, then the system call fails with the error EINTR — but the other steps still occur as described above. 😭
• If the lease breaker is killed by a signal while blocked in open(2) or truncate(2), then the other steps still occur as described above. 💀
• If the lease breaker specifies the O_NONBLOCK flag when calling open(2), then the call immediately fails with the error EWOULDBLOCK — but, you guessed it, the other steps still occur as described above. 🙈

🎀 the signal glow-up

The default signal used to notify the lease holder is SIGIO, but you can change it using the F_SETSIG operation to fcntl().

And here's the cute part: if an F_SETSIG operation is performed (even one specifying SIGIO), and the signal handler is established using SA_SIGINFO, then the handler will receive a siginfo_t structure as its second argument, and the si_fd field of that argument will hold the file descriptor of the leased file that has been accessed by another process. (This is useful if the caller holds leases against multiple files.) ✨ such a serve.

⭐ RETURN VALUE

• F_GETLEASE — Type of lease held on file descriptor.
• F_SETLEASE — Zero.

On error, -1 is returned, and errno is set to indicate the error. 😔

💅 ERRORS

See fcntl(2).

These operations can also fail with the following error codes:

• EAGAIN — The operation is prohibited because the file is open in a way that conflicts with the requested lease.
• EINVAL — The operation is prohibited because the underlying filesystem doesn't support leases, or because fd does not represent a regular file.

🌸 STANDARDS

Linux. 🐧

🧚 HISTORY

Linux 2.4.

👀 SEE ALSO

• fcntl(2)

---

ok that's the whole page, bestie. go forth and lease responsibly 🫶

mwah 💋 this was the F_GETLEASE(2const) page from Linux man-pages 6.20, dated 2026-01-14. love u, bye! 🎀✨