man/man2const: clean up F_GETLEASE and add F_SETDELEG/F_GETDELEG manpages

Hi Jeff,

The following observation is not a blocker.

At 2026-01-14T12:35:24-0500, Jeff Layton wrote:
[...]

man/man2const/F_GETDELEG.2const line 44

Quoted 5 lines

+.P

man/man2const/F_GETDELEG.2const new file +4 -0

+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

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

---
 man/man2/fcntl.2                |   5 +
 man/man2const/F_GETDELEG.2const | 246 ++++++++++++++++++++++++++++++++++++++++
 man/man2const/F_SETDELEG.2const |   1 +
 3 files changed, 252 insertions(+)

man/man2/fcntl.2 +5 -0

index 7f34e332ef9070867c4cdb51e8c5d4991b4fac22..f05d559da149e6a4cc8ae935ffa32111deabd94d 100644
@@ -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)

man/man2const/F_GETDELEG.2const new file +21 -0

new file mode 100644
index 0000000000000000000000000000000000000000..43bfac5707b189a4e16b7068674d5ddc0ec98913
@@ -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 {

man/man2const/F_GETDELEG.2const new file +7 -0

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

man/man2const/F_GETDELEG.2const new file +17 -0

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

man/man2const/F_GETDELEG.2const new file +8 -0

+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

man/man2const/F_GETDELEG.2const new file +4 -0

+as
+.BR F_RDLCK .
+.P
+If the delegation holder fails to downgrade or remove the delegation within

man/man2const/F_GETDELEG.2const new file +19 -0

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

man/man2const/F_GETDELEG.2const new file +14 -0

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

man/man2const/F_GETDELEG.2const new file +5 -0

+.SH HISTORY
+Linux 6.19.
+.SH SEE ALSO
+.BR fcntl (2) ,
+.BR F_SETLEASE (2const)

man/man2const/F_SETDELEG.2const new file +1 -0

new file mode 100644
index 0000000000000000000000000000000000000000..acabdfc139fb3d753dbf3061c31d59332d046c63
@@ -0,0 +1 @@
+.so man2const/F_GETDELEG.2const

Signature · 2 lines

-- 
2.52.0

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

Signed-off-by Jeff Layton <[email protected]>

---
 man/man2const/F_GETLEASE.2const | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

man/man2const/F_GETLEASE.2const +17 -5

index 10f7ac7a89a70b83be10a381462d879cff813471..e841f7f8c7c64ba8c6868e68d493716040e3dec2 100644
@@ -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

Signature · 2 lines

-- 
2.52.0

From: Jeff Layton <[email protected]>

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

[alx: minor tweaks]

Signed-off-by Alejandro Colomar <[email protected]>

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

man/man2/fcntl.2 +5 -0

index 7f34e332e..f05d559da 100644
@@ -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)

man/man2const/F_GETDELEG.2const new file +265 -0

new file mode 100644
index 000000000..e4d98feed
@@ -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)

man/man2const/F_SETDELEG.2const new file +1 -0

new file mode 100644
index 000000000..acabdfc13
@@ -0,0 +1 @@
+.so man2const/F_GETDELEG.2const

base-commit: f17241696722c472c5fcd06ee3b7af7afc3f1082

Quoted 19 lines · Alejandro Colomar

From: Jeff Layton <[email protected]>

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

[alx: minor tweaks]

Signed-off-by Alejandro Colomar <[email protected]>

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

Quoted 6 lines

man/man2const/F_GETDELEG.2const new file +0 -0

new file mode 100644
index 000000000..e4d98feed
@@ -0,0 +1,265 @@

Quoted 2 lines

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

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

Hi Jeff,

Quoted 20 lines · Jeff Layton

Quoted 19 lines · Alejandro Colomar

From: Jeff Layton <[email protected]>

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

[alx: minor tweaks]

Signed-off-by Alejandro Colomar <[email protected]>

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

[...]

Quoted 6 lines

Quoted 6 lines

man/man2const/F_GETDELEG.2const new file +0 -0

new file mode 100644
index 000000000..e4d98feed
@@ -0,0 +1,265 @@

[...]

Quoted 2 lines

Quoted 2 lines

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

[...]

Quoted 1 line

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

The only remaining doubt is the question above.

Quoted 3 lines

Thanks for doing the cleanup! FWIW:

Reviewed-by Jeff Layton <[email protected]>

You're welcome! And thanks! :-)

Have a lovely day!
Alex

Quoted 6 lines

Quoted 2 lines

Quoted 2 lines

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

Quoted 2 lines

[...]

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.

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