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

[PATCH man-pages] 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 | 230 ++++++++++++++++++++++++++++++++++++++++
 man/man2const/F_SETDELEG.2const |   1 +
 3 files changed, 236 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..60c7e62f8dbcb6f97fda82e1c50f34ecacce2aab
--- /dev/null
+++ b/man/man2const/F_GETDELEG.2const
@@ -0,0 +1,230 @@
+.\" 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
+.EX
+/* Argument structure for F_GETDELEG and F_SETDELEG */
+struct delegation {
+        __u32   d_flags;
+        __u16   d_type;
+        __u16   __pad;
+};
+.EE
+.P
+.BI "int fcntl(int " fd ", F_SETDELEG, struct delegation *" deleg );
+.br
+.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
+.fi
+.SH DESCRIPTION
+.SS Delegations
+.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 .
+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.
+.BR F_RDLCK
+delegations can also be set on directory file descriptors, in which case they will
+be recalled 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 which of the following
+values is specified in the
+.IR d_type
+field of
+.IR deleg :
+.RS
+.TP
+.B F_RDLCK
+Take out a read delegation.
+This will cause the calling process to be notified when
+the file is opened for writing or is truncated, or when the file is 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
+Take out a write delegation.
+This will cause the caller to be notified when
+the file is opened for reading or writing or is truncated or when the file is 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 ", " F_WRLCK ", or " 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, and
+conform to the delegation semantics described in RFC\ 8881.
+.SH RETURN VALUE
+On success zero is returned. On error, \-1 is returned, and
+.I errno
+is set to indicate the error. A successful F_GETDELEG call will also update the
+.I d_type
+field in the structure to which
+.I deleg
+points.
+.SH ERRORS
+See
+.BR fcntl (2).
+.SH STANDARDS
+Linux, IETF RFC\ 8881.
+.SH HISTORY
+Linux v6.19.
+.SH SEE ALSO
+.BR fcntl (2)
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

---
base-commit: 753ac20a01007417aa993e70d290f51840e2f477
change-id: 20260112-master-23a1ede99836

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

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

[Alejandro Colomar]

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

Hi Jeff,

On Mon, Jan 12, 2026 at 01:47:11PM -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>
> ---
>  man/man2/fcntl.2                |   5 +
>  man/man2const/F_GETDELEG.2const | 230 ++++++++++++++++++++++++++++++++++++++++
>  man/man2const/F_SETDELEG.2const |   1 +
>  3 files changed, 236 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..60c7e62f8dbcb6f97fda82e1c50f34ecacce2aab
> --- /dev/null
> +++ b/man/man2const/F_GETDELEG.2const
> @@ -0,0 +1,230 @@
> +.\" 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
> +.EX
> +/* Argument structure for F_GETDELEG and F_SETDELEG */

I'd say this comment seems redundant, given this structure is defined
in this manual page.

> +struct delegation {
> +        __u32   d_flags;
> +        __u16   d_type;
> +        __u16   __pad;
> +};
> +.EE
> +.P
> +.BI "int fcntl(int " fd ", F_SETDELEG, struct delegation *" deleg );

Is this really not const-qualified?  Does the kernel modify it?

> +.br

This .br seems superfluous.

> +.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
> +.fi
> +.SH DESCRIPTION
> +.SS Delegations

If the entire section is within a subsection, I think the subsection is
redundant, isn't it?

> +.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

Just to confirm: one can't retrieve delegations through a different file
description that refers to the same inode, right?

> +.IR fd .

I'd separate the paragraph here.  The above serves as a brief
introduction of these two APIs, while the following text describes what
delegations are.

> +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.
> +.BR F_RDLCK
> +delegations can also be set on directory file descriptors, in which case they will
> +be recalled if there is a create, delete or rename of a dirent within the directory.

Please use semantic newlines.  See man-pages(7):

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
     In the source of a manual page, new sentences should be started on
     new lines, long sentences should be split  into  lines  at  clause
     breaks  (commas,  semicolons, colons, and so on), and long clauses
     should be split at phrase boundaries.  This convention,  sometimes
     known as "semantic newlines", makes it easier to see the effect of
     patches, which often operate at the level of individual sentences,
     clauses, or phrases.

> +.TP
> +.B F_SETDELEG
> +Set or remove a file or directory delegation according to which of the following
> +values is specified in the
> +.IR d_type

s/IR/I/

IR is for alternating Italics and Roman.

Also, it would be good to use '.d_type' notation, for making it easier
to distinguish struct members.  A few manual pages already do this.
Thus:

	.I .d_type

> +field of
> +.IR deleg :

