Debian Codegraph @

upstream/debian-unstable/man2/F_GETDELEG.2const

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH F_GETDELEG 2const 2026-01-23 "Linux man-pages 6.18"
6 .SH NAME
7 F_GETDELEG,
8 F_SETDELEG
9 \-
10 delegations
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #define _GNU_SOURCE
17 .B #include <fcntl.h>
18 .P
19 .BI "int fcntl(int " fd ", F_SETDELEG, const struct delegation *" deleg );
20 .BI "int fcntl(int " fd ", F_GETDELEG, struct delegation *" deleg );
21 .fi
22 .P
23 .EX
24 struct delegation {
25 __u32 d_flags;
26 __u16 d_type;
27 __u16 __pad;
28 };
29 .EE
30 .SH DESCRIPTION
31 .B F_SETDELEG
32 and
33 .B F_GETDELEG
34 are used to establish a new delegation,
35 and retrieve the current delegation,
36 on the open file description referred to by the file descriptor
37 .IR fd .
38 .P
39 A file delegation is a mechanism whereby
40 the process holding the delegation (the "delegation holder")
41 is notified (via delivery of a signal)
42 when a process (the "delegation breaker")
43 tries to
44 .BR open (2)
45 or
46 .BR truncate (2)
47 the file referred to by that file descriptor,
48 or tries to
49 .BR unlink (2)
50 or
51 .BR rename (2)
52 the dentry that was originally opened for the file.
53 .P
54 Delegations can also be set on directory file descriptors.
55 The holder of a directory delegation will be notified if there is a
56 create, delete, or rename of a dirent within the directory.
57 .TP
58 .B F_SETDELEG
59 Set or remove a file or directory delegation according to the
60 value specified in
61 .IR deleg->d_type :
62 .RS
63 .TP
64 .B F_RDLCK
65 Establish a read delegation.
66 This will cause the calling process to be notified
67 when the file is
68 opened for writing,
69 or is truncated, unlinked or renamed.
70 A read delegation can be placed
71 only on a file descriptor that is opened read-only.
72 .IP
73 If
74 .I fd
75 refers to a directory,
76 then the calling process will be notified
77 if there are changes to filenames within the directory,
78 or when the directory itself is renamed.
79 .TP
80 .B F_WRLCK
81 Establish a write delegation.
82 This will cause the caller to be notified
83 when the file is opened for reading or writing,
84 or is truncated, renamed or unlinked.
85 A write delegation may be placed on a file
86 only if there are no other open file descriptors for the file.
87 The file must be opened for write
88 in order to set a write delegation on it.
89 Write delegations cannot be set on directory file descriptors.
90 .TP
91 .B F_UNLCK
92 Remove our delegation from the file.
93 .RE
94 .P
95 Like leases,
96 delegations are associated with an open file description
97 (see
98 .BR open (2)).
99 This means that duplicate file descriptors
100 (created by, for example,
101 .BR fork (2)
102 or
103 .BR dup (2))
104 refer to the same delegation,
105 and this delegation may be modified or released
106 using any of these descriptors.
107 Furthermore,
108 the delegation is released by either an explicit
109 .B F_UNLCK
110 operation on any of these duplicate file descriptors,
111 or when all such file descriptors have been closed.
112 .P
113 An unprivileged process may establish a delegation
114 only on a file whose UID (owner) matches the filesystem UID of the process.
115 A process with the
116 .B CAP_LEASE
117 capability may establish delegations on arbitrary files and directories.
118 .TP
119 .B F_GETDELEG
120 Indicates what type of delegation is associated with the file descriptor
121 .I fd
122 by setting
123 .I deleg->d_type
124 to either
125 .BR F_RDLCK ,
126 .BR F_WRLCK ,
127 or
128 .BR F_UNLCK ,
129 indicating, respectively,
130 a read delegation, a write delegation, or no delegation.
131 .P
132 When a process (the "delegation breaker")
133 performs an activity that conflicts with a delegation
134 established via
135 .BR F_SETDELEG ,
136 the system call is blocked by the kernel
137 and the kernel notifies the delegation holder by sending it a signal
138 .RB ( SIGIO
139 by default).
140 The delegation holder should respond to receipt of this signal
141 by doing whatever cleanup is required
142 in preparation for the file to be
143 accessed by another process
144 (e.g., flushing cached buffers)
145 and then either remove or downgrade its delegation.
146 A delegation is removed by performing an
147 .B F_SETDELEG
148 operation specifying
149 .I deleg->d_type
150 as
151 .BR F_UNLCK .
152 If the delegation holder currently holds
153 a write delegation on the file,
154 and the delegation breaker
155 is opening the file for reading,
156 then it is sufficient for the delegation holder to
157 downgrade the delegation to a read delegation.
158 This is done by performing an
159 .B F_SETDELEG
160 operation specifying
161 .I deleg->d_type
162 as
163 .BR F_RDLCK .
164 .P
165 If the delegation holder
166 fails to downgrade or remove the delegation
167 within the number of seconds specified in
168 .IR /proc/sys/fs/lease\-break\-time ,
169 then the kernel
170 forcibly removes or downgrades the delegation holder's delegation.
171 .P
172 Once a delegation break has been initiated,
173 .B F_GETDELEG
174 returns the target delegation type in the
175 .I deleg->d_type
176 (either
177 .B F_RDLCK
178 or
179 .BR F_UNLCK ,
180 depending on what would be compatible with the delegation breaker)
181 until the delegation holder voluntarily downgrades or removes the delegation
182 or the kernel forcibly does so after the delegation break timer expires.
183 .P
184 Once the delegation has been voluntarily or forcibly removed or downgraded,
185 and assuming the delegation breaker has not unblocked its system call,
186 the kernel permits the delegation breaker's system call to proceed.
187 .P
188 If the delegation breaker's blocked system call
189 is interrupted by a signal handler,
190 then the system call fails with the error
191 .BR EINTR ,
192 but the other steps still occur as described above.
193 If the delegation breaker is killed by a signal while blocked in
194 .BR open (2)
195 or
196 .BR truncate (2),
197 then the other steps still occur as described above.
198 If the delegation breaker specifies the
199 .B O_NONBLOCK
200 flag when calling
201 .BR open (2),
202 then the call immediately fails with the error
203 .BR EWOULDBLOCK ,
204 but the other steps still occur as described above.
205 .P
206 The default signal used to notify the delegation holder is
207 .BR SIGIO ,
208 but this can be changed using
209 .BR F_SETSIG (2const).
210 If a
211 .BR F_SETSIG (2const)
212 operation is performed
213 (even one specifying
214 .BR SIGIO ),
215 and the signal
216 handler is established using
217 .BR SA_SIGINFO ,
218 then the handler will receive a
219 .I siginfo_t
220 structure as its second argument,
221 and the
222 .I si_fd
223 field of this argument will hold
224 the file descriptor of the file with the delegation
225 that has been accessed by another process.
226 (This is useful if the caller holds delegations against multiple files.)
227 .SH NOTES
228 Delegations were designed to implement
229 NFSv4 (RFC\ 8881) delegations
230 for the Linux NFS server.
231 .SH RETURN VALUE
232 On success zero is returned.
233 On error, \-1 is returned, and
234 .I errno
235 is set to indicate the error.
236 A successful
237 .B F_GETDELEG
238 call will also update the
239 .I deleg->d_type
240 field.
241 .SH ERRORS
242 See
243 .BR fcntl (2).
244 These operations can also return the following errors:
245 .TP
246 .B EAGAIN
247 The file was held open in a way that
248 conflicts with the requested delegation.
249 .TP
250 .B EINVAL
251 The caller tried to set a
252 .B F_WRLCK
253 delegation and
254 .I fd
255 represents a directory.
256 .TP
257 .B EINVAL
258 .I fd
259 doesn't represent a file or directory.
260 .TP
261 .B EINVAL
262 The underlying filesystem doesn't support delegations.
263 .SH STANDARDS
264 Linux,
265 IETF\ RFC\ 8881.
266 .SH HISTORY
267 Linux 6.19.
268 .SH SEE ALSO
269 .BR fcntl (2) ,
270 .BR F_SETLEASE (2const)