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

[Alejandro Colomar <alx@kernel.org>]

[-- 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 --]