From: Jeff Layton 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 [alx: minor tweaks] Signed-off-by: Alejandro Colomar --- 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 diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2 index 7f34e332e..f05d559da 100644 --- a/man/man2/fcntl.2 +++ b/man/man2/fcntl.2 @@ -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) diff --git a/man/man2const/F_GETDELEG.2const b/man/man2const/F_GETDELEG.2const new file mode 100644 index 000000000..e4d98feed --- /dev/null +++ b/man/man2const/F_GETDELEG.2const @@ -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 +.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) diff --git a/man/man2const/F_SETDELEG.2const b/man/man2const/F_SETDELEG.2const new file mode 100644 index 000000000..acabdfc13 --- /dev/null +++ b/man/man2const/F_SETDELEG.2const @@ -0,0 +1 @@ +.so man2const/F_GETDELEG.2const base-commit: f17241696722c472c5fcd06ee3b7af7afc3f1082 -- 2.51.0