--- name: "F_GETLEASE" section: "2const" platform: "linux" package: "man-pages" version: "6.19-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/F_GETLEASE" --- # F\_GETLEASE(2const) leases ## NAME F\_GETLEASE, F\_SETLEASE - leases ## LIBRARY Standard C library (*libc*, *-lc*) ## SYNOPSIS ``` #define _GNU_SOURCE #include ``` **int fcntl(int** *fd***, F\_SETLEASE, int** *arg***);** **int fcntl(int** *fd***, F\_GETLEASE);** ## DESCRIPTION **F\_SETLEASE** and **F\_GETLEASE** are used to establish a new lease, and retrieve the current lease, on the open file description referred to by the file descriptor *fd*. A file lease provides a mechanism whereby the process holding the lease (the "lease holder") is notified (via delivery of a signal) when a process (the "lease breaker") tries to [**open**(2)](/open/2.md) or [**truncate**(2)](/truncate/2.md) the file referred to by that file descriptor. - **F\_SETLEASE** Set or remove a file lease according to which of the following values is specified in the integer *arg*: - **F\_RDLCK** Establish a read lease. This will cause the calling process to be notified when the file is opened for writing or is truncated. A read lease can be placed only on a file descriptor that is opened read-only. - **F\_WRLCK** Establish a write lease. This will cause the caller to be notified when the file is opened for reading or writing or is truncated. A write lease may be placed on a file only if there are no other open file descriptors for the file. - **F\_UNLCK** Remove our lease from the file. Leases are associated with an open file description (see [**open**(2)](/open/2.md)). This means that duplicate file descriptors (created by, for example, [**fork**(2)](/fork/2.md) or [**dup**(2)](/dup/2.md)) refer to the same lease, and this lease may be modified or released using any of these descriptors. Furthermore, the lease is released by either an explicit **F\_UNLCK** operation on any of these duplicate file descriptors, or when all such file descriptors have been closed. Leases may be taken out only on regular files. An unprivileged process may take out a lease only on a file whose UID (owner) matches the filesystem UID of the process. A process with the **CAP\_LEASE** capability may take out leases on arbitrary files. - **F\_GETLEASE** Indicates what type of lease is associated with the file descriptor *fd* by returning either **F\_RDLCK**, **F\_WRLCK**, or **F\_UNLCK**, indicating, respectively, a read lease, a write lease, or no lease. *arg* is ignored. When a process (the "lease breaker") performs an [**open**(2)](/open/2.md) or [**truncate**(2)](/truncate/2.md) that conflicts with a lease established via **F\_SETLEASE**, the system call is blocked by the kernel and the kernel notifies the lease holder by sending it a signal (**SIGIO** by default). The lease holder should respond to receipt of this signal by doing whatever cleanup is required in preparation for the file to be accessed by another process (e.g., flushing cached buffers) and then either remove or downgrade its lease. 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 is sufficient for the lease holder to downgrade the lease to a read lease. This is 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 the lease holder's lease. 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) 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 has not unblocked its system call, the kernel permits the lease breaker's system call to proceed. If the lease breaker's blocked [**open**(2)](/open/2.md) or [**truncate**(2)](/truncate/2.md) 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)](/open/2.md) or [**truncate**(2)](/truncate/2.md), then the other steps still occur as described above. If the lease breaker specifies the **O\_NONBLOCK** flag when calling [**open**(2)](/open/2.md), then the call immediately fails with the error **EWOULDBLOCK**, but the other steps still occur as described above. The default signal used to notify the lease holder is **SIGIO**, but this can be changed using the **F\_SETSIG** operation to **fcntl**(). If a **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 this 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.) ## 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)](/fcntl/2.md). 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)](/fcntl/2.md)