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

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

@@ -0,0 +1 @@
+.so man2const/F_GETDELEG.2const