Maybe we could even simplify this as:

	...
	specified in
	.IR deleg->d_type :

> +.RS
> +.TP
> +.B F_RDLCK
> +Take out a read delegation.

'Take out' means to remove, but by reading the context, I think this
instead creates a read delegation, right?  Would it be correct to say
this?:

	Create a read delegation.

(I'm not a native English speaker, so I may be mistaken.)

> +This will cause the calling process to be notified when
> +the file is opened for writing or is truncated, or when the file is 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

Are we in time to rename this?

F_RDLCK blocks essentially writing.
F_WRLCK blocks both reading and writing.

What do you think of this rename:

	RD => WR
	WR => RW

> +Take out a write delegation.
> +This will cause the caller to be notified when
> +the file is opened for reading or writing or is truncated or when the file is 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 ", " F_WRLCK ", or " F_UNLCK ,

Please use a separate line for each:

	.BR F_RDLCK ,
	.BR F_WRLCK ,
	or
	.BR F_UNLCK ,

> +indicating, respectively, a read delegation , a write delegation, or no delegation.

Spurious white space before comma.

> +.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, and
> +conform to the delegation semantics described in RFC\ 8881.

I'd say the part after the comma is redundant with the STANDARDS
section.

> +.SH RETURN VALUE
> +On success zero is returned. On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error. A successful F_GETDELEG call will also update the

F_GETDELEG should be in bold.

> +.I d_type
> +field in the structure to which
> +.I deleg
> +points.
> +.SH ERRORS
> +See
> +.BR fcntl (2).

I guess there are also errors specific to delegations, right?  I expect
for example an error if F_SETDELEG is called with F_WRLCK but more file
descriptors are open for the same file.

> +.SH STANDARDS
> +Linux, IETF RFC\ 8881.
> +.SH HISTORY
> +Linux v6.19.

Please remove the 'v'.

> +.SH SEE ALSO
> +.BR fcntl (2)
> 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

Thanks!


Have a lovely day!
Alex

> ---
> base-commit: 753ac20a01007417aa993e70d290f51840e2f477
> change-id: 20260112-master-23a1ede99836
> 
> Best regards,
> -- 
> Jeff Layton <jlayton@kernel.org>
> 
> 

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

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

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

[Jeff Layton]

On Tue, 2026-01-13 at 15:13 +0100, Alejandro Colomar wrote:
> Hi Jeff,
> 
> On Mon, Jan 12, 2026 at 01:47:11PM -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>
> > ---
> >  man/man2/fcntl.2                |   5 +
> >  man/man2const/F_GETDELEG.2const | 230 ++++++++++++++++++++++++++++++++++++++++
> >  man/man2const/F_SETDELEG.2const |   1 +
> >  3 files changed, 236 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..60c7e62f8dbcb6f97fda82e1c50f34ecacce2aab
> > --- /dev/null
> > +++ b/man/man2const/F_GETDELEG.2const
> > @@ -0,0 +1,230 @@
> > +.\" 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
> > +.EX
> > +/* Argument structure for F_GETDELEG and F_SETDELEG */
> 
> I'd say this comment seems redundant, given this structure is defined
> in this manual page.
> 

Ack. Will remove.

> > +struct delegation {
> > +        __u32   d_flags;
> > +        __u16   d_type;
> > +        __u16   __pad;
> > +};
> > +.EE
> > +.P
> > +.BI "int fcntl(int " fd ", F_SETDELEG, struct delegation *" deleg );
> 
> Is this really not const-qualified?  Does the kernel modify it?
> 

Yes, it does modify it. F_GETDELEG populates d_type. I have some plans
to expand this interface in the future so F_GETDELEG may eventually
return other fields in there too.

> > +.br
> 
> This .br seems superfluous.
> 

You would think, no? But when I remove it, man seems to stick both
lines togther. I really do not grok groff at all.

I'm happy to accept other suggestions on how to fix that though.

> > +.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
> > +.fi
> > +.SH DESCRIPTION
> > +.SS Delegations
> 
> If the entire section is within a subsection, I think the subsection is
> redundant, isn't it?
> 

Oh ok, I cargo-cult copied most of this from F_GETLEASE.man2const, so
this may be there as well.


> > +.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
> 
> Just to confirm: one can't retrieve delegations through a different file
> description that refers to the same inode, right?
> 

Correct. F_GETDELEG just fills out ->d_type with the type of delegation
set on "fd".
  
> > +.IR fd .
> 
> I'd separate the paragraph here.  The above serves as a brief
> introduction of these two APIs, while the following text describes what
> delegations are.
> 

Ok.

