HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |SEE ALSO |COLOPHON | |
F_GETLEASE(2const)F_GETLEASE(2const)F_GETLEASE, F_SETLEASE - leases
Standard C library (libc,-lc)
#define _GNU_SOURCE#include <fcntl.h>int fcntl(intfd, F_SETLEASE, intarg);int fcntl(intfd, F_GETLEASE);
LeasesF_SETLEASEandF_GETLEASEare used to establish a new lease, and retrieve the current lease, on the open file description referred to by the file descriptorfd. 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 toopen(2) ortruncate(2) 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 integerarg:F_RDLCK Take out 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 Take out 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 (seeopen(2)). This means that duplicate file descriptors (created by, for example,fork(2) ordup(2)) 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 explicitF_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 theCAP_LEASEcapability may take out leases on arbitrary files.F_GETLEASE Indicates what type of lease is associated with the file descriptorfd by returning eitherF_RDLCK,F_WRLCK, orF_UNLCK, indicating, respectively, a read lease , a write lease, or no lease.arg is ignored. When a process (the "lease breaker") performs anopen(2) ortruncate(2) that conflicts with a lease established viaF_SETLEASE, the system call is blocked by the kernel and the kernel notifies the lease holder by sending it a signal (SIGIOby 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 anF_SETLEASEoperation specifyingarg asF_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 anF_SETLEASEoperation specifyingarg asF_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_GETLEASEreturns the target lease type (eitherF_RDLCKorF_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 blockedopen(2) ortruncate(2) is interrupted by a signal handler, then the system call fails with the errorEINTR, but the other steps still occur as described above. If the lease breaker is killed by a signal while blocked inopen(2) ortruncate(2), then the other steps still occur as described above. If the lease breaker specifies theO_NONBLOCK flag when callingopen(2), then the call immediately fails with the errorEWOULDBLOCK, but the other steps still occur as described above. The default signal used to notify the lease holder isSIGIO, but this can be changed using theF_SETSIGoperation tofcntl(). If aF_SETSIGoperation is performed (even one specifyingSIGIO), and the signal handler is established usingSA_SIGINFO, then the handler will receive asiginfo_t structure as its second argument, and thesi_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.)
F_GETLEASE Type of lease held on file descriptor.F_SETLEASE Zero. On error, -1 is returned, anderrno is set to indicate the error.
Seefcntl(2).
Linux.
Linux 2.4.
fcntl(2)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-07-20F_GETLEASE(2const)Pages that refer to this page:fcntl(2)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |