Hi Jeff, On Tue, Jan 13, 2026 at 09:45:11AM -0500, Jeff Layton wrote: [...] > > > +.SH SYNOPSIS > > > +.nf > > > +.B #define _GNU_SOURCE > > > +.B #include > > > +.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 --