> > +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.
> > +.BR F_RDLCK
> > +delegations can also be set on directory file descriptors, in which case they will
> > +be recalled if there is a create, delete or rename of a dirent within the directory.
> 
> Please use semantic newlines.  See man-pages(7):
> 
> $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
>    Use semantic newlines
>      In the source of a manual page, new sentences should be started on
>      new lines, long sentences should be split  into  lines  at  clause
>      breaks  (commas,  semicolons, colons, and so on), and long clauses
>      should be split at phrase boundaries.  This convention,  sometimes
>      known as "semantic newlines", makes it easier to see the effect of
>      patches, which often operate at the level of individual sentences,
>      clauses, or phrases.
> 

Ok, I'll reformat that.

> > +.TP
> > +.B F_SETDELEG
> > +Set or remove a file or directory delegation according to which of the following
> > +values is specified in the
> > +.IR d_type
> 
> s/IR/I/
> 
> IR is for alternating Italics and Roman.
> 
> Also, it would be good to use '.d_type' notation, for making it easier
> to distinguish struct members.  A few manual pages already do this.
> Thus:
> 
> 	.I .d_type
> 
> > +field of
> > +.IR deleg :
> 
> Maybe we could even simplify this as:
> 
> 	...
> 	specified in
> 	.IR deleg->d_type :
> 

Ok

> > +.RS
> > +.TP
> > +.B F_RDLCK
> > +Take out a read delegation.
> 
> 'Take out' means to remove, but by reading the context, I think this
> instead creates a read delegation, right?  Would it be correct to say
> this?:
> 
> 	Create a read delegation.
> 
> (I'm not a native English speaker, so I may be mistaken.)
> 

Delegations are returnable, so "take out" in the sense of a library
book or some other returnable object. I'll rephrase that, since it's
unclear.

> > +This will cause the calling process to be notified when
> > +the file is opened for writing or is truncated, or when the file is 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
> 
> Are we in time to rename this?
> 
> F_RDLCK blocks essentially writing.
> F_WRLCK blocks both reading and writing.
> 
> What do you think of this rename:
> 
> 	RD => WR
> 	WR => RW
> 

These are constants from file locking. I suppose we could add new
constants that overload those values?

> > +Take out a write delegation.
> > +This will cause the caller to be notified when
> > +the file is opened for reading or writing or is truncated or when the file is 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 ", " F_WRLCK ", or " F_UNLCK ,
> 
> Please use a separate line for each:
> 
> 	.BR F_RDLCK ,
> 	.BR F_WRLCK ,
> 	or
> 	.BR F_UNLCK ,
> 
> > +indicating, respectively, a read delegation , a write delegation, or no delegation.
>

ACK

> Spurious white space before comma.
> 

ACK

> > +.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, and
> > +conform to the delegation semantics described in RFC\ 8881.
> 
> I'd say the part after the comma is redundant with the STANDARDS
> section.
> 

Ok.

> > +.SH RETURN VALUE
> > +On success zero is returned. On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error. A successful F_GETDELEG call will also update the
> 
> F_GETDELEG should be in bold.
> 

Ok.

> > +.I d_type
> > +field in the structure to which
> > +.I deleg
> > +points.
> > +.SH ERRORS
> > +See
> > +.BR fcntl (2).
> 
> I guess there are also errors specific to delegations, right?  I expect
> for example an error if F_SETDELEG is called with F_WRLCK but more file
> descriptors are open for the same file.
> 

Only if the file descriptor was opened non-blocking. The errors are
basically the same as the ones for leases. I can transplant the
relevant error messages here though.

> > +.SH STANDARDS
> > +Linux, IETF RFC\ 8881.
> > +.SH HISTORY
> > +Linux v6.19.
> 
> Please remove the 'v'.
> 

ACK.

> > +.SH SEE ALSO
> > +.BR fcntl (2)
> > 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
> 
> Thanks!
> 
> 
> Have a lovely day!
> Alex

Thank you for the review! I'll update and send a v2.

Cheers,
-- 
Jeff Layton <jlayton@kernel.org>

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

[G. Branden Robinson]

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

Hi Jeff and Alex,

At 2026-01-13T09:45:11-0500, Jeff Layton wrote:
> On Tue, 2026-01-13 at 15:13 +0100, Alejandro Colomar wrote:
> > On Mon, Jan 12, 2026 at 01:47:11PM -0500, Jeff Layton wrote:
[...]
> > > +.br
> > 
> > This .br seems superfluous.
> > 
> 
> You would think, no? But when I remove it, man seems to stick both
> lines togther. I really do not grok groff at all.

Try the introduction in groff_man_style(7).

https://man7.org/linux/man-pages/man7/groff_man_style.7.html

> I'm happy to accept other suggestions on how to fix that though.

Here's the hunk with context:

+.EE
+.P
+.BI "int fcntl(int " fd ", F_SETDELEG, struct delegation *" deleg );
+.br
+.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
+.fi

