[PATCH man-pages v2 0/2] man/man2const: clean up F_GETLEASE and add F_SETDELEG/F_GETDELEG manpages

[PATCH man-pages v2 0/2] man/man2const: clean up F_GETLEASE and add F_SETDELEG/F_GETDELEG manpages

[Jeff Layton]

Hopefully this set is closer to being mergeable. Let me know if I missed
anything. Not sure if I got the semantic newline thing right, but I
think it's at least slightly more readable now.

Thanks for the review so far!

Signed-off-by: Jeff Layton <jlayton@kernel.org>
---
Changes in v2:
- Add patch to clean up F_GETLEASE manpage
- Grammatical and formatting cleanups for F_GETDELEG manpage
- Link to v1: https://lore.kernel.org/r/20260112-master-v1-1-3948465faaae@kernel.org

---
Jeff Layton (2):
      man/man2const: document the new F_SETDELEG and F_GETDELEG constants
      man/man2const: clean up the F_GETLEASE manpage

 man/man2/fcntl.2                |   5 +
 man/man2const/F_GETDELEG.2const | 246 ++++++++++++++++++++++++++++++++++++++++
 man/man2const/F_GETLEASE.2const |  22 +++-
 man/man2const/F_SETDELEG.2const |   1 +
 4 files changed, 269 insertions(+), 5 deletions(-)
---
base-commit: 753ac20a01007417aa993e70d290f51840e2f477
change-id: 20260112-master-23a1ede99836

Best regards,
-- 
Jeff Layton <jlayton@kernel.org>

[PATCH man-pages v2 1/2] man/man2const: document the new F_SETDELEG and F_GETDELEG constants

[Jeff Layton]

With v6.19, userland will be able to request a delegation on a file or
directory. These new objects act a lot like file leases, but are based
on NFSv4 file and directory delegations.

Add new F_GETDELEG and F_SETDELEG manpages to document them.

Signed-off-by: Jeff Layton <jlayton@kernel.org>
---
 man/man2/fcntl.2                |   5 +
 man/man2const/F_GETDELEG.2const | 246 ++++++++++++++++++++++++++++++++++++++++
 man/man2const/F_SETDELEG.2const |   1 +
 3 files changed, 252 insertions(+)

diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2
index 7f34e332ef9070867c4cdb51e8c5d4991b4fac22..f05d559da149e6a4cc8ae935ffa32111deabd94d 100644
--- a/man/man2/fcntl.2
+++ b/man/man2/fcntl.2
@@ -78,6 +78,11 @@ indicating that the kernel does not recognize this value.
 .BR F_SETLEASE (2const)
 .TQ
 .BR F_GETLEASE (2const)
+.SS Delegations
+.TP
+.BR F_SETDELEG (2const)
+.TQ
+.BR F_GETDELEG (2const)
 .SS File and directory change notification (dnotify)
 .TP
 .BR F_NOTIFY (2const)
diff --git a/man/man2const/F_GETDELEG.2const b/man/man2const/F_GETDELEG.2const
new file mode 100644
index 0000000000000000000000000000000000000000..43bfac5707b189a4e16b7068674d5ddc0ec98913
--- /dev/null
+++ b/man/man2const/F_GETDELEG.2const
@@ -0,0 +1,246 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH F_GETDELEG 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+F_GETDELEG,
+F_SETDELEG
+\-
+delegations
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #define _GNU_SOURCE
+.B #include <fcntl.h>
+
+.fi
+.EX
+struct delegation {
+        __u32   d_flags;
+        __u16   d_type;
+        __u16   __pad;
+};
+.EE
+.P
+.nf
+.BI "int fcntl(int " fd ", F_SETDELEG, const struct delegation *" deleg );
+.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
+.fi
+.SH DESCRIPTION
+.B F_SETDELEG
+and
+.B F_GETDELEG
+are used to establish a new delegation,
+and retrieve the current delegation,
+on the open file description referred to by the file descriptor
+.IR fd .
+.P
+A file delegation is a mechanism whereby
+the process holding the delegation (the "delegation holder")
+is notified (via delivery of a signal)
+when a process (the "delegation breaker") tries to
+.BR open (2)
+or
+.BR truncate (2)
+the file referred to by that file descriptor, or attempts to
+.BR unlink (2)
+or
+.BR rename (2)
+the dentry that was originally opened for the file.
+.P
+Delegations can also be set on directory file descriptors.
+The holder of a directory delegation will be notified if there is a
+create, delete or rename of a dirent within the directory.
+.TP
+.B F_SETDELEG
+Set or remove a file or directory delegation according to the
+value specified in
+.IR deleg->d_type :
+.RS
+.TP
+.B F_RDLCK
+Establish a read delegation.
+This will cause the calling process to be notified when the file is opened for writing,
+or is truncated, unlinked or renamed.
+A read delegation can be placed only on a file descriptor that is opened read-only.
+If
+.IR fd
+refers to a directory,
+then the calling process will be notified if there are changes to filenames within the directory,
+or when the directory itself is renamed.
+.TP
+.B F_WRLCK
+Establish a write delegation.
+This will cause the caller to be notified when the file is opened for reading or writing,
+or is truncated, renamed or unlinked.
+A write delegation may be placed on a file only if there are no other open file descriptors for the file.
+The file must be opened for write in order to set a write delegation on it.
+Write delegations cannot be set on directory file descriptors.
+.TP
+.B F_UNLCK
+Remove our delegation from the file.
+.RE
+.P
+Like leases, delegations 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 delegation,
+and this delegation may be modified or released using any of these descriptors.
+Furthermore, the delegation 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
+An unprivileged process may take out a delegation 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 delegations on arbitrary files or directories.
+.TP
+.B F_GETDELEG
+Indicates what type of delegation is associated with the file descriptor
+.I fd
+by setting the
+.IR d_type
+field in
+.IR deleg
+to either
+.BR F_RDLCK ,
+.BR F_WRLCK ,
+or
+.BR F_UNLCK ,
+indicating, respectively, a read delegation, a write delegation, or no delegation.
+.P
+When a process (the "delegation breaker") performs an activity that conflicts with a delegation
+established via
+.BR F_SETDELEG ,
+the system call is blocked by the kernel and
+the kernel notifies the delegation holder by sending it a signal
+.RB ( SIGIO
+by default).
+The delegation 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 delegation.
+A delegation is removed by performing an
+.B F_SETDELEG
+operation specifying
+.I d_type
+in
+.I deleg
+as
+.BR F_UNLCK .
+If the delegation holder currently holds a write delegation on the file,
+and the delegation breaker is opening the file for reading,
+then it is sufficient for the delegation holder to downgrade
+the delegation to a read delegation.
+This is done by performing an
+.B F_SETDELEG
+operation specifying
+.I d_type
+in
+.I deleg
+as
+.BR F_RDLCK .
+.P
+If the delegation holder fails to downgrade or remove the delegation within
+the number of seconds specified in
+.IR /proc/sys/fs/lease\-break\-time ,
+then the kernel forcibly removes or downgrades the delegation holder's delegation.
+.P
+Once a delegation break has been initiated,
+.B F_GETDELEG
+returns the target delegation type in the
+.I d_type
+field in
+.I deleg
+(either
+.B F_RDLCK
+or
+.BR F_UNLCK ,
+depending on what would be compatible with the delegation breaker)
+until the delegation holder voluntarily downgrades or removes the delegation or
+the kernel forcibly does so after the delegation break timer expires.
+.P
+Once the delegation has been voluntarily or forcibly removed or downgraded,
+and assuming the delegation breaker has not unblocked its system call,
+the kernel permits the delegation breaker's system call to proceed.
+.P
+If the delegation breaker's blocked system call
+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 delegation 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 delegation 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 delegation 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 file with the delegation
+that has been accessed by another process.
+(This is useful if the caller holds delegations against multiple files.)
+.SH NOTES
+Delegations were designed to implement NFSv4 delegations for the Linux NFS server.
+.SH RETURN VALUE
+On success zero is returned. On error, \-1 is returned, and
+.I errno
+is set to indicate the error. A successful
+.B F_GETDELEG
+call will also update the
+.I deleg->d_type
+field.
+.SH ERRORS
+See
+.BR fcntl (2).
+These operations can also return the following errors:
+.TP
+.B EAGAIN
+The operation was prohibited because the file was held open in a way that conflicts with the requested delegation.
+.TP
+.B EINVAL
+The operation was prohibited because the caller tried to set a
+.B F_WRLCK
+delegation and
+.I fd
+represents a directory,
+or
+.I fd
+doesn't represent a file or directory, or
+the underlying filesystem doesn't support delegations.
+.SH STANDARDS
+Linux, IETF RFC\ 8881.
+.SH HISTORY
+Linux 6.19.
+.SH SEE ALSO
+.BR fcntl (2) ,
+.BR F_SETLEASE (2const)
diff --git a/man/man2const/F_SETDELEG.2const b/man/man2const/F_SETDELEG.2const
new file mode 100644
index 0000000000000000000000000000000000000000..acabdfc139fb3d753dbf3061c31d59332d046c63
--- /dev/null
+++ b/man/man2const/F_SETDELEG.2const
@@ -0,0 +1 @@
+.so man2const/F_GETDELEG.2const

