From: Alejandro Colomar Date: Tue, 15 Jul 2025 22:40:28 +0000 (+0200) Subject: man/man2/fcntl.2, man/man2const/F_GETLEASE.2const: Split F_{G,S}ETLEASE from fcntl(2) X-Git-Tag: man-pages-6.15~2^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=358aa107c93082442b09d753b075c21afd7bf59c;p=thirdparty%2Fman-pages.git man/man2/fcntl.2, man/man2const/F_GETLEASE.2const: Split F_{G,S}ETLEASE from fcntl(2) Signed-off-by: Alejandro Colomar --- diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2 index fccfe2c05..a98c14f5a 100644 --- a/man/man2/fcntl.2 +++ b/man/man2/fcntl.2 @@ -881,167 +881,10 @@ POSIX has asynchronous I/O and the structure to achieve similar things; these are also available in Linux as part of the GNU C Library (glibc). .SS Leases -.B F_SETLEASE -and -.B F_GETLEASE -(Linux 2.4 onward) are used to establish a new lease, -and retrieve the current lease, on the open file description -referred to by the file descriptor -.IR 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 -.BR open (2) -or -.BR truncate (2) -the file referred to by that file descriptor. .TP -.BR F_SETLEASE \~(\f[I]int\f[]) -Set or remove a file lease according to which of the following -values is specified in the integer -.IR arg : -.RS -.TP -.B 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. -.\" The following became true in Linux 2.6.10: -.\" See the man-pages-2.09 Changelog for further info. -A read lease can be placed only on a file descriptor that -is opened read-only. -.TP -.B 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. -.TP -.B F_UNLCK -Remove our lease from the file. -.RE -.P -Leases are associated with an open file description (see -.BR open (2)). -This means that duplicate file descriptors (created by, for example, -.BR fork (2) -or -.BR dup (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 explicit -.B F_UNLCK -operation on any of these duplicate file descriptors, or when all -such file descriptors have been closed. -.P -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 -.B CAP_LEASE -capability may take out leases on arbitrary files. -.TP -.BR F_GETLEASE \~(\f[I]void\f[]) -Indicates what type of lease is associated with the file descriptor -.I fd -by returning either -.BR F_RDLCK ", " F_WRLCK ", or " F_UNLCK , -indicating, respectively, a read lease , a write lease, or no lease. -.I arg -is ignored. -.P -When a process (the "lease breaker") performs an -.BR open (2) -or -.BR truncate (2) -that conflicts with a lease established via -.BR F_SETLEASE , -the system call is blocked by the kernel and -the kernel notifies the lease holder by sending it a signal -.RB ( 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 -.B F_SETLEASE -operation specifying -.I arg -as -.BR 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 -.B F_SETLEASE -operation specifying -.I arg -as -.BR F_RDLCK . -.P -If the lease holder fails to downgrade or remove the lease within -the number of seconds specified in -.IR /proc/sys/fs/lease\-break\-time , -then the kernel forcibly removes or downgrades the lease holder's lease. -.P -Once a lease break has been initiated, -.B F_GETLEASE -returns the target lease type (either -.B F_RDLCK -or -.BR 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. -.P -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. -.P -If the lease breaker's blocked -.BR open (2) -or -.BR truncate (2) -is interrupted by a signal handler, -then the system call fails with the error -.BR EINTR , -but the other steps still occur as described above. -If the lease breaker is killed by a signal while blocked in -.BR open (2) -or -.BR truncate (2), -then the other steps still occur as described above. -If the lease breaker specifies the -.B O_NONBLOCK -flag when calling -.BR open (2), -then the call immediately fails with the error -.BR EWOULDBLOCK , -but the other steps still occur as described above. -.P -The default signal used to notify the lease holder is -.BR SIGIO , -but this can be changed using the -.B F_SETSIG -operation to -.BR fcntl (). -If a -.B F_SETSIG -operation is performed (even one specifying -.BR SIGIO ), -and the signal -handler is established using -.BR SA_SIGINFO , -then the handler will receive a -.I siginfo_t -structure as its second argument, and the -.I 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.) +.BR F_SETLEASE (2const) +.TQ +.BR F_GETLEASE (2const) .SS File and directory change notification (dnotify) .TP .BR F_NOTIFY (2const) @@ -1067,9 +910,6 @@ that has been accessed by another process. .SH RETURN VALUE For a successful call, the return value depends on the operation: .TP -.B F_GETLEASE -Type of lease held on file descriptor. -.TP .B F_GETOWN Value of file descriptor owner. .TP @@ -1177,10 +1017,8 @@ POSIX.1-2008. .BR F_GETOWN_EX , .BR F_SETOWN_EX , .BR F_GETSIG , -.BR F_SETSIG , -.BR F_GETLEASE , and -.B F_SETLEASE +.BR F_SETSIG , are Linux-specific. (Define the .B _GNU_SOURCE diff --git a/man/man2const/F_GETLEASE.2const b/man/man2const/F_GETLEASE.2const new file mode 100644 index 000000000..ff435ce2e --- /dev/null +++ b/man/man2const/F_GETLEASE.2const @@ -0,0 +1,204 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH F_GETLEASE 2const (date) "Linux man-pages (unreleased)" +.SH NAME +F_GETLEASE, +F_SETLEASE +\- +leases +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.P +.BI "int fcntl(int " fd ", F_SETLEASE, int " arg ); +.BI "int fcntl(int " fd ", F_GETLEASE);" +.fi +.SH DESCRIPTION +.SS Leases +.B F_SETLEASE +and +.B F_GETLEASE +(Linux 2.4 onward) are used to establish a new lease, +and retrieve the current lease, on the open file description +referred to by the file descriptor +.IR 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 +.BR open (2) +or +.BR truncate (2) +the file referred to by that file descriptor. +.TP +.BR F_SETLEASE \~(\f[I]int\f[]) +Set or remove a file lease according to which of the following +values is specified in the integer +.IR arg : +.RS +.TP +.B 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. +.\" The following became true in Linux 2.6.10: +.\" See the man-pages-2.09 Changelog for further info. +A read lease can be placed only on a file descriptor that +is opened read-only. +.TP +.B 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. +.TP +.B F_UNLCK +Remove our lease from the file. +.RE +.P +Leases are associated with an open file description (see +.BR open (2)). +This means that duplicate file descriptors (created by, for example, +.BR fork (2) +or +.BR dup (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 explicit +.B F_UNLCK +operation on any of these duplicate file descriptors, or when all +such file descriptors have been closed. +.P +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 +.B CAP_LEASE +capability may take out leases on arbitrary files. +.TP +.BR F_GETLEASE \~(\f[I]void\f[]) +Indicates what type of lease is associated with the file descriptor +.I fd +by returning either +.BR F_RDLCK ", " F_WRLCK ", or " F_UNLCK , +indicating, respectively, a read lease , a write lease, or no lease. +.I arg +is ignored. +.P +When a process (the "lease breaker") performs an +.BR open (2) +or +.BR truncate (2) +that conflicts with a lease established via +.BR F_SETLEASE , +the system call is blocked by the kernel and +the kernel notifies the lease holder by sending it a signal +.RB ( 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 +.B F_SETLEASE +operation specifying +.I arg +as +.BR 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 +.B F_SETLEASE +operation specifying +.I arg +as +.BR F_RDLCK . +.P +If the lease holder fails to downgrade or remove the lease within +the number of seconds specified in +.IR /proc/sys/fs/lease\-break\-time , +then the kernel forcibly removes or downgrades the lease holder's lease. +.P +Once a lease break has been initiated, +.B F_GETLEASE +returns the target lease type (either +.B F_RDLCK +or +.BR 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. +.P +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. +.P +If the lease breaker's blocked +.BR open (2) +or +.BR truncate (2) +is interrupted by a signal handler, +then the system call fails with the error +.BR EINTR , +but the other steps still occur as described above. +If the lease breaker is killed by a signal while blocked in +.BR open (2) +or +.BR truncate (2), +then the other steps still occur as described above. +If the lease breaker specifies the +.B O_NONBLOCK +flag when calling +.BR open (2), +then the call immediately fails with the error +.BR EWOULDBLOCK , +but the other steps still occur as described above. +.P +The default signal used to notify the lease holder is +.BR SIGIO , +but this can be changed using the +.B F_SETSIG +operation to +.BR fcntl (). +If a +.B F_SETSIG +operation is performed (even one specifying +.BR SIGIO ), +and the signal +handler is established using +.BR SA_SIGINFO , +then the handler will receive a +.I siginfo_t +structure as its second argument, and the +.I 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.) +.SH RETURN VALUE +.TP +.B F_GETLEASE +Type of lease held on file descriptor. +.TP +.B F_SETLEASE +Zero. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +See +.BR fcntl (2). +.SH STANDARDS +Linux. +.SH HISTORY +Linux. +.SH SEE ALSO +.BR fcntl (2)