The `br` request really is necessary there, as Jeff says.  This is an
ordinary paragraph.  The `EE` (end example) restores filling.  So you
_do_ need the `br` request here _but_ you can discard the `fi` request
to enable filling afterward, because it's already on.

An alternative will become available in groff 1.24.0; you'll be able to
use groff man's syopsis macros to set C function protoypes.

https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/NEWS?id=cfcfe1dde5b1752484dcd94dde1d65c65a5540fb#n409

Regards,
Branden

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

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

[Alejandro Colomar]

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

Hi Jeff,

On Tue, Jan 13, 2026 at 09:45:11AM -0500, Jeff Layton wrote:
[...]
> > > +.SH SYNOPSIS
> > > +.nf
> > > +.B #define _GNU_SOURCE
> > > +.B #include <fcntl.h>
> > > +.P
> > > +.EX
> > > +/* Argument structure for F_GETDELEG and F_SETDELEG */
> > 
> > I'd say this comment seems redundant, given this structure is defined
> > in this manual page.
> > 
> 
> Ack. Will remove.
> 
> > > +struct delegation {
> > > +        __u32   d_flags;
> > > +        __u16   d_type;
> > > +        __u16   __pad;
> > > +};
> > > +.EE
> > > +.P
> > > +.BI "int fcntl(int " fd ", F_SETDELEG, struct delegation *" deleg );
> > 
> > Is this really not const-qualified?  Does the kernel modify it?
> > 
> 
> Yes, it does modify it. F_GETDELEG populates d_type. I have some plans
> to expand this interface in the future so F_GETDELEG may eventually
> return other fields in there too.

But I mean F_SETDELEG (with an S).  I expect the setter wouldn't modify,
right?

> 
> > > +.br
> > 
> > This .br seems superfluous.
> > 
> 
> You would think, no? But when I remove it, man seems to stick both
> lines togther. I really do not grok groff at all.
> 
> I'm happy to accept other suggestions on how to fix that though.

Ahhh, sorry!  I see why.  So, we have EX/EE nested within nf/fi.  These
don't nest correctly, so one should close nf/fi, then do EX/EE, and then
open a new nf/fi pair.

> > > +.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
> > > +.fi
> > > +.SH DESCRIPTION
> > > +.SS Delegations
> > 
> > If the entire section is within a subsection, I think the subsection is
> > redundant, isn't it?
> > 
> 
> Oh ok, I cargo-cult copied most of this from F_GETLEASE.man2const, so
> this may be there as well.

I was supposing you had done that, but didn't figure out from which.  :)
Now it makes sense.  Yes, I should remove that from
F_GETLEASE.man2const.  It is a left-over from when I split the page
from fcntl(2).

> > > +.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
> > 
> > Just to confirm: one can't retrieve delegations through a different file
> > description that refers to the same inode, right?
> > 
> 
> Correct. F_GETDELEG just fills out ->d_type with the type of delegation
> set on "fd".

Thanks!

> > > +.IR fd .
> > 
> > I'd separate the paragraph here.  The above serves as a brief
> > introduction of these two APIs, while the following text describes what
> > delegations are.
> > 
> 
> Ok.
> 
> > > +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.
> > > +.BR F_RDLCK
> > > +delegations can also be set on directory file descriptors, in which case they will
> > > +be recalled if there is a create, delete or rename of a dirent within the directory.
> > 
> > Please use semantic newlines.  See man-pages(7):
> > 
> > $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
> >    Use semantic newlines
> >      In the source of a manual page, new sentences should be started on
> >      new lines, long sentences should be split  into  lines  at  clause
> >      breaks  (commas,  semicolons, colons, and so on), and long clauses
> >      should be split at phrase boundaries.  This convention,  sometimes
> >      known as "semantic newlines", makes it easier to see the effect of
> >      patches, which often operate at the level of individual sentences,
> >      clauses, or phrases.
> > 
> 
> Ok, I'll reformat that.

This applies also to the rest of the page, BTW.