-- 
2.52.0

Re: [PATCH man-pages v2 1/2] man/man2const: document the new F_SETDELEG and F_GETDELEG constants

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 790 bytes --]

Hi Jeff,

The following observation is not a blocker.

At 2026-01-14T12:35:24-0500, Jeff Layton wrote:
[...]
> +.P
> +A file delegation is a mechanism whereby
> +the process holding the delegation (the "delegation holder")
> +is notified (via delivery of a signal)
> +when a process (the "delegation breaker") tries to

I recommend use of typographer's quotes marks in prose (contrast code).

groff_man_style(7):
     \[lq]
     \[rq]  Left and right double quotation marks.  Use these for paired
            directional double quotes, “like this”.

These look better in typeset output (like PDF) and on UTF-8 terminals,
and avoid collisions with `"` when searching man(7) documents in source
and, on the aforemented devices, as rendered too.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH man-pages v2 1/2] man/man2const: document the new F_SETDELEG and F_GETDELEG constants

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1209 bytes --]

Hi Branden, Jeff,

On Wed, Jan 14, 2026 at 11:50:48AM -0600, G. Branden Robinson wrote:
> Hi Jeff,
> 
> The following observation is not a blocker.
> 
> At 2026-01-14T12:35:24-0500, Jeff Layton wrote:
> [...]
> > +.P
> > +A file delegation is a mechanism whereby
> > +the process holding the delegation (the "delegation holder")
> > +is notified (via delivery of a signal)
> > +when a process (the "delegation breaker") tries to
> 
> I recommend use of typographer's quotes marks in prose (contrast code).
> 
> groff_man_style(7):
>      \[lq]
>      \[rq]  Left and right double quotation marks.  Use these for paired
>             directional double quotes, “like this”.

I don't have a strong opinion in either way.  However, I'd say I should
do a global pass before asking contributors to do this in new code.

For now, I'll take the patch with the '"'.

Thanks!


Have a lovely night!
Alex

> These look better in typeset output (like PDF) and on UTF-8 terminals,
> and avoid collisions with `"` when searching man(7) documents in source
> and, on the aforemented devices, as rendered too.
> 
> Regards,
> Branden



-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH man-pages v2 1/2] man/man2const: document the new F_SETDELEG and F_GETDELEG constants

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 20466 bytes --]

Hi Jeff,

On Wed, Jan 14, 2026 at 12:35:24PM -0500, Jeff Layton wrote:
> With v6.19, userland will be able to request a delegation on a file or
> directory. These new objects act a lot like file leases, but are based
> on NFSv4 file and directory delegations.
> 
> Add new F_GETDELEG and F_SETDELEG manpages to document them.
> 
> Signed-off-by: Jeff Layton <jlayton@kernel.org>

I've applied a large number of minor changes to the patch.  I have not
applied it yet, as I'd like you to have a look at it, and answer a
question or two.  I'd also like to review it again in case I made any
mistakes.

I've commented below on the changes, and have one or two questions that
need your attention.  I'll also reply with the patch updated with these
changes, so that you don't need to manually apply these changes.

See below.


Have a lovely day!
Alex

> ---
>  man/man2/fcntl.2                |   5 +
>  man/man2const/F_GETDELEG.2const | 246 ++++++++++++++++++++++++++++++++++++++++
>  man/man2const/F_SETDELEG.2const |   1 +
>  3 files changed, 252 insertions(+)
> 
> diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2
> index 7f34e332ef9070867c4cdb51e8c5d4991b4fac22..f05d559da149e6a4cc8ae935ffa32111deabd94d 100644
> --- a/man/man2/fcntl.2
> +++ b/man/man2/fcntl.2
> @@ -78,6 +78,11 @@ indicating that the kernel does not recognize this value.
>  .BR F_SETLEASE (2const)
>  .TQ
>  .BR F_GETLEASE (2const)
> +.SS Delegations
> +.TP
> +.BR F_SETDELEG (2const)
> +.TQ
> +.BR F_GETDELEG (2const)
>  .SS File and directory change notification (dnotify)
>  .TP
>  .BR F_NOTIFY (2const)
> diff --git a/man/man2const/F_GETDELEG.2const b/man/man2const/F_GETDELEG.2const
> new file mode 100644
> index 0000000000000000000000000000000000000000..43bfac5707b189a4e16b7068674d5ddc0ec98913
> --- /dev/null
> +++ b/man/man2const/F_GETDELEG.2const
> @@ -0,0 +1,246 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH F_GETDELEG 2const (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +F_GETDELEG,
> +F_SETDELEG
> +\-
> +delegations
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.B #define _GNU_SOURCE
> +.B #include <fcntl.h>
> +
> +.fi
> +.EX
> +struct delegation {
> +        __u32   d_flags;
> +        __u16   d_type;
> +        __u16   __pad;
> +};
> +.EE
> +.P
> +.nf
> +.BI "int fcntl(int " fd ", F_SETDELEG, const struct delegation *" deleg );
> +.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
> +.fi

