man/man2const: document the new F_SETDELEG and F_GETDELEG constants
PATCH 1/1 man/man2const: document the new F_SETDELEG and F_GETDELEG constants
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.
--- man/man2/fcntl.2 | 5 + man/man2const/F_GETDELEG.2const | 230 ++++++++++++++++++++++++++++++++++++++++ man/man2const/F_SETDELEG.2const | 1 + 3 files changed, 236 insertions(+)
man/man2/fcntl.2 +5 -0
@@ -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 +230 -0
230 lines not on this page · raw message
man/man2const/F_SETDELEG.2const new file +1 -0
@@ -0,0 +1 @@ +.so man2const/F_GETDELEG.2const
---
base-commit: 753ac20a01007417aa993e70d290f51840e2f477
change-id: 20260112-master-23a1ede99836
Best regards,
Signature · 1 line
Jeff Layton <[email protected]>
Alejandro Colomar
maintainerHi Jeff,
Quoted 45 lines · 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_GETDELEGandF_SETDELEGmanpages to document them.Signed-off-by Jeff Layton <[email protected]>--- man/man2/fcntl.2 | 5 + man/man2const/F_GETDELEG.2const | 230 ++++++++++++++++++++++++++++++++++++++++ man/man2const/F_SETDELEG.2const | 1 + 3 files changed, 236 insertions(+)man/man2/fcntl.2 +5
-0@@ -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 +10
-0@@ -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
man/man2const/F_GETDELEG.2const line 20
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+.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.
man/man2const/F_GETDELEG.2const line 28
Quoted 8 lines
man/man2const/F_GETDELEG.2const new file +8
-0+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?
man/man2const/F_GETDELEG.2const line 29
Quoted 1 line
man/man2const/F_GETDELEG.2const new file +1
-0+.br
This .br seems superfluous.
man/man2const/F_GETDELEG.2const line 33
Quoted 4 lines
man/man2const/F_GETDELEG.2const new file +4
-0+.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?
man/man2const/F_GETDELEG.2const line 39
Quoted 6 lines
man/man2const/F_GETDELEG.2const new file +6
-0+.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?
man/man2const/F_GETDELEG.2const line 40
Quoted 1 line
man/man2const/F_GETDELEG.2const new file +1
-0+.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.
Quoted 4 lines
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 +.BR open (2)
man/man2const/F_GETDELEG.2const line 54
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+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.man/man2const/F_GETDELEG.2const line 59
Quoted 5 lines
man/man2const/F_GETDELEG.2const new file +5
-0+.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
man/man2const/F_GETDELEG.2const line 61
Quoted 2 lines
man/man2const/F_GETDELEG.2const new file +2
-0+field of +.IR deleg :
Maybe we could even simplify this as:
... specified in .IR deleg->d_type :
man/man2const/F_GETDELEG.2const line 65
Quoted 4 lines
man/man2const/F_GETDELEG.2const new file +4
-0+.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.)
man/man2const/F_GETDELEG.2const line 75
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+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
Quoted 30 lines
man/man2const/F_GETDELEG.2const new file +30
-0+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.
man/man2const/F_GETDELEG.2const line 115
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+.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 ,
man/man2const/F_GETDELEG.2const line 116
Quoted 1 line
man/man2const/F_GETDELEG.2const new file +1
-0+indicating, respectively, a read delegation , a write delegation, or no delegation.
Spurious white space before comma.
Quoted 87 lines
man/man2const/F_GETDELEG.2const new file +87
-0+.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 ,
man/man2const/F_GETDELEG.2const line 213
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+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.
man/man2const/F_GETDELEG.2const line 217
Quoted 4 lines
man/man2const/F_GETDELEG.2const new file +4
-0+.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.
man/man2const/F_GETDELEG.2const line 224
Quoted 7 lines
man/man2const/F_GETDELEG.2const new file +7
-0+.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.
man/man2const/F_GETDELEG.2const line 228
Quoted 4 lines
man/man2const/F_GETDELEG.2const new file +4
-0+.SH STANDARDS +Linux, IETF RFC\ 8881. +.SH HISTORY +Linux v6.19.
Please remove the 'v'.
man/man2const/F_SETDELEG.2const line 1
Quoted 9 lines
man/man2const/F_GETDELEG.2const new file +2
-0+.SH SEE ALSO +.BR fcntl (2)man/man2const/F_SETDELEG.2const new file +1
-0@@ -0,0 +1 @@ +.so man2const/F_GETDELEG.2const
Thanks!
Have a lovely day!
Alex
Quoted 9 lines
---
base-commit:753ac20a01007417aa993e70d290f51840e2f477
change-id: 20260112-master-23a1ede99836Best regards,
Signature · 1 line
Jeff Layton <[email protected]>
Signature · 1 line
<https://www.alejandro-colomar.es>
Quoted 53 lines · Alejandro Colomar
Hi Jeff,
Quoted 50 lines · 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_GETDELEGandF_SETDELEGmanpages to document them.Signed-off-by Jeff Layton <[email protected]>--- man/man2/fcntl.2 | 5 + man/man2const/F_GETDELEG.2const | 230 ++++++++++++++++++++++++++++++++++++++++ man/man2const/F_SETDELEG.2const | 1 + 3 files changed, 236 insertions(+)man/man2/fcntl.2 +5
-0@@ -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 +15
-0@@ -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
Quoted 9 lines
man/man2const/F_GETDELEG.2const line 20
Quoted 5 lines
man/man2const/F_GETDELEG.2const new file +5
-0+.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.
Quoted 11 lines
man/man2const/F_GETDELEG.2const line 28
Quoted 8 lines
man/man2const/F_GETDELEG.2const new file +8
-0+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.
Quoted 4 lines
man/man2const/F_GETDELEG.2const line 29
Quoted 1 line
man/man2const/F_GETDELEG.2const new file +1
-0+.brThis .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.
Quoted 8 lines
man/man2const/F_GETDELEG.2const line 33
Quoted 4 lines
man/man2const/F_GETDELEG.2const new file +4
-0+.BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg ); +.fi +.SH DESCRIPTION +.SS DelegationsIf 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.
Quoted 10 lines
man/man2const/F_GETDELEG.2const line 39
Quoted 6 lines
man/man2const/F_GETDELEG.2const new file +6
-0+.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 descriptorJust 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".
Quoted 6 lines
man/man2const/F_GETDELEG.2const line 40
Quoted 1 line
man/man2const/F_GETDELEG.2const new file +1
-0+.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.
Quoted 17 lines
Quoted 4 lines
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 +.BR open (2)man/man2const/F_GETDELEG.2const line 54
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+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):
Quoted 10 lines
$ 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.
Quoted 16 lines
man/man2const/F_GETDELEG.2const line 59
Quoted 5 lines
man/man2const/F_GETDELEG.2const new file +5
-0+.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_types/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
Quoted 9 lines
man/man2const/F_GETDELEG.2const line 61
Quoted 2 lines
man/man2const/F_GETDELEG.2const new file +2
-0+field of +.IR deleg :Maybe we could even simplify this as:
... specified in .IR deleg->d_type :
Ok
Quoted 5 lines
man/man2const/F_GETDELEG.2const line 65
Quoted 4 lines
man/man2const/F_GETDELEG.2const new file +4
-0+.RS +.TP +.B F_RDLCK +Take out a read delegation.
Quoted 8 lines
'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.
Quoted 13 lines
man/man2const/F_GETDELEG.2const line 75
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+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_WRLCKAre we in time to rename this?
Quoted 8 lines
F_RDLCKblocks essentially writing.F_WRLCKblocks 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?
Quoted 43 lines
Quoted 30 lines
man/man2const/F_GETDELEG.2const new file +30
-0+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.man/man2const/F_GETDELEG.2const line 115
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+.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:
Quoted 7 lines
.BR
F_RDLCK,
.BRF_WRLCK,
or
.BRF_UNLCK,Quoted 1 line
man/man2const/F_GETDELEG.2const new file +1
-0+indicating, respectively, a read delegation , a write delegation, or no delegation.
ACK
Quoted 2 lines
Spurious white space before comma.
ACK
Quoted 92 lines
Quoted 92 lines
man/man2const/F_GETDELEG.2const new file +92
-0+.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
Quoted 9 lines
man/man2const/F_GETDELEG.2const line 213
Quoted 5 lines
man/man2const/F_GETDELEG.2const new file +5
-0+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.
Quoted 7 lines
man/man2const/F_GETDELEG.2const line 217
Quoted 4 lines
man/man2const/F_GETDELEG.2const new file +4
-0+.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_GETDELEGshould be in bold.
Ok.
Quoted 12 lines
man/man2const/F_GETDELEG.2const line 224
Quoted 7 lines
man/man2const/F_GETDELEG.2const new file +7
-0+.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_SETDELEGis called withF_WRLCKbut 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.
Quoted 7 lines
man/man2const/F_GETDELEG.2const line 228
Quoted 4 lines
man/man2const/F_GETDELEG.2const new file +4
-0+.SH STANDARDS +Linux, IETF RFC\ 8881. +.SH HISTORY +Linux v6.19.Please remove the 'v'.
ACK.
Quoted 13 lines
man/man2const/F_SETDELEG.2const line 1
Quoted 9 lines
man/man2const/F_GETDELEG.2const new file +2
-0+.SH SEE ALSO +.BR fcntl (2)man/man2const/F_SETDELEG.2const new file +1
-0@@ -0,0 +1 @@ +.so man2const/F_GETDELEG.2constThanks!
Quoted 2 lines
Have a lovely day!
Alex
Thank you for the review! I'll update and send a v2.
Cheers,
Signature · 1 line
Jeff Layton <[email protected]>
Hi Jeff and Alex,
Quoted 2 lines · Jeff Layton
Quoted 1 line · Alejandro Colomar
On Mon, Jan 12, 2026 at 01:47:11PM -0500, Jeff Layton wrote:
[...]
Quoted 7 lines
Quoted 4 lines
Quoted 1 line
+.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
Quoted 1 line
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.
Regards,
Branden
Alejandro Colomar
maintainerHi Jeff,
On Tue, Jan 13, 2026 at 09:45:11AM -0500, Jeff Layton wrote:
[...]
Quoted 26 lines
Quoted 11 lines
Quoted 7 lines
+.SH SYNOPSIS
+.nf
+.B #define_GNU_SOURCE
+.B #include <fcntl.h>
+.P
+.EX
+/* Argument structure forF_GETDELEGandF_SETDELEG*/I'd say this comment seems redundant, given this structure is defined in this manual page.
Ack. Will remove.
Quoted 11 lines
man/man2const/F_GETDELEG.2const line 28
Quoted 8 lines
man/man2const/F_GETDELEG.2const new file +8
-0+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?
Quoted 3 lines
Yes, it does modify it.
F_GETDELEGpopulatesd_type. I have some plans to expand this interface in the future soF_GETDELEGmay eventually return other fields in there too.
But I mean F_SETDELEG (with an S). I expect the setter wouldn't modify, right?
Quoted 10 lines
Quoted 5 lines
Quoted 2 lines
+.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.
Quoted 11 lines
Quoted 8 lines
Quoted 4 lines
+.BI "int
fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg ); +.fi
+.SH DESCRIPTION
+.SS DelegationsIf 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).
Quoted 11 lines
Quoted 10 lines
man/man2const/F_GETDELEG.2const line 39
Quoted 6 lines
+.B
F_SETDELEGman/man2const/F_GETDELEG.2const new file +5
-0+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 descriptorJust to confirm: one can't retrieve delegations through a different file description that refers to the same inode, right?
Quoted 2 lines
Correct.
F_GETDELEGjust fills out ->d_type with the type of delegation set on "fd".
Thanks!
Quoted 37 lines
Quoted 6 lines
Quoted 1 line
+.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.
Quoted 17 lines
Quoted 4 lines
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 +.BR open (2)man/man2const/F_GETDELEG.2const line 54
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+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):
Quoted 10 lines
$ 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.
Quoted 1 line
Ok, I'll reformat that.
This applies also to the rest of the page, BTW.
Quoted 62 lines
Quoted 16 lines
man/man2const/F_GETDELEG.2const line 59
Quoted 5 lines
+.TP
+.BF_SETDELEGman/man2const/F_GETDELEG.2const new file +3
-0+Set or remove a file or directory delegation according to which of the following +values is specified in the +.IR d_types/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_typeQuoted 9 lines
Quoted 2 lines
+field of
+.IR deleg :Maybe we could even simplify this as:
... specified in .IR deleg->d_type :Ok
Quoted 5 lines
Quoted 4 lines
+.RS
+.TP
+.BF_RDLCK
+Take out a read delegation.Quoted 8 lines
'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.
Quoted 16 lines
man/man2const/F_GETDELEG.2const line 75
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+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_WRLCKAre we in time to rename this?
F_RDLCKblocks essentially writing.F_WRLCKblocks both reading and writing.
Quoted 8 lines
Quoted 5 lines
What do you think of this rename:
RD => WR
WR => RWThese 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.
Quoted 185 lines
Quoted 43 lines
Quoted 30 lines
man/man2const/F_GETDELEG.2const new file +30
-0+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.man/man2const/F_GETDELEG.2const line 115
Quoted 10 lines
man/man2const/F_GETDELEG.2const new file +10
-0+.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:
Quoted 7 lines
.BR
F_RDLCK,
.BRF_WRLCK,
or
.BRF_UNLCK,Quoted 1 line
+indicating, respectively, a read delegation , a write delegation, or no delegation.
ACK
Quoted 2 lines
Spurious white space before comma.
ACK
Quoted 92 lines
Quoted 92 lines
+.P
man/man2const/F_GETDELEG.2const new file +91
-0+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 delegationQuoted 9 lines
man/man2const/F_GETDELEG.2const line 213
Quoted 5 lines
man/man2const/F_GETDELEG.2const new file +5
-0+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.
Quoted 7 lines
man/man2const/F_GETDELEG.2const line 217
Quoted 4 lines
+.SH RETURN VALUE
man/man2const/F_GETDELEG.2const new file +3
-0+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_GETDELEGshould be in bold.Ok.
Quoted 12 lines
man/man2const/F_GETDELEG.2const line 224
Quoted 7 lines
+.I
d_typeman/man2const/F_GETDELEG.2const new file +6
-0+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_SETDELEGis called withF_WRLCKbut more file descriptors are open for the same file.
Quoted 3 lines
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.)
Quoted 23 lines
Quoted 7 lines
man/man2const/F_GETDELEG.2const line 228
Quoted 4 lines
+.SH STANDARDS
man/man2const/F_GETDELEG.2const new file +3
-0+Linux, IETF RFC\ 8881. +.SH HISTORY +Linux v6.19.Please remove the 'v'.
ACK.
Quoted 13 lines
man/man2const/F_SETDELEG.2const line 1
Quoted 9 lines
+.SH SEE ALSO
+.BR fcntl (2)man/man2const/F_SETDELEG.2const new file +1
-0@@ -0,0 +1 @@ +.so man2const/F_GETDELEG.2constThanks!
Quoted 4 lines
Quoted 2 lines
Have a lovely day!
AlexThank you for the review! I'll update and send a v2.
Thanks!
Cheers,
Alex
Quoted 4 lines
Cheers,
Signature · 1 line
Jeff Layton <[email protected]>
Signature · 1 line
<https://www.alejandro-colomar.es>