Debian Codegraph @

upstream/debian-unstable/man2/F_GETLEASE.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_GETLEASE 2const 2026-01-14 "Linux man-pages 6.18"
6 .SH NAME
7 F_GETLEASE,
8 F_SETLEASE
9 \-
10 leases
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_SETLEASE, int " arg );
20 .BI "int fcntl(int " fd ", F_GETLEASE);"
21 .fi
22 .SH DESCRIPTION
23 .B F_SETLEASE
24 and
25 .B F_GETLEASE
26 are used to establish a new lease,
27 and retrieve the current lease, on the open file description
28 referred to by the file descriptor
29 .IR fd .
30 A file lease provides a mechanism whereby the process holding
31 the lease (the "lease holder") is notified (via delivery of a signal)
32 when a process (the "lease breaker") tries to
33 .BR open (2)
34 or
35 .BR truncate (2)
36 the file referred to by that file descriptor.
37 .TP
38 .B F_SETLEASE
39 Set or remove a file lease according to which of the following
40 values is specified in the integer
41 .IR arg :
42 .RS
43 .TP
44 .B F_RDLCK
45 Establish a read lease.
46 This will cause the calling process to be notified when
47 the file is opened for writing or is truncated.
48 .\" The following became true in Linux 2.6.10:
49 .\" See the man-pages-2.09 Changelog for further info.
50 A read lease can be placed only on a file descriptor that
51 is opened read-only.
52 .TP
53 .B F_WRLCK
54 Establish a write lease.
55 This will cause the caller to be notified when
56 the file is opened for reading or writing or is truncated.
57 A write lease may be placed on a file only if there are no
58 other open file descriptors for the file.
59 .TP
60 .B F_UNLCK
61 Remove our lease from the file.
62 .RE
63 .P
64 Leases are associated with an open file description (see
65 .BR open (2)).
66 This means that duplicate file descriptors (created by, for example,
67 .BR fork (2)
68 or
69 .BR dup (2))
70 refer to the same lease, and this lease may be modified
71 or released using any of these descriptors.
72 Furthermore, the lease is released by either an explicit
73 .B F_UNLCK
74 operation on any of these duplicate file descriptors, or when all
75 such file descriptors have been closed.
76 .P
77 Leases may be taken out only on regular files.
78 An unprivileged process may take out a lease only on a file whose
79 UID (owner) matches the filesystem UID of the process.
80 A process with the
81 .B CAP_LEASE
82 capability may take out leases on arbitrary files.
83 .TP
84 .B F_GETLEASE
85 Indicates what type of lease is associated with the file descriptor
86 .I fd
87 by returning either
88 .BR F_RDLCK ,
89 .BR F_WRLCK ,
90 or
91 .BR F_UNLCK ,
92 indicating, respectively, a read lease, a write lease, or no lease.
93 .I arg
94 is ignored.
95 .P
96 When a process (the "lease breaker") performs an
97 .BR open (2)
98 or
99 .BR truncate (2)
100 that conflicts with a lease established via
101 .BR F_SETLEASE ,
102 the system call is blocked by the kernel and
103 the kernel notifies the lease holder by sending it a signal
104 .RB ( SIGIO
105 by default).
106 The lease holder should respond to receipt of this signal by doing
107 whatever cleanup is required in preparation for the file to be
108 accessed by another process (e.g., flushing cached buffers) and
109 then either remove or downgrade its lease.
110 A lease is removed by performing an
111 .B F_SETLEASE
112 operation specifying
113 .I arg
114 as
115 .BR F_UNLCK .
116 If the lease holder currently holds a write lease on the file,
117 and the lease breaker is opening the file for reading,
118 then it is sufficient for the lease holder to downgrade
119 the lease to a read lease.
120 This is done by performing an
121 .B F_SETLEASE
122 operation specifying
123 .I arg
124 as
125 .BR F_RDLCK .
126 .P
127 If the lease holder fails to downgrade or remove the lease within
128 the number of seconds specified in
129 .IR /proc/sys/fs/lease\-break\-time ,
130 then the kernel forcibly removes or downgrades the lease holder's lease.
131 .P
132 Once a lease break has been initiated,
133 .B F_GETLEASE
134 returns the target lease type (either
135 .B F_RDLCK
136 or
137 .BR F_UNLCK ,
138 depending on what would be compatible with the lease breaker)
139 until the lease holder voluntarily downgrades or removes the lease or
140 the kernel forcibly does so after the lease break timer expires.
141 .P
142 Once the lease has been voluntarily or forcibly removed or downgraded,
143 and assuming the lease breaker has not unblocked its system call,
144 the kernel permits the lease breaker's system call to proceed.
145 .P
146 If the lease breaker's blocked
147 .BR open (2)
148 or
149 .BR truncate (2)
150 is interrupted by a signal handler,
151 then the system call fails with the error
152 .BR EINTR ,
153 but the other steps still occur as described above.
154 If the lease breaker is killed by a signal while blocked in
155 .BR open (2)
156 or
157 .BR truncate (2),
158 then the other steps still occur as described above.
159 If the lease breaker specifies the
160 .B O_NONBLOCK
161 flag when calling
162 .BR open (2),
163 then the call immediately fails with the error
164 .BR EWOULDBLOCK ,
165 but the other steps still occur as described above.
166 .P
167 The default signal used to notify the lease holder is
168 .BR SIGIO ,
169 but this can be changed using the
170 .B F_SETSIG
171 operation to
172 .BR fcntl ().
173 If a
174 .B F_SETSIG
175 operation is performed (even one specifying
176 .BR SIGIO ),
177 and the signal
178 handler is established using
179 .BR SA_SIGINFO ,
180 then the handler will receive a
181 .I siginfo_t
182 structure as its second argument, and the
183 .I si_fd
184 field of this argument will hold the file descriptor of the leased file
185 that has been accessed by another process.
186 (This is useful if the caller holds leases against multiple files.)
187 .SH RETURN VALUE
188 .TP
189 .B F_GETLEASE
190 Type of lease held on file descriptor.
191 .TP
192 .B F_SETLEASE
193 Zero.
194 .P
195 On error, \-1 is returned, and
196 .I errno
197 is set to indicate the error.
198 .SH ERRORS
199 See
200 .BR fcntl (2).
201 .P
202 These operations can also fail with the following error codes:
203 .TP
204 .B EAGAIN
205 The operation is prohibited because
206 the file is open in a way that conflicts with the requested lease.
207 .TP
208 .B EINVAL
209 The operation is prohibited because
210 the underlying filesystem doesn't support leases,
211 or because
212 .I fd
213 does not represent a regular file.
214 .SH STANDARDS
215 Linux.
216 .SH HISTORY
217 Linux 2.4.
218 .SH SEE ALSO
219 .BR fcntl (2)