I'd reorder this to minimize nf/fi and EX/EE pairs:

	@@ -15,20 +15,18 @@ .SH SYNOPSIS
	 .nf
	 .B #define _GNU_SOURCE
	 .B #include <fcntl.h>
	-
	-.fi
	-.EX
	-struct delegation {
	-        __u32   d_flags;
	-        __u16   d_type;
	-        __u16   __pad;
	-};
	-.EE
	 .P
	-.nf
	 .BI "int fcntl(int " fd ", F_SETDELEG, const struct delegation *" deleg );
	 .BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
	 .fi
	+.P
	+.EX
	+struct delegation {
	+       __u32  d_flags;
	+       __u16  d_type;
	+       __u16  __pad;
	+};
	+.EE
	 .SH DESCRIPTION
	 .B F_SETDELEG
	 and

> +.SH DESCRIPTION
> +.B F_SETDELEG
> +and
> +.B F_GETDELEG
> +are used to establish a new delegation,
> +and retrieve the current delegation,
> +on the open file description referred to by the file descriptor
> +.IR fd .
> +.P
> +A file delegation is a mechanism whereby
> +the process holding the delegation (the "delegation holder")
> +is notified (via delivery of a signal)
> +when a process (the "delegation breaker") tries to
> +.BR open (2)
> +or
> +.BR truncate (2)
> +the file referred to by that file descriptor, or attempts to

I'd s/attempts/tries/, for consistency with the preceding clause.

	@@ -41,11 +39,13 @@ .SH DESCRIPTION
	 A file delegation is a mechanism whereby
	 the process holding the delegation (the "delegation holder")
	 is notified (via delivery of a signal)
	-when a process (the "delegation breaker") tries to
	+when a process (the "delegation breaker")
	+tries to
	 .BR open (2)
	 or
	 .BR truncate (2)
	-the file referred to by that file descriptor, or attempts to
	+the file referred to by that file descriptor,
	+or tries to
	 .BR unlink (2)
	 or
	 .BR rename (2)

> +.BR unlink (2)
> +or
> +.BR rename (2)
> +the dentry that was originally opened for the file.
> +.P
> +Delegations can also be set on directory file descriptors.
> +The holder of a directory delegation will be notified if there is a
> +create, delete or rename of a dirent within the directory.

We use the Oxform comma, which separates also the last two elements in
an or/and chain:

	@@ -53,7 +53,7 @@ .SH DESCRIPTION
	 .P
	 Delegations can also be set on directory file descriptors.
	 The holder of a directory delegation will be notified if there is a
	-create, delete or rename of a dirent within the directory.
	+create, delete, or rename of a dirent within the directory.
	 .TP
	 .B F_SETDELEG
	 Set or remove a file or directory delegation according to the

> +.TP
> +.B F_SETDELEG
> +Set or remove a file or directory delegation according to the
> +value specified in
> +.IR deleg->d_type :
> +.RS
> +.TP
> +.B F_RDLCK
> +Establish a read delegation.
> +This will cause the calling process to be notified when the file is opened for writing,

We have a hard limit of 80 columns in source code.

	@@
	 .TP
	 .B F_RDLCK
	 Establish a read delegation.
	-This will cause the calling process to be notified when the file is opened for writing,
	+This will cause the calling process to be notified
	+when the file is
	+opened for writing,
	 or is truncated, unlinked or renamed.
	-A read delegation can be placed only on a file descriptor that is opened read-only.
	+A read delegation can be placed
	+only on a file descriptor that is opened read-only.
	+.IP
	 If

> +or is truncated, unlinked or renamed.
> +A read delegation can be placed only on a file descriptor that is opened read-only.

I'd separate the following sentence into a new paragraph.

> +If
> +.IR fd

s/IR/I/

	@@
	 If
	-.IR fd
	+.I fd
	 refers to a directory,
	 then the calling process will be notified if there are changes to filenames within the directory,
	 or when the directory itself is renamed.

> +refers to a directory,
> +then the calling process will be notified if there are changes to filenames within the directory,
> +or when the directory itself is renamed.

80-col

	@@
	 refers to a directory,
	-then the calling process will be notified if there are changes to filenames within the directory,
	+then the calling process will be notified
	+if there are changes to filenames within the directory,
	 or when the directory itself is renamed.
	 .TP
	 .B F_WRLCK

> +.TP
> +.B F_WRLCK
> +Establish a write delegation.
> +This will cause the caller to be notified when the file is opened for reading or writing,
> +or is truncated, renamed or unlinked.
> +A write delegation may be placed on a file only if there are no other open file descriptors for the file.
> +The file must be opened for write in order to set a write delegation on it.
> +Write delegations cannot be set on directory file descriptors.
> +.TP
> +.B F_UNLCK
> +Remove our delegation from the file.
> +.RE
> +.P
> +Like leases, delegations 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 delegation,
> +and this delegation may be modified or released using any of these descriptors.
> +Furthermore, the delegation 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
> +An unprivileged process may take out a delegation only on a file whose UID (owner) matches the filesystem UID of the process.