> > > +.TP
> > > +.B F_SETDELEG
> > > +Set or remove a file or directory delegation according to which of the following
> > > +values is specified in the
> > > +.IR d_type
> > 
> > s/IR/I/
> > 
> > IR is for alternating Italics and Roman.
> > 
> > Also, it would be good to use '.d_type' notation, for making it easier
> > to distinguish struct members.  A few manual pages already do this.
> > Thus:
> > 
> > 	.I .d_type
> > 
> > > +field of
> > > +.IR deleg :
> > 
> > Maybe we could even simplify this as:
> > 
> > 	...
> > 	specified in
> > 	.IR deleg->d_type :
> > 
> 
> Ok
> 
> > > +.RS
> > > +.TP
> > > +.B F_RDLCK
> > > +Take out a read delegation.
> > 
> > 'Take out' means to remove, but by reading the context, I think this
> > instead creates a read delegation, right?  Would it be correct to say
> > this?:
> > 
> > 	Create a read delegation.
> > 
> > (I'm not a native English speaker, so I may be mistaken.)
> > 
> 
> Delegations are returnable, so "take out" in the sense of a library
> book or some other returnable object. I'll rephrase that, since it's
> unclear.
> 
> > > +This will cause the calling process to be notified when
> > > +the file is opened for writing or is truncated, or when the file is 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
> > 
> > Are we in time to rename this?
> > 
> > F_RDLCK blocks essentially writing.
> > F_WRLCK blocks both reading and writing.
> > 
> > What do you think of this rename:
> > 
> > 	RD => WR
> > 	WR => RW
> > 
> 
> These are constants from file locking. I suppose we could add new
> constants that overload those values?

Ahhh, so this is already a historical thing.  Indeed:

	$ grep -rn F_RDLCK man/
	man/man2const/F_GETLEASE.2const:45:.B F_RDLCK
	man/man2const/F_GETLEASE.2const:89:.BR F_RDLCK ", " F_WRLCK ", or " F_UNLCK ,
	man/man2const/F_GETLEASE.2const:123:.BR F_RDLCK .
	man/man2const/F_GETLEASE.2const:133:.B F_RDLCK
	man/man2/fcntl_locking.2:52:    short l_type;    /* Type of lock: F_RDLCK,
	man/man2/fcntl_locking.2:123:.RB ( F_RDLCK )
	man/man2/fcntl_locking.2:143:.B F_RDLCK
	man/man2/fcntl_locking.2:360:.B F_RDLCK

I guess that answers my question: no, we can't rename these.
Let's keep the historical names.

> > > +Take out a write delegation.
> > > +This will cause the caller to be notified when
> > > +the file is opened for reading or writing or is truncated or when the file is 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 ", " F_WRLCK ", or " F_UNLCK ,
> > 
> > Please use a separate line for each:
> > 
> > 	.BR F_RDLCK ,
> > 	.BR F_WRLCK ,
> > 	or
> > 	.BR F_UNLCK ,
> > 
> > > +indicating, respectively, a read delegation , a write delegation, or no delegation.
> >
> 
> ACK
> 
> > Spurious white space before comma.
> > 
> 
> ACK
> 
> > > +.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, and
> > > +conform to the delegation semantics described in RFC\ 8881.
> > 
> > I'd say the part after the comma is redundant with the STANDARDS
> > section.
> > 
> 
> Ok.
> 
> > > +.SH RETURN VALUE
> > > +On success zero is returned. On error, \-1 is returned, and
> > > +.I errno
> > > +is set to indicate the error. A successful F_GETDELEG call will also update the
> > 
> > F_GETDELEG should be in bold.
> > 
> 
> Ok.
> 
> > > +.I d_type
> > > +field in the structure to which
> > > +.I deleg
> > > +points.
> > > +.SH ERRORS
> > > +See
> > > +.BR fcntl (2).
> > 
> > I guess there are also errors specific to delegations, right?  I expect
> > for example an error if F_SETDELEG is called with F_WRLCK but more file
> > descriptors are open for the same file.
> > 
> 
> Only if the file descriptor was opened non-blocking. The errors are
> basically the same as the ones for leases. I can transplant the
> relevant error messages here though.

Hmm, I see the F_SETLEASE page doesn't document those either.

I think it would be good to document the errors, and in F_GETLEASE too,
if you can.  (Feel free to leave that for a later patch.)

> > > +.SH STANDARDS
> > > +Linux, IETF RFC\ 8881.
> > > +.SH HISTORY
> > > +Linux v6.19.
> > 
> > Please remove the 'v'.
> > 
> 
> ACK.
> 
> > > +.SH SEE ALSO
> > > +.BR fcntl (2)
> > > 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
> > 
> > Thanks!
> > 
> > 
> > Have a lovely day!
> > Alex
> 
> Thank you for the review! I'll update and send a v2.

Thanks!


Cheers,
Alex

> 
> Cheers,
> -- 
> Jeff Layton <jlayton@kernel.org>

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

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