Some more semantic newlines:

	@@ -84,23 +89,29 @@ .SH DESCRIPTION
	 Remove our delegation from the file.
	 .RE
	 .P
	-Like leases, delegations are associated with an open file description (see
	+Like leases,
	+delegations are associated with an open file description
	+(see
	 .BR open (2)).
	-This means that duplicate file descriptors (created by, for example,
	+This means that duplicate file descriptors
	+(created by, for example,
	 .BR fork (2)
	 or
	 .BR dup (2))
	 refer to the same delegation,
	-and this delegation may be modified or released using any of these descriptors.
	-Furthermore, the delegation is released by either an explicit
	+and this delegation may be modified or released
	+using any of these descriptors.
	+Furthermore,
	+the delegation 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
	-An unprivileged process may take out a delegation only on a file whose UID (owner) matches the filesystem UID of the process.
	+An unprivileged process may establish a delegation
	+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 delegations on arbitrary files or directories.
	+capability may establish delegations on arbitrary files and directories.
	 .TP
	 .B F_GETDELEG
	 Indicates what type of delegation is associated with the file descriptor


> +A process with the
> +.B CAP_LEASE
> +capability may take out delegations on arbitrary files or directories.
> +.TP
> +.B F_GETDELEG
> +Indicates what type of delegation is associated with the file descriptor
> +.I fd
> +by setting the
> +.IR d_type
> +field in
> +.IR deleg

	@@ -107,6 +118,4 @@ .SH DESCRIPTION
	 .I fd
	-by setting the
	-.IR d_type
	-field in
	-.IR deleg
	+by setting
	+.I deleg->d_type
	 to either

> +to either
> +.BR F_RDLCK ,
> +.BR F_WRLCK ,
> +or
> +.BR F_UNLCK ,
> +indicating, respectively, a read delegation, a write delegation, or no delegation.
> +.P
> +When a process (the "delegation breaker") performs an activity that conflicts with a delegation
> +established via
> +.BR F_SETDELEG ,
> +the system call is blocked by the kernel and
> +the kernel notifies the delegation holder by sending it a signal
> +.RB ( SIGIO
> +by default).
> +The delegation 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 delegation.

More semantic newlines:

	@@ -116,15 +125,19 @@ .SH DESCRIPTION
	 .BR F_UNLCK ,
	-indicating, respectively, a read delegation, a write delegation, or no delegation.
	+indicating, respectively,
	+a read delegation, a write delegation, or no delegation.
	 .P
	-When a process (the "delegation breaker") performs an activity that conflicts with a delegation
	+When a process (the "delegation breaker")
	+performs an activity that conflicts with a delegation
	 established via
	 .BR F_SETDELEG ,
	-the system call is blocked by the kernel and
	-the kernel notifies the delegation holder by sending it a signal
	+the system call is blocked by the kernel
	+and the kernel notifies the delegation holder by sending it a signal
	 .RB ( SIGIO
	 by default).
	-The delegation 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 delegation.
	+The delegation 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 delegation.
	 A delegation is removed by performing an


> +A delegation is removed by performing an
> +.B F_SETDELEG
> +operation specifying
> +.I d_type
> +in
> +.I deleg

	@@ -132,5 +145,3 @@ .SH DESCRIPTION
	 operation specifying
	-.I d_type
	-in
	-.I deleg
	+.I deleg->d_type
	 as

> +as
> +.BR F_UNLCK .
> +If the delegation holder currently holds a write delegation on the file,
> +and the delegation breaker is opening the file for reading,
> +then it is sufficient for the delegation holder to downgrade
> +the delegation to a read delegation.

More semantic newlines:

	@@
	 .BR F_UNLCK .
	-If the delegation holder currently holds a write delegation on the file,
	-and the delegation breaker is opening the file for reading,
	-then it is sufficient for the delegation holder to downgrade
	-the delegation to a read delegation.
	+If the delegation holder currently holds
	+a write delegation on the file,
	+and the delegation breaker
	+is opening the file for reading,
	+then it is sufficient for the delegation holder to
	+downgrade the delegation to a read delegation.
	 This is done by performing an

> +This is done by performing an
> +.B F_SETDELEG
> +operation specifying
> +.I d_type
> +in
> +.I deleg

	@@ -144,5 +157,3 @@ .SH DESCRIPTION
	 operation specifying
	-.I d_type
	-in
	-.I deleg
	+.I deleg->d_type
	 as

> +as
> +.BR F_RDLCK .
> +.P
> +If the delegation holder fails to downgrade or remove the delegation within
> +the number of seconds specified in
> +.IR /proc/sys/fs/lease\-break\-time ,
> +then the kernel forcibly removes or downgrades the delegation holder's delegation.
> +.P
> +Once a delegation break has been initiated,
> +.B F_GETDELEG
> +returns the target delegation type in the
> +.I d_type
> +field in
> +.I deleg

	@@ -150,6 +161,8 @@ .SH DESCRIPTION
	 .P
	-If the delegation holder fails to downgrade or remove the delegation within
	-the number of seconds specified in
	+If the delegation holder
	+fails to downgrade or remove the delegation
	+within the number of seconds specified in
	 .IR /proc/sys/fs/lease\-break\-time ,
	-then the kernel forcibly removes or downgrades the delegation holder's delegation.
	+then the kernel
	+forcibly removes or downgrades the delegation holder's delegation.
	 .P
	@@ -158,5 +171,3 @@ .SH DESCRIPTION
	 returns the target delegation type in the
	-.I d_type
	-field in
	-.I deleg
	+.I deleg->d_type
	 (either

> +(either
> +.B F_RDLCK
> +or
> +.BR F_UNLCK ,
> +depending on what would be compatible with the delegation breaker)
> +until the delegation holder voluntarily downgrades or removes the delegation or
> +the kernel forcibly does so after the delegation break timer expires.

	@@ -166,4 +177,4 @@ .SH DESCRIPTION
	 depending on what would be compatible with the delegation breaker)
	-until the delegation holder voluntarily downgrades or removes the delegation or
	-the kernel forcibly does so after the delegation break timer expires.
	+until the delegation holder voluntarily downgrades or removes the delegation
	+or the kernel forcibly does so after the delegation break timer expires.
	 .P


> +.P
> +Once the delegation has been voluntarily or forcibly removed or downgraded,
> +and assuming the delegation breaker has not unblocked its system call,
> +the kernel permits the delegation breaker's system call to proceed.
> +.P
> +If the delegation breaker's blocked system call
> +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 delegation 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 delegation 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 delegation holder is
> +.BR SIGIO ,
> +but this can be changed using the
> +.B F_SETSIG
> +operation to
> +.BR fcntl ().

Refer to the manual page:

	@@ -193,9 +204,8 @@ .SH DESCRIPTION
	 .BR SIGIO ,
	-but this can be changed using the
	-.B F_SETSIG
	-operation to
	-.BR fcntl ().
	+but this can be changed using
	+.BR F_SETSIG (2const).
	 If a
	-.B F_SETSIG
	-operation is performed (even one specifying
	+.BR F_SETSIG (2const)
	+operation is performed
	+(even one specifying
	 .BR SIGIO ),

> +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 file with the delegation
> +that has been accessed by another process.

Semantic newlines:

	@@ -206,5 +216,7 @@ .SH DESCRIPTION
	 .I siginfo_t
	-structure as its second argument, and the
	+structure as its second argument,
	+and the
	 .I si_fd
	-field of this argument will hold the file descriptor of the file with the delegation
	+field of this argument will hold
	+the file descriptor of the file with the delegation
	 that has been accessed by another process.

> +(This is useful if the caller holds delegations against multiple files.)
> +.SH NOTES
> +Delegations were designed to implement NFSv4 delegations for the Linux NFS server.

Do we have a link to the NFSv4 specification of delegations?  It would
be useful, I think.

> +.SH RETURN VALUE
> +On success zero is returned. On error, \-1 is returned, and

In source code, we *always* start a new line after period.

	@@ -214,5 +226,7 @@ .SH NOTES
	 .SH RETURN VALUE
	-On success zero is returned. On error, \-1 is returned, and
	+On success zero is returned.
	+On error, \-1 is returned, and
	 .I errno
	-is set to indicate the error. A successful
	+is set to indicate the error.
	+A successful
	 .B F_GETDELEG

> +.I errno
> +is set to indicate the error. A successful
> +.B F_GETDELEG
> +call will also update the
> +.I deleg->d_type
> +field.
> +.SH ERRORS
> +See
> +.BR fcntl (2).
> +These operations can also return the following errors:
> +.TP
> +.B EAGAIN
> +The operation was prohibited because the file was held open in a way that conflicts with the requested delegation.
> +.TP
> +.B EINVAL
> +The operation was prohibited because the caller tried to set a
> +.B F_WRLCK
> +delegation and
> +.I fd
> +represents a directory,
> +or
> +.I fd
> +doesn't represent a file or directory, or
> +the underlying filesystem doesn't support delegations.

I've split this into 3 separate EINVAL entries, and have removed
superfluous wording.

	@@ -225,18 +239,22 @@ .SH ERRORS
	 These operations can also return the following errors:
	 .TP
	 .B EAGAIN
	-The operation was prohibited because the file was held open in a way that conflicts with the requested delegation.
	+The file was held open in a way that
	+conflicts with the requested delegation.
	 .TP
	 .B EINVAL
	-The operation was prohibited because the caller tried to set a
	+The caller tried to set a
	 .B F_WRLCK
	 delegation and
	 .I fd
	-represents a directory,
	-or
	+represents a directory.
	+.TP
	+.B EINVAL
	 .I fd
	-doesn't represent a file or directory, or
	-the underlying filesystem doesn't support delegations.
	+doesn't represent a file or directory.
	+.TP
	+.B EINVAL
	+The underlying filesystem doesn't support delegations.
	 .SH STANDARDS
	 Linux, IETF RFC\ 8881.
	 .SH HISTORY

> +.SH STANDARDS
> +Linux, IETF RFC\ 8881.

	@@ -241 +259,2 @@ .SH STANDARDS
	-Linux, IETF RFC\ 8881.
	+Linux,
	+IETF\ RFC\ 8881.

> +.SH HISTORY
> +Linux 6.19.
> +.SH SEE ALSO
> +.BR fcntl (2) ,
> +.BR F_SETLEASE (2const)
> diff --git a/man/man2const/F_SETDELEG.2const b/man/man2const/F_SETDELEG.2const
> new file mode 100644
> index 0000000000000000000000000000000000000000..acabdfc139fb3d753dbf3061c31d59332d046c63
> --- /dev/null
> +++ b/man/man2const/F_SETDELEG.2const
> @@ -0,0 +1 @@
> +.so man2const/F_GETDELEG.2const
> 
> -- 
> 2.52.0
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH man-pages v2 2/2] man/man2const: clean up the F_GETLEASE manpage

[Jeff Layton]

- Remove a redundant subsection heading
- Add in the lease-specific error codes
- Clean up some semantic newline warts

Signed-off-by: Jeff Layton <jlayton@kernel.org>
---
 man/man2const/F_GETLEASE.2const | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/man/man2const/F_GETLEASE.2const b/man/man2const/F_GETLEASE.2const
index 10f7ac7a89a70b83be10a381462d879cff813471..e841f7f8c7c64ba8c6868e68d493716040e3dec2 100644
--- a/man/man2const/F_GETLEASE.2const
+++ b/man/man2const/F_GETLEASE.2const
@@ -20,7 +20,6 @@ Standard C library
 .BI "int fcntl(int " fd ", F_GETLEASE);"
 .fi
 .SH DESCRIPTION
-.SS Leases
 .B F_SETLEASE
 and
 .B F_GETLEASE
@@ -43,7 +42,7 @@ values is specified in the integer
 .RS
 .TP
 .B F_RDLCK
-Take out a read lease.
+Establish 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:
@@ -52,7 +51,7 @@ 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.
+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
@@ -86,8 +85,11 @@ capability may take out leases on arbitrary files.
 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.
+.BR F_RDLCK,
+.BR F_WRLCK,
+or
+.BR F_UNLCK,
+indicating, respectively, a read lease, a write lease, or no lease.
 .I arg
 is ignored.
 .P
@@ -196,6 +198,16 @@ is set to indicate the error.
 .SH ERRORS
 See
 .BR fcntl (2).
+These operations can also fail with the following error codes:
+.TP
+.B EAGAIN
+The operation is prohibited because the file is open in a way that conflicts with the requested lease.
+.TP
+.B EINVAL
+The operation is prohibited because the underlying filesystem doesn't support leases,
+or because
+.I fd
+does not represent a regular file.
 .SH STANDARDS
 Linux.
 .SH HISTORY

-- 
2.52.0

Re: [PATCH man-pages v2 2/2] man/man2const: clean up the F_GETLEASE manpage

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2622 bytes --]

Hi Jeff,

On Wed, Jan 14, 2026 at 12:35:25PM -0500, Jeff Layton wrote:
> - Remove a redundant subsection heading
> - Add in the lease-specific error codes
> - Clean up some semantic newline warts
> 
> Signed-off-by: Jeff Layton <jlayton@kernel.org>

Thanks!  I've applied it, and split it in two commits.


Have a lovely night!
Alex

> ---
>  man/man2const/F_GETLEASE.2const | 22 +++++++++++++++++-----
>  1 file changed, 17 insertions(+), 5 deletions(-)
> 
> diff --git a/man/man2const/F_GETLEASE.2const b/man/man2const/F_GETLEASE.2const
> index 10f7ac7a89a70b83be10a381462d879cff813471..e841f7f8c7c64ba8c6868e68d493716040e3dec2 100644
> --- a/man/man2const/F_GETLEASE.2const
> +++ b/man/man2const/F_GETLEASE.2const
> @@ -20,7 +20,6 @@ Standard C library
>  .BI "int fcntl(int " fd ", F_GETLEASE);"
>  .fi
>  .SH DESCRIPTION
> -.SS Leases
>  .B F_SETLEASE
>  and
>  .B F_GETLEASE
> @@ -43,7 +42,7 @@ values is specified in the integer
>  .RS
>  .TP
>  .B F_RDLCK
> -Take out a read lease.
> +Establish 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:
> @@ -52,7 +51,7 @@ 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.
> +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
> @@ -86,8 +85,11 @@ capability may take out leases on arbitrary files.
>  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.
> +.BR F_RDLCK,
> +.BR F_WRLCK,
> +or
> +.BR F_UNLCK,
> +indicating, respectively, a read lease, a write lease, or no lease.
>  .I arg
>  is ignored.
>  .P
> @@ -196,6 +198,16 @@ is set to indicate the error.
>  .SH ERRORS
>  See
>  .BR fcntl (2).
> +These operations can also fail with the following error codes:
> +.TP
> +.B EAGAIN
> +The operation is prohibited because the file is open in a way that conflicts with the requested lease.
> +.TP
> +.B EINVAL
> +The operation is prohibited because the underlying filesystem doesn't support leases,
> +or because
> +.I fd
> +does not represent a regular file.
>  .SH STANDARDS
>  Linux.
>  .SH HISTORY
> 
> -- 
> 2.52.0
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v3] man/man2const/F_[SG]ETDELEG.2const, man/man2/fcntl.2: Document F_SETDELEG and F_GETDELEG

[Alejandro Colomar]

From: Jeff Layton <jlayton@kernel.org>

With Linux 6.19, userland will be able to request a delegation on a file
or directory.  These new objects act a lot like file leases, but are
based on NFSv4 file and directory delegations.

Add new F_GETDELEG and F_SETDELEG manpages to document them.

Signed-off-by: Jeff Layton <jlayton@kernel.org>
[alx: minor tweaks]
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/fcntl.2                |   5 +
 man/man2const/F_GETDELEG.2const | 265 ++++++++++++++++++++++++++++++++
 man/man2const/F_SETDELEG.2const |   1 +
 3 files changed, 271 insertions(+)
 create mode 100644 man/man2const/F_GETDELEG.2const
 create mode 100644 man/man2const/F_SETDELEG.2const

diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2
index 7f34e332e..f05d559da 100644
--- a/man/man2/fcntl.2
+++ b/man/man2/fcntl.2
@@ -78,6 +78,11 @@ .SS Leases
 .BR F_SETLEASE (2const)
 .TQ
 .BR F_GETLEASE (2const)
+.SS Delegations
+.TP
+.BR F_SETDELEG (2const)
+.TQ
+.BR F_GETDELEG (2const)
 .SS File and directory change notification (dnotify)
 .TP
 .BR F_NOTIFY (2const)
diff --git a/man/man2const/F_GETDELEG.2const b/man/man2const/F_GETDELEG.2const
new file mode 100644
index 000000000..e4d98feed
--- /dev/null
+++ b/man/man2const/F_GETDELEG.2const
@@ -0,0 +1,265 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH F_GETDELEG 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+F_GETDELEG,
+F_SETDELEG
+\-
+delegations
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #define _GNU_SOURCE
+.B #include <fcntl.h>
+.P
+.BI "int fcntl(int " fd ", F_SETDELEG, const struct delegation *" deleg );
+.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
+.fi
+.P
+.EX
+struct delegation {
+	__u32  d_flags;
+	__u16  d_type;
+	__u16  __pad;
+};
+.EE
+.SH DESCRIPTION
+.B F_SETDELEG
+and
+.B F_GETDELEG
+are used to establish a new delegation,
+and retrieve the current delegation,
+on the open file description referred to by the file descriptor
+.IR fd .
+.P
+A file delegation is a mechanism whereby
+the process holding the delegation (the "delegation holder")
+is notified (via delivery of a signal)
+when a process (the "delegation breaker")
+tries to
+.BR open (2)
+or
+.BR truncate (2)
+the file referred to by that file descriptor,
+or tries to
+.BR unlink (2)
+or
+.BR rename (2)
+the dentry that was originally opened for the file.
+.P
+Delegations can also be set on directory file descriptors.
+The holder of a directory delegation will be notified if there is a
+create, delete, or rename of a dirent within the directory.
+.TP
+.B F_SETDELEG
+Set or remove a file or directory delegation according to the
+value specified in
+.IR deleg->d_type :
+.RS
+.TP
+.B F_RDLCK
+Establish a read delegation.
+This will cause the calling process to be notified
+when the file is
+opened for writing,
+or is truncated, unlinked or renamed.
+A read delegation can be placed
+only on a file descriptor that is opened read-only.
+.IP
+If
+.I fd
+refers to a directory,
+then the calling process will be notified
+if there are changes to filenames within the directory,
+or when the directory itself is renamed.
+.TP
+.B F_WRLCK
+Establish a write delegation.
+This will cause the caller to be notified when the file is opened for reading or writing,
+or is truncated, renamed or unlinked.
+A write delegation may be placed on a file only if there are no other open file descriptors for the file.
+The file must be opened for write in order to set a write delegation on it.
+Write delegations cannot be set on directory file descriptors.
+.TP
+.B F_UNLCK
+Remove our delegation from the file.
+.RE
+.P
+Like leases,
+delegations 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 delegation,
+and this delegation may be modified or released
+using any of these descriptors.
+Furthermore,
+the delegation 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
+An unprivileged process may establish a delegation
+only on a file whose UID (owner) matches the filesystem UID of the process.
+A process with the
+.B CAP_LEASE
+capability may establish delegations on arbitrary files and directories.
+.TP
+.B F_GETDELEG
+Indicates what type of delegation is associated with the file descriptor
+.I fd
+by setting
+.I deleg->d_type
+to either
+.BR F_RDLCK ,
+.BR F_WRLCK ,
+or
+.BR F_UNLCK ,
+indicating, respectively,
+a read delegation, a write delegation, or no delegation.
+.P
+When a process (the "delegation breaker")
+performs an activity that conflicts with a delegation
+established via
+.BR F_SETDELEG ,
+the system call is blocked by the kernel
+and the kernel notifies the delegation holder by sending it a signal
+.RB ( SIGIO
+by default).
+The delegation 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 delegation.
+A delegation is removed by performing an
+.B F_SETDELEG
+operation specifying
+.I deleg->d_type
+as
+.BR F_UNLCK .
+If the delegation holder currently holds
+a write delegation on the file,
+and the delegation breaker
+is opening the file for reading,
+then it is sufficient for the delegation holder to
+downgrade the delegation to a read delegation.
+This is done by performing an
+.B F_SETDELEG
+operation specifying
+.I deleg->d_type
+as
+.BR F_RDLCK .
+.P
+If the delegation holder
+fails to downgrade or remove the delegation
+within the number of seconds specified in
+.IR /proc/sys/fs/lease\-break\-time ,
+then the kernel
+forcibly removes or downgrades the delegation holder's delegation.
+.P
+Once a delegation break has been initiated,
+.B F_GETDELEG
+returns the target delegation type in the
+.I deleg->d_type
+(either
+.B F_RDLCK
+or
+.BR F_UNLCK ,
+depending on what would be compatible with the delegation breaker)
+until the delegation holder voluntarily downgrades or removes the delegation
+or the kernel forcibly does so after the delegation break timer expires.
+.P
+Once the delegation has been voluntarily or forcibly removed or downgraded,
+and assuming the delegation breaker has not unblocked its system call,
+the kernel permits the delegation breaker's system call to proceed.
+.P
+If the delegation breaker's blocked system call
+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 delegation 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 delegation 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 delegation holder is
+.BR SIGIO ,
+but this can be changed using
+.BR F_SETSIG (2const).
+If a
+.BR F_SETSIG (2const)
+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 file with the delegation
+that has been accessed by another process.
+(This is useful if the caller holds delegations against multiple files.)
+.SH NOTES
+Delegations were designed to implement NFSv4 delegations for the Linux NFS server.
+.SH RETURN VALUE
+On success zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+A successful
+.B F_GETDELEG
+call will also update the
+.I deleg->d_type
+field.
+.SH ERRORS
+See
+.BR fcntl (2).
+These operations can also return the following errors:
+.TP
+.B EAGAIN
+The file was held open in a way that
+conflicts with the requested delegation.
+.TP
+.B EINVAL
+The caller tried to set a
+.B F_WRLCK
+delegation and
+.I fd
+represents a directory.
+.TP
+.B EINVAL
+.I fd
+doesn't represent a file or directory.
+.TP
+.B EINVAL
+The underlying filesystem doesn't support delegations.
+.SH STANDARDS
+Linux,
+IETF\ RFC\ 8881.
+.SH HISTORY
+Linux 6.19.
+.SH SEE ALSO
+.BR fcntl (2) ,
+.BR F_SETLEASE (2const)
diff --git a/man/man2const/F_SETDELEG.2const b/man/man2const/F_SETDELEG.2const
new file mode 100644
index 000000000..acabdfc13
--- /dev/null
+++ b/man/man2const/F_SETDELEG.2const
@@ -0,0 +1 @@
+.so man2const/F_GETDELEG.2const

base-commit: f17241696722c472c5fcd06ee3b7af7afc3f1082
-- 
2.51.0

Re: [PATCH v3] man/man2const/F_[SG]ETDELEG.2const, man/man2/fcntl.2: Document F_SETDELEG and F_GETDELEG

[Jeff Layton]

On Sun, 2026-01-18 at 16:42 +0100, Alejandro Colomar wrote:
> From: Jeff Layton <jlayton@kernel.org>
> 
> With Linux 6.19, userland will be able to request a delegation on a file
> or directory.  These new objects act a lot like file leases, but are
> based on NFSv4 file and directory delegations.
> 
> Add new F_GETDELEG and F_SETDELEG manpages to document them.
> 
> Signed-off-by: Jeff Layton <jlayton@kernel.org>
> [alx: minor tweaks]
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>  man/man2/fcntl.2                |   5 +
>  man/man2const/F_GETDELEG.2const | 265 ++++++++++++++++++++++++++++++++
>  man/man2const/F_SETDELEG.2const |   1 +
>  3 files changed, 271 insertions(+)
>  create mode 100644 man/man2const/F_GETDELEG.2const
>  create mode 100644 man/man2const/F_SETDELEG.2const
> 
> diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2
> index 7f34e332e..f05d559da 100644
> --- a/man/man2/fcntl.2
> +++ b/man/man2/fcntl.2
> @@ -78,6 +78,11 @@ .SS Leases
>  .BR F_SETLEASE (2const)
>  .TQ
>  .BR F_GETLEASE (2const)
> +.SS Delegations
> +.TP
> +.BR F_SETDELEG (2const)
> +.TQ
> +.BR F_GETDELEG (2const)
>  .SS File and directory change notification (dnotify)
>  .TP
>  .BR F_NOTIFY (2const)
> diff --git a/man/man2const/F_GETDELEG.2const b/man/man2const/F_GETDELEG.2const
> new file mode 100644
> index 000000000..e4d98feed
> --- /dev/null
> +++ b/man/man2const/F_GETDELEG.2const
> @@ -0,0 +1,265 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH F_GETDELEG 2const (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +F_GETDELEG,
> +F_SETDELEG
> +\-
> +delegations
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.B #define _GNU_SOURCE
> +.B #include <fcntl.h>
> +.P
> +.BI "int fcntl(int " fd ", F_SETDELEG, const struct delegation *" deleg );
> +.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
> +.fi
> +.P
> +.EX
> +struct delegation {
> +	__u32  d_flags;
> +	__u16  d_type;
> +	__u16  __pad;
> +};
> +.EE
> +.SH DESCRIPTION
> +.B F_SETDELEG
> +and
> +.B F_GETDELEG
> +are used to establish a new delegation,
> +and retrieve the current delegation,
> +on the open file description referred to by the file descriptor
> +.IR fd .
> +.P
> +A file delegation is a mechanism whereby
> +the process holding the delegation (the "delegation holder")
> +is notified (via delivery of a signal)
> +when a process (the "delegation breaker")
> +tries to
> +.BR open (2)
> +or
> +.BR truncate (2)
> +the file referred to by that file descriptor,
> +or tries to
> +.BR unlink (2)
> +or
> +.BR rename (2)
> +the dentry that was originally opened for the file.
> +.P
> +Delegations can also be set on directory file descriptors.
> +The holder of a directory delegation will be notified if there is a
> +create, delete, or rename of a dirent within the directory.
> +.TP
> +.B F_SETDELEG
> +Set or remove a file or directory delegation according to the
> +value specified in
> +.IR deleg->d_type :
> +.RS
> +.TP
> +.B F_RDLCK
> +Establish a read delegation.
> +This will cause the calling process to be notified
> +when the file is
> +opened for writing,
> +or is truncated, unlinked or renamed.
> +A read delegation can be placed
> +only on a file descriptor that is opened read-only.
> +.IP
> +If
> +.I fd
> +refers to a directory,
> +then the calling process will be notified
> +if there are changes to filenames within the directory,
> +or when the directory itself is renamed.
> +.TP
> +.B F_WRLCK
> +Establish a write delegation.
> +This will cause the caller to be notified when the file is opened for reading or writing,
> +or is truncated, renamed or unlinked.
> +A write delegation may be placed on a file only if there are no other open file descriptors for the file.
> +The file must be opened for write in order to set a write delegation on it.
> +Write delegations cannot be set on directory file descriptors.
> +.TP
> +.B F_UNLCK
> +Remove our delegation from the file.
> +.RE
> +.P
> +Like leases,
> +delegations 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 delegation,
> +and this delegation may be modified or released
> +using any of these descriptors.
> +Furthermore,
> +the delegation 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
> +An unprivileged process may establish a delegation
> +only on a file whose UID (owner) matches the filesystem UID of the process.
> +A process with the
> +.B CAP_LEASE
> +capability may establish delegations on arbitrary files and directories.
> +.TP
> +.B F_GETDELEG
> +Indicates what type of delegation is associated with the file descriptor
> +.I fd
> +by setting
> +.I deleg->d_type
> +to either
> +.BR F_RDLCK ,
> +.BR F_WRLCK ,
> +or
> +.BR F_UNLCK ,
> +indicating, respectively,
> +a read delegation, a write delegation, or no delegation.
> +.P
> +When a process (the "delegation breaker")
> +performs an activity that conflicts with a delegation
> +established via
> +.BR F_SETDELEG ,
> +the system call is blocked by the kernel
> +and the kernel notifies the delegation holder by sending it a signal
> +.RB ( SIGIO
> +by default).
> +The delegation 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 delegation.
> +A delegation is removed by performing an
> +.B F_SETDELEG
> +operation specifying
> +.I deleg->d_type
> +as
> +.BR F_UNLCK .
> +If the delegation holder currently holds
> +a write delegation on the file,
> +and the delegation breaker
> +is opening the file for reading,
> +then it is sufficient for the delegation holder to
> +downgrade the delegation to a read delegation.
> +This is done by performing an
> +.B F_SETDELEG
> +operation specifying
> +.I deleg->d_type
> +as
> +.BR F_RDLCK .
> +.P
> +If the delegation holder
> +fails to downgrade or remove the delegation
> +within the number of seconds specified in
> +.IR /proc/sys/fs/lease\-break\-time ,
> +then the kernel
> +forcibly removes or downgrades the delegation holder's delegation.
> +.P
> +Once a delegation break has been initiated,
> +.B F_GETDELEG
> +returns the target delegation type in the
> +.I deleg->d_type
> +(either
> +.B F_RDLCK
> +or
> +.BR F_UNLCK ,
> +depending on what would be compatible with the delegation breaker)
> +until the delegation holder voluntarily downgrades or removes the delegation
> +or the kernel forcibly does so after the delegation break timer expires.
> +.P
> +Once the delegation has been voluntarily or forcibly removed or downgraded,
> +and assuming the delegation breaker has not unblocked its system call,
> +the kernel permits the delegation breaker's system call to proceed.
> +.P
> +If the delegation breaker's blocked system call
> +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 delegation 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 delegation 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 delegation holder is
> +.BR SIGIO ,
> +but this can be changed using
> +.BR F_SETSIG (2const).
> +If a
> +.BR F_SETSIG (2const)
> +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 file with the delegation
> +that has been accessed by another process.
> +(This is useful if the caller holds delegations against multiple files.)
> +.SH NOTES
> +Delegations were designed to implement NFSv4 delegations for the Linux NFS server.
> +.SH RETURN VALUE
> +On success zero is returned.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +A successful
> +.B F_GETDELEG
> +call will also update the
> +.I deleg->d_type
> +field.
> +.SH ERRORS
> +See
> +.BR fcntl (2).
> +These operations can also return the following errors:
> +.TP
> +.B EAGAIN
> +The file was held open in a way that
> +conflicts with the requested delegation.
> +.TP
> +.B EINVAL
> +The caller tried to set a
> +.B F_WRLCK
> +delegation and
> +.I fd
> +represents a directory.
> +.TP
> +.B EINVAL
> +.I fd
> +doesn't represent a file or directory.
> +.TP
> +.B EINVAL
> +The underlying filesystem doesn't support delegations.
> +.SH STANDARDS
> +Linux,
> +IETF\ RFC\ 8881.
> +.SH HISTORY
> +Linux 6.19.
> +.SH SEE ALSO
> +.BR fcntl (2) ,
> +.BR F_SETLEASE (2const)
> diff --git a/man/man2const/F_SETDELEG.2const b/man/man2const/F_SETDELEG.2const
> new file mode 100644
> index 000000000..acabdfc13
> --- /dev/null
> +++ b/man/man2const/F_SETDELEG.2const
> @@ -0,0 +1 @@
> +.so man2const/F_GETDELEG.2const
> 
> base-commit: f17241696722c472c5fcd06ee3b7af7afc3f1082


This all looks great to me. Did you need me to make any other changes?
Thanks for doing the cleanup! FWIW:

Reviewed-by: Jeff Layton <jlayton@kernel.org>

Re: [PATCH v3] man/man2const/F_[SG]ETDELEG.2const, man/man2/fcntl.2: Document F_SETDELEG and F_GETDELEG

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1750 bytes --]

Hi Jeff,

On Tue, Jan 20, 2026 at 09:39:27AM -0500, Jeff Layton wrote:
> On Sun, 2026-01-18 at 16:42 +0100, Alejandro Colomar wrote:
> > From: Jeff Layton <jlayton@kernel.org>
> > 
> > With Linux 6.19, userland will be able to request a delegation on a file
> > or directory.  These new objects act a lot like file leases, but are
> > based on NFSv4 file and directory delegations.
> > 
> > Add new F_GETDELEG and F_SETDELEG manpages to document them.
> > 
> > Signed-off-by: Jeff Layton <jlayton@kernel.org>
> > [alx: minor tweaks]
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > ---
> >  man/man2/fcntl.2                |   5 +
> >  man/man2const/F_GETDELEG.2const | 265 ++++++++++++++++++++++++++++++++
> >  man/man2const/F_SETDELEG.2const |   1 +
> >  3 files changed, 271 insertions(+)
> >  create mode 100644 man/man2const/F_GETDELEG.2const
> >  create mode 100644 man/man2const/F_SETDELEG.2const
> > 

[...]

> > diff --git a/man/man2const/F_GETDELEG.2const b/man/man2const/F_GETDELEG.2const
> > new file mode 100644
> > index 000000000..e4d98feed
> > --- /dev/null
> > +++ b/man/man2const/F_GETDELEG.2const
> > @@ -0,0 +1,265 @@

[...]

> > +.SH NOTES
> > +Delegations were designed to implement NFSv4 delegations for the Linux NFS server.

Do we have a link to the NFSv4 specification of delegations?  It could
be useful, I think.  What do you think?

[...]

> This all looks great to me. Did you need me to make any other changes?

The only remaining doubt is the question above.

> Thanks for doing the cleanup! FWIW:
> 
> Reviewed-by: Jeff Layton <jlayton@kernel.org>

You're welcome!  And thanks!  :-)


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] man/man2const/F_[SG]ETDELEG.2const, man/man2/fcntl.2: Document F_SETDELEG and F_GETDELEG

[Jeff Layton]

On Tue, 2026-01-20 at 16:12 +0100, Alejandro Colomar wrote:
> Hi Jeff,
> 
> On Tue, Jan 20, 2026 at 09:39:27AM -0500, Jeff Layton wrote:
> > On Sun, 2026-01-18 at 16:42 +0100, Alejandro Colomar wrote:
> > > From: Jeff Layton <jlayton@kernel.org>
> > > 
> > > With Linux 6.19, userland will be able to request a delegation on a file
> > > or directory.  These new objects act a lot like file leases, but are
> > > based on NFSv4 file and directory delegations.
> > > 
> > > Add new F_GETDELEG and F_SETDELEG manpages to document them.
> > > 
> > > Signed-off-by: Jeff Layton <jlayton@kernel.org>
> > > [alx: minor tweaks]
> > > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > > ---
> > >  man/man2/fcntl.2                |   5 +
> > >  man/man2const/F_GETDELEG.2const | 265 ++++++++++++++++++++++++++++++++
> > >  man/man2const/F_SETDELEG.2const |   1 +
> > >  3 files changed, 271 insertions(+)
> > >  create mode 100644 man/man2const/F_GETDELEG.2const
> > >  create mode 100644 man/man2const/F_SETDELEG.2const
> > > 
> 
> [...]
> 
> > > diff --git a/man/man2const/F_GETDELEG.2const b/man/man2const/F_GETDELEG.2const
> > > new file mode 100644
> > > index 000000000..e4d98feed
> > > --- /dev/null
> > > +++ b/man/man2const/F_GETDELEG.2const
> > > @@ -0,0 +1,265 @@
> 
> [...]
> 
> > > +.SH NOTES
> > > +Delegations were designed to implement NFSv4 delegations for the Linux NFS server.
> 
> Do we have a link to the NFSv4 specification of delegations?  It could
> be useful, I think.  What do you think?
> 
> [...]
> 

RFC8881 is the NFSv4.1 spec, and that's what defines them. The
description is spread out all over the document however. Section 10.2
probably has the best basic description. It's not exactly succinct
though.


> > This all looks great to me. Did you need me to make any other changes?
> 
> The only remaining doubt is the question above.
> 
> > Thanks for doing the cleanup! FWIW:
> > 
> > Reviewed-by: Jeff Layton <jlayton@kernel.org>
> 
> You're welcome!  And thanks!  :-)
> 
> 
> Have a lovely day!
> Alex

-- 
Jeff Layton <jlayton@kernel.org>

Re: [PATCH v3] man/man2const/F_[SG]ETDELEG.2const, man/man2/fcntl.2: Document F_SETDELEG and F_GETDELEG

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 851 bytes --]

Hi Jeff,

On Tue, Jan 20, 2026 at 10:30:00AM -0500, Jeff Layton wrote:
> > > > +.SH NOTES
> > > > +Delegations were designed to implement NFSv4 delegations for the Linux NFS server.
> > 
> > Do we have a link to the NFSv4 specification of delegations?  It could
> > be useful, I think.  What do you think?
> > 
> > [...]
> > 
> 
> RFC8881 is the NFSv4.1 spec, and that's what defines them. The
> description is spread out all over the document however. Section 10.2
> probably has the best basic description. It's not exactly succinct
> though.

Ahh, ok.  Then I guess I'll say

	... to implement NFSv4 (RFC 8881) delegations ...

That should be enough for the reader to know where to find the spec if
needed.


I'll tweak that and push this evening.  Thank you!


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] man/man2const/F_[SG]ETDELEG.2const, man/man2/fcntl.2: Document F_SETDELEG and F_GETDELEG

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 257 bytes --]

Hi Jeff,

On Tue, Jan 20, 2026 at 04:58:09PM +0100, Alejandro Colomar wrote:
> I'll tweak that and push this evening.  Thank you!

I've pushed now; sorry for the delay.  Thanks!


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]