]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | '\" t |
fea681da | 2 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
99b5ab79 MK |
3 | .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson; |
4 | .\" and Copyright (C) 1998 Jamie Lokier; | |
5 | .\" and Copyright (C) 2002-2010, 2014 Michael Kerrisk; | |
6 | .\" and Copyright (C) 2014 Jeff Layton | |
6bdad35b | 7 | .\" and Copyright (C) 2014 David Herrmann |
fea681da | 8 | .\" |
93015253 | 9 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
10 | .\" Permission is granted to make and distribute verbatim copies of this |
11 | .\" manual provided the copyright notice and this permission notice are | |
12 | .\" preserved on all copies. | |
13 | .\" | |
14 | .\" Permission is granted to copy and distribute modified versions of this | |
15 | .\" manual under the conditions for verbatim copying, provided that the | |
16 | .\" entire resulting derived work is distributed under the terms of a | |
17 | .\" permission notice identical to this one. | |
c13182ef | 18 | .\" |
fea681da MK |
19 | .\" Since the Linux kernel and libraries are constantly changing, this |
20 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
21 | .\" responsibility for errors or omissions, or for damages resulting from | |
22 | .\" the use of the information contained herein. The author(s) may not | |
23 | .\" have taken the same level of care in the production of this manual, | |
24 | .\" which is licensed free of charge, as they might when working | |
25 | .\" professionally. | |
c13182ef | 26 | .\" |
fea681da MK |
27 | .\" Formatted or processed versions of this manual, if unaccompanied by |
28 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 29 | .\" %%%LICENSE_END |
fea681da MK |
30 | .\" |
31 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
32 | .\" Modified 1995-09-26 by Andries Brouwer <aeb@cwi.nl> | |
33 | .\" and again on 960413 and 980804 and 981223. | |
34 | .\" Modified 1998-12-11 by Jamie Lokier <jamie@imbolc.ucc.ie> | |
35 | .\" Applied correction by Christian Ehrhardt - aeb, 990712 | |
c11b1abf | 36 | .\" Modified 2002-04-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
37 | .\" Added note on F_SETFL and O_DIRECT |
38 | .\" Complete rewrite + expansion of material on file locking | |
39 | .\" Incorporated description of F_NOTIFY, drawing on | |
40 | .\" Stephen Rothwell's notes in Documentation/dnotify.txt. | |
41 | .\" Added description of F_SETLEASE and F_GETLEASE | |
42 | .\" Corrected and polished, aeb, 020527. | |
c11b1abf | 43 | .\" Modified 2004-03-03 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
44 | .\" Modified description of file leases: fixed some errors of detail |
45 | .\" Replaced the term "lease contestant" by "lease breaker" | |
c11b1abf | 46 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 47 | .\" Added notes on capability requirements |
1c1e15ed | 48 | .\" Modified 2004-12-08, added O_NOATIME after note from Martin Pool |
c13182ef | 49 | .\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb. |
2f36a807 | 50 | .\" 2005-04-08 Jamie Lokier <jamie@shareable.org>, mtk |
d9bfdb9c | 51 | .\" Described behavior of F_SETOWN/F_SETSIG in |
71fea607 | 52 | .\" multithreaded processes, and generally cleaned |
2f36a807 | 53 | .\" up the discussion of F_SETOWN. |
c13182ef | 54 | .\" 2005-05-20, Johannes Nicolai <johannes.nicolai@hpi.uni-potsdam.de>, |
9d2a7b1f MK |
55 | .\" mtk: Noted F_SETOWN bug for socket file descriptor in Linux 2.4 |
56 | .\" and earlier. Added text on permissions required to send signal. | |
dd164bfc MK |
57 | .\" 2009-09-30, Michael Kerrisk |
58 | .\" Note obsolete F_SETOWN behavior with threads. | |
59 | .\" Document F_SETOWN_EX and F_GETOWN_EX | |
14f7d1a4 MK |
60 | .\" 2010-06-17, Michael Kerrisk |
61 | .\" Document F_SETPIPE_SZ and F_GETPIPE_SZ. | |
a25d701d | 62 | .\" 2014-07-08, David Herrmann <dh.herrmann@gmail.com> |
6bdad35b | 63 | .\" Document F_ADD_SEALS and F_GET_SEALS |
fea681da | 64 | .\" |
b8efb414 | 65 | .TH FCNTL 2 2016-10-08 "Linux" "Linux Programmer's Manual" |
fea681da MK |
66 | .SH NAME |
67 | fcntl \- manipulate file descriptor | |
68 | .SH SYNOPSIS | |
69 | .nf | |
70 | .B #include <unistd.h> | |
71 | .B #include <fcntl.h> | |
72 | .sp | |
68e0696a | 73 | .BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );" |
fea681da MK |
74 | .fi |
75 | .SH DESCRIPTION | |
cff88e99 MK |
76 | .BR fcntl () |
77 | performs one of the operations described below on the open file descriptor | |
fea681da | 78 | .IR fd . |
cff88e99 | 79 | The operation is determined by |
fea681da | 80 | .IR cmd . |
68e0696a MK |
81 | |
82 | .BR fcntl () | |
83 | can take an optional third argument. | |
84 | Whether or not this argument is required is determined by | |
85 | .IR cmd . | |
63a6efda | 86 | The required argument type is indicated in parentheses after each |
68e0696a MK |
87 | .I cmd |
88 | name (in most cases, the required type is | |
ed9821bb | 89 | .IR int , |
68e0696a MK |
90 | and we identify the argument using the name |
91 | .IR arg ), | |
92 | or | |
93 | .I void | |
94 | is specified if the argument is not required. | |
6024e733 MK |
95 | |
96 | Certain of the operations below are supported only since a particular | |
97 | Linux kernel version. | |
98 | The preferred method of checking whether the host kernel supports | |
99 | a particular operation is to invoke | |
100 | .BR fcntl () | |
101 | with the desired | |
102 | .IR cmd | |
103 | value and then test whether the call failed with | |
104 | .BR EINVAL , | |
105 | indicating that the kernel does not recognize this value. | |
73d8cece | 106 | .SS Duplicating a file descriptor |
fea681da | 107 | .TP |
ed9821bb | 108 | .BR F_DUPFD " (\fIint\fP)" |
6a459f6f MK |
109 | Duplicate the file descriptor |
110 | .IR fd | |
111 | using the lowest-numbered available file descriptor greater than or equal to | |
112 | .IR arg . | |
cff88e99 | 113 | This is different from |
68e0696a | 114 | .BR dup2 (2), |
d9cb0d7d | 115 | which uses exactly the file descriptor specified. |
ca92ce95 | 116 | .IP |
d9cb0d7d | 117 | On success, the new file descriptor is returned. |
ca92ce95 | 118 | .IP |
cff88e99 MK |
119 | See |
120 | .BR dup (2) | |
121 | for further details. | |
ef203e45 | 122 | .TP |
ed9821bb | 123 | .BR F_DUPFD_CLOEXEC " (\fIint\fP; since Linux 2.6.24)" |
635d3959 | 124 | As for |
ef203e45 MK |
125 | .BR F_DUPFD , |
126 | but additionally set the | |
d9cb0d7d | 127 | close-on-exec flag for the duplicate file descriptor. |
ef203e45 | 128 | Specifying this flag permits a program to avoid an additional |
0e92e8cc | 129 | .BR fcntl () |
ef203e45 MK |
130 | .B F_SETFD |
131 | operation to set the | |
132 | .B FD_CLOEXEC | |
133 | flag. | |
134 | For an explanation of why this flag is useful, | |
e4b4caa6 | 135 | see the description of |
ef203e45 MK |
136 | .B O_CLOEXEC |
137 | in | |
138 | .BR open (2). | |
73d8cece | 139 | .SS File descriptor flags |
cff88e99 | 140 | The following commands manipulate the flags associated with |
c13182ef | 141 | a file descriptor. |
cff88e99 MK |
142 | Currently, only one such flag is defined: |
143 | .BR FD_CLOEXEC , | |
144 | the close-on-exec flag. | |
145 | If the | |
fea681da | 146 | .B FD_CLOEXEC |
8b4be846 MK |
147 | bit is set, |
148 | the file descriptor will automatically be closed during a successful | |
149 | .BR execve (2). | |
150 | (If the | |
151 | .BR execve (2) | |
152 | fails, the file descriptor is left open.) | |
153 | If the | |
154 | .B FD_CLOEXEC | |
155 | bit is not set, the file descriptor will remain open across an | |
156 | .BR execve (2). | |
fea681da | 157 | .TP |
68e0696a | 158 | .BR F_GETFD " (\fIvoid\fP)" |
f157f403 | 159 | Return (as the function result) the file descriptor flags; |
68e0696a MK |
160 | .I arg |
161 | is ignored. | |
cff88e99 | 162 | .TP |
ed9821bb | 163 | .BR F_SETFD " (\fIint\fP)" |
cff88e99 | 164 | Set the file descriptor flags to the value specified by |
fea681da | 165 | .IR arg . |
2f4772d2 MK |
166 | .PP |
167 | In multithreaded programs, using | |
168 | .BR fcntl () | |
169 | .B F_SETFD | |
170 | to set the close-on-exec flag at the same time as another thread performs a | |
171 | .BR fork (2) | |
172 | plus | |
173 | .BR execve (2) | |
174 | is vulnerable to a race condition that may unintentionally leak | |
175 | the file descriptor to the program executed in the child process. | |
176 | See the discussion of the | |
177 | .BR O_CLOEXEC | |
178 | flag in | |
179 | .BR open (2) | |
180 | for details and a remedy to the problem. | |
73d8cece | 181 | .SS File status flags |
08478724 MK |
182 | Each open file description has certain associated status flags, |
183 | initialized by | |
fea681da MK |
184 | .BR open (2) |
185 | .\" or | |
186 | .\" .BR creat (2), | |
187 | and possibly modified by | |
2777b1ca | 188 | .BR fcntl (). |
c13182ef | 189 | Duplicated file descriptors |
cff88e99 | 190 | (made with |
0bfa087b | 191 | .BR dup (2), |
cff88e99 | 192 | .BR fcntl (F_DUPFD), |
0bfa087b | 193 | .BR fork (2), |
cff88e99 MK |
194 | etc.) refer to the same open file description, and thus |
195 | share the same file status flags. | |
ca92ce95 | 196 | |
cff88e99 | 197 | The file status flags and their semantics are described in |
fea681da MK |
198 | .BR open (2). |
199 | .TP | |
68e0696a | 200 | .BR F_GETFL " (\fIvoid\fP)" |
f157f403 MK |
201 | Return (as the function result) |
202 | the file access mode and the file status flags; | |
68e0696a MK |
203 | .I arg |
204 | is ignored. | |
fea681da | 205 | .TP |
ed9821bb | 206 | .BR F_SETFL " (\fIint\fP)" |
cff88e99 | 207 | Set the file status flags to the value specified by |
fea681da | 208 | .IR arg . |
c13182ef | 209 | File access mode |
cff88e99 MK |
210 | .RB ( O_RDONLY ", " O_WRONLY ", " O_RDWR ) |
211 | and file creation flags | |
68b93ce2 MK |
212 | (i.e., |
213 | .BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", " O_TRUNC ) | |
cff88e99 | 214 | in |
fea681da MK |
215 | .I arg |
216 | are ignored. | |
329ad271 | 217 | On Linux, this command can change only the |
c13182ef | 218 | .BR O_APPEND , |
1c1e15ed MK |
219 | .BR O_ASYNC , |
220 | .BR O_DIRECT , | |
221 | .BR O_NOATIME , | |
c13182ef | 222 | and |
0daa9e92 | 223 | .B O_NONBLOCK |
1c1e15ed | 224 | flags. |
639b33d7 MK |
225 | It is not possible to change the |
226 | .BR O_DSYNC | |
227 | and | |
228 | .BR O_SYNC | |
229 | flags; see BUGS, below. | |
9584daf7 | 230 | .SS Advisory record locking |
7562b10e MK |
231 | Linux implements traditional ("process-associated") UNIX record locks, |
232 | as standardized by POSIX. | |
233 | For a Linux-specific alternative with better semantics, | |
234 | see the discussion of open file description locks below. | |
235 | ||
dc45cae3 MK |
236 | .BR F_SETLK , |
237 | .BR F_SETLKW , | |
238 | and | |
239 | .BR F_GETLK | |
fea681da | 240 | are used to acquire, release, and test for the existence of record |
9584daf7 | 241 | locks (also known as byte-range, file-segment, or file-region locks). |
68e0696a MK |
242 | The third argument, |
243 | .IR lock , | |
fea681da MK |
244 | is a pointer to a structure that has at least the following fields |
245 | (in unspecified order). | |
088a639b | 246 | .in +4n |
fea681da MK |
247 | .nf |
248 | .sp | |
249 | struct flock { | |
250 | ... | |
251 | short l_type; /* Type of lock: F_RDLCK, | |
252 | F_WRLCK, F_UNLCK */ | |
253 | short l_whence; /* How to interpret l_start: | |
254 | SEEK_SET, SEEK_CUR, SEEK_END */ | |
255 | off_t l_start; /* Starting offset for lock */ | |
256 | off_t l_len; /* Number of bytes to lock */ | |
257 | pid_t l_pid; /* PID of process blocking our lock | |
99b5ab79 | 258 | (set by F_GETLK and F_OFD_GETLK) */ |
fea681da MK |
259 | ... |
260 | }; | |
261 | .fi | |
088a639b | 262 | .in |
fea681da MK |
263 | .P |
264 | The | |
265 | .IR l_whence ", " l_start ", and " l_len | |
266 | fields of this structure specify the range of bytes we wish to lock. | |
057dce78 MK |
267 | Bytes past the end of the file may be locked, |
268 | but not bytes before the start of the file. | |
269 | ||
fea681da MK |
270 | .I l_start |
271 | is the starting offset for the lock, and is interpreted | |
272 | relative to either: | |
273 | the start of the file (if | |
274 | .I l_whence | |
275 | is | |
276 | .BR SEEK_SET ); | |
277 | the current file offset (if | |
278 | .I l_whence | |
279 | is | |
280 | .BR SEEK_CUR ); | |
281 | or the end of the file (if | |
282 | .I l_whence | |
283 | is | |
284 | .BR SEEK_END ). | |
285 | In the final two cases, | |
286 | .I l_start | |
287 | can be a negative number provided the | |
288 | offset does not lie before the start of the file. | |
057dce78 | 289 | |
fea681da | 290 | .I l_len |
057dce78 MK |
291 | specifies the number of bytes to be locked. |
292 | If | |
293 | .I l_len | |
294 | is positive, then the range to be locked covers bytes | |
295 | .I l_start | |
296 | up to and including | |
95dadb39 | 297 | .IR l_start + l_len \-1. |
fea681da MK |
298 | Specifying 0 for |
299 | .I l_len | |
300 | has the special meaning: lock all bytes starting at the | |
301 | location specified by | |
302 | .IR l_whence " and " l_start | |
303 | through to the end of file, no matter how large the file grows. | |
057dce78 MK |
304 | |
305 | POSIX.1-2001 allows (but does not require) | |
306 | an implementation to support a negative | |
307 | .I l_len | |
308 | value; if | |
309 | .I l_len | |
310 | is negative, the interval described by | |
311 | .I lock | |
312 | covers bytes | |
313 | .IR l_start + l_len | |
314 | up to and including | |
315 | .IR l_start \-1. | |
316 | This is supported by Linux since kernel versions 2.4.21 and 2.5.49. | |
317 | ||
fea681da MK |
318 | The |
319 | .I l_type | |
320 | field can be used to place a read | |
321 | .RB ( F_RDLCK ) | |
322 | or a write | |
1c287bbf | 323 | .RB ( F_WRLCK ) |
fea681da MK |
324 | lock on a file. |
325 | Any number of processes may hold a read lock (shared lock) | |
326 | on a file region, but only one process may hold a write lock | |
7c93fec0 MK |
327 | (exclusive lock). |
328 | An exclusive lock excludes all other locks, | |
fea681da MK |
329 | both shared and exclusive. |
330 | A single process can hold only one type of lock on a file region; | |
331 | if a new lock is applied to an already-locked region, | |
8c450534 | 332 | then the existing lock is converted to the new lock type. |
fea681da MK |
333 | (Such conversions may involve splitting, shrinking, or coalescing with |
334 | an existing lock if the byte range specified by the new lock does not | |
335 | precisely coincide with the range of the existing lock.) | |
336 | .TP | |
68e0696a | 337 | .BR F_SETLK " (\fIstruct flock *\fP)" |
fea681da MK |
338 | Acquire a lock (when |
339 | .I l_type | |
340 | is | |
341 | .B F_RDLCK | |
342 | or | |
343 | .BR F_WRLCK ) | |
344 | or release a lock (when | |
345 | .I l_type | |
346 | is | |
347 | .BR F_UNLCK ) | |
348 | on the bytes specified by the | |
349 | .IR l_whence ", " l_start ", and " l_len | |
350 | fields of | |
351 | .IR lock . | |
352 | If a conflicting lock is held by another process, | |
353 | this call returns \-1 and sets | |
354 | .I errno | |
355 | to | |
356 | .B EACCES | |
357 | or | |
358 | .BR EAGAIN . | |
d068eb3b MK |
359 | (The error returned in this case differs across implementations, |
360 | so POSIX requires a portable application to check for both errors.) | |
fea681da | 361 | .TP |
68e0696a | 362 | .BR F_SETLKW " (\fIstruct flock *\fP)" |
fea681da MK |
363 | As for |
364 | .BR F_SETLK , | |
365 | but if a conflicting lock is held on the file, then wait for that | |
366 | lock to be released. | |
367 | If a signal is caught while waiting, then the call is interrupted | |
368 | and (after the signal handler has returned) | |
369 | returns immediately (with return value \-1 and | |
370 | .I errno | |
371 | set to | |
01538d0d MK |
372 | .BR EINTR ; |
373 | see | |
374 | .BR signal (7)). | |
fea681da | 375 | .TP |
68e0696a | 376 | .BR F_GETLK " (\fIstruct flock *\fP)" |
fea681da MK |
377 | On input to this call, |
378 | .I lock | |
379 | describes a lock we would like to place on the file. | |
380 | If the lock could be placed, | |
381 | .BR fcntl () | |
382 | does not actually place it, but returns | |
383 | .B F_UNLCK | |
384 | in the | |
385 | .I l_type | |
386 | field of | |
387 | .I lock | |
388 | and leaves the other fields of the structure unchanged. | |
99b5ab79 | 389 | |
fea681da MK |
390 | If one or more incompatible locks would prevent |
391 | this lock being placed, then | |
392 | .BR fcntl () | |
99b5ab79 | 393 | returns details about one of those locks in the |
fea681da MK |
394 | .IR l_type ", " l_whence ", " l_start ", and " l_len |
395 | fields of | |
99b5ab79 MK |
396 | .IR lock . |
397 | If the conflicting lock is a traditional (process-associated) record lock, | |
398 | then the | |
fea681da | 399 | .I l_pid |
99b5ab79 MK |
400 | field is set to the PID of the process holding that lock. |
401 | If the conflicting lock is an open file description lock, then | |
2d3e4b83 | 402 | .I l_pid |
99b5ab79 MK |
403 | is set to \-1. |
404 | Note that the returned information | |
eceaee47 | 405 | may already be out of date by the time the caller inspects it. |
fea681da MK |
406 | .P |
407 | In order to place a read lock, | |
408 | .I fd | |
409 | must be open for reading. | |
410 | In order to place a write lock, | |
411 | .I fd | |
412 | must be open for writing. | |
413 | To place both types of lock, open a file read-write. | |
76868835 MK |
414 | |
415 | When placing locks with | |
416 | .BR F_SETLKW , | |
417 | the kernel detects | |
418 | .IR deadlocks , | |
419 | whereby two or more processes have their | |
420 | lock requests mutually blocked by locks held by the other processes. | |
421 | For example, suppose process A holds a write lock on byte 100 of a file, | |
422 | and process B holds a write lock on byte 200. | |
423 | If each process then attempts to lock the byte already | |
424 | locked by the other process using | |
425 | .BR F_SETLKW , | |
426 | then, without deadlock detection, | |
427 | both processes would remain blocked indefinitely. | |
428 | When the kernel detects such deadlocks, | |
429 | it causes one of the blocking lock requests to immediately fail with the error | |
430 | .BR EDEADLK ; | |
431 | an application that encounters such an error should release | |
432 | some of its locks to allow other applications to proceed before | |
433 | attempting regain the locks that it requires. | |
434 | Circular deadlocks involving more than two processes are also detected. | |
435 | Note, however, that there are limitations to the kernel's | |
436 | deadlock-detection algorithm; see BUGS. | |
437 | ||
fea681da MK |
438 | As well as being removed by an explicit |
439 | .BR F_UNLCK , | |
1a93af04 | 440 | record locks are automatically released when the process terminates. |
fea681da MK |
441 | .P |
442 | Record locks are not inherited by a child created via | |
443 | .BR fork (2), | |
444 | but are preserved across an | |
445 | .BR execve (2). | |
446 | .P | |
447 | Because of the buffering performed by the | |
448 | .BR stdio (3) | |
449 | library, the use of record locking with routines in that package | |
450 | should be avoided; use | |
35e21ba7 | 451 | .BR read (2) |
c13182ef | 452 | and |
35e21ba7 | 453 | .BR write (2) |
fea681da | 454 | instead. |
1a93af04 MK |
455 | |
456 | The record locks described above are associated with the process | |
457 | (unlike the open file description locks described below). | |
458 | This has some unfortunate consequences: | |
459 | .IP * 3 | |
d9312ec7 | 460 | If a process closes |
1a93af04 | 461 | .I any |
d9312ec7 MK |
462 | file descriptor referring to a file, |
463 | then all of the process's locks on that file are released, | |
464 | regardless of the file descriptor(s) on which the locks were obtained. | |
1a93af04 MK |
465 | .\" (Additional file descriptors referring to the same file |
466 | .\" may have been obtained by calls to | |
467 | .\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl ().) | |
468 | This is bad: it means that a process can lose its locks on | |
469 | a file such as | |
470 | .I /etc/passwd | |
471 | or | |
472 | .I /etc/mtab | |
473 | when for some reason a library function decides to open, read, | |
474 | and close the same file. | |
475 | .IP * | |
476 | The threads in a process share locks. | |
477 | In other words, | |
478 | a multithreaded program can't use record locking to ensure | |
97e03523 | 479 | that threads don't simultaneously access the same region of a file. |
1a93af04 MK |
480 | .PP |
481 | Open file description locks solve both of these problems. | |
2d3e4b83 | 482 | .SS Open file description locks (non-POSIX) |
bfb14716 MK |
483 | Open file description locks are advisory byte-range locks whose operation is |
484 | in most respects identical to the traditional record locks described above. | |
485 | This lock type is Linux-specific, | |
38702b6c | 486 | and available since Linux 3.15. |
728aff57 MK |
487 | (There is a proposal with the Austin Group |
488 | .\" FIXME . Review progress into POSIX | |
489 | .\" http://austingroupbugs.net/view.php?id=768 | |
490 | to include this lock type in the next revision of POSIX.1.) | |
64515702 | 491 | For an explanation of open file descriptions, see |
b7a3dc84 | 492 | .BR open (2). |
99b5ab79 MK |
493 | |
494 | The principal difference between the two lock types | |
495 | is that whereas traditional record locks | |
496 | are associated with a process, | |
497 | open file description locks are associated with the | |
498 | open file description on which they are acquired, | |
499 | much like locks acquired with | |
500 | .BR flock (2). | |
501 | Consequently (and unlike traditional advisory record locks), | |
502 | open file description locks are inherited across | |
2d3e4b83 | 503 | .BR fork (2) |
99b5ab79 | 504 | (and |
2d3e4b83 JL |
505 | .BR clone (2) |
506 | with | |
99b5ab79 MK |
507 | .BR CLONE_FILES ), |
508 | and are only automatically released on the last close | |
509 | of the open file description, | |
510 | instead of being released on any close of the file. | |
2d3e4b83 | 511 | .PP |
ee662773 MK |
512 | Conflicting lock combinations |
513 | (i.e., a read lock and a write lock or two write locks) | |
514 | where one lock is an open file description lock and the other | |
515 | is a traditional record lock conflict | |
2d3e4b83 | 516 | even when they are acquired by the same process on the same file descriptor. |
97e03523 MK |
517 | |
518 | Open file description locks placed via the same open file description | |
519 | (i.e., via the same file descriptor, | |
520 | or via a duplicate of the file descriptor created by | |
521 | .BR fork (2), | |
522 | .BR dup (2), | |
bf7bc8b8 | 523 | .BR fcntl () |
97e03523 MK |
524 | .BR F_DUPFD , |
525 | and so on) are always compatible: | |
526 | if a new lock is placed on an already locked region, | |
527 | then the existing lock is converted to the new lock type. | |
528 | (Such conversions may result in splitting, shrinking, or coalescing with | |
529 | an existing lock as discussed above.) | |
530 | ||
531 | On the other hand, open file description locks may conflict with | |
532 | each other when they are acquired via different open file descriptions. | |
533 | Thus, the threads in a multithreaded program can use | |
534 | open file description locks to synchronize access to a file region | |
535 | by having each thread perform its own | |
536 | .BR open (2) | |
537 | on the file and applying locks via the resulting file descriptor. | |
2d3e4b83 | 538 | .PP |
99b5ab79 MK |
539 | As with traditional advisory locks, the third argument to |
540 | .BR fcntl (), | |
541 | .IR lock , | |
542 | is a pointer to an | |
543 | .IR flock | |
544 | structure. | |
545 | By contrast with traditional record locks, the | |
2d3e4b83 | 546 | .I l_pid |
99b5ab79 MK |
547 | field of that structure must be set to zero |
548 | when using the commands described below. | |
549 | ||
550 | The commands for working with open file description locks are analogous | |
551 | to those used with traditional locks: | |
2d3e4b83 JL |
552 | .TP |
553 | .BR F_OFD_SETLK " (\fIstruct flock *\fP)" | |
554 | Acquire an open file description lock (when | |
555 | .I l_type | |
556 | is | |
557 | .B F_RDLCK | |
558 | or | |
559 | .BR F_WRLCK ) | |
560 | or release an open file description lock (when | |
561 | .I l_type | |
562 | is | |
563 | .BR F_UNLCK ) | |
564 | on the bytes specified by the | |
565 | .IR l_whence ", " l_start ", and " l_len | |
566 | fields of | |
567 | .IR lock . | |
568 | If a conflicting lock is held by another process, | |
569 | this call returns \-1 and sets | |
570 | .I errno | |
571 | to | |
2d3e4b83 JL |
572 | .BR EAGAIN . |
573 | .TP | |
574 | .BR F_OFD_SETLKW " (\fIstruct flock *\fP)" | |
575 | As for | |
576 | .BR F_OFD_SETLK , | |
577 | but if a conflicting lock is held on the file, then wait for that lock to be | |
99b5ab79 MK |
578 | released. |
579 | If a signal is caught while waiting, then the call is interrupted | |
580 | and (after the signal handler has returned) returns immediately | |
581 | (with return value \-1 and | |
2d3e4b83 JL |
582 | .I errno |
583 | set to | |
584 | .BR EINTR ; | |
585 | see | |
586 | .BR signal (7)). | |
587 | .TP | |
588 | .BR F_OFD_GETLK " (\fIstruct flock *\fP)" | |
589 | On input to this call, | |
590 | .I lock | |
591 | describes an open file description lock we would like to place on the file. | |
592 | If the lock could be placed, | |
593 | .BR fcntl () | |
594 | does not actually place it, but returns | |
595 | .B F_UNLCK | |
596 | in the | |
597 | .I l_type | |
598 | field of | |
599 | .I lock | |
600 | and leaves the other fields of the structure unchanged. | |
99b5ab79 MK |
601 | If one or more incompatible locks would prevent this lock being placed, |
602 | then details about one of these locks are returned via | |
603 | .IR lock , | |
604 | as described above for | |
605 | .BR F_GETLK . | |
d2e429c1 MK |
606 | .PP |
607 | In the current implementation, | |
608 | .\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7 | |
609 | no deadlock detection is performed for open file description locks. | |
610 | (This contrasts with process-associated record locks, | |
611 | for which the kernel does perform deadlock detection.) | |
612 | .\" | |
73d8cece | 613 | .SS Mandatory locking |
f5cdb4b0 MK |
614 | .IR Warning : |
615 | the Linux implementation of mandatory locking is unreliable. | |
616 | See BUGS below. | |
e1124af0 MK |
617 | Because of these bugs, |
618 | and the fact that the feature is believed to be little used, | |
619 | since Linux 4.5, mandatory locking has been made an optional feature, | |
620 | governed by a configuration option | |
621 | .RB ( CONFIG_MANDATORY_FILE_LOCKING ). | |
622 | This is an initial step toward removing this feature completely. | |
f5cdb4b0 | 623 | |
9acee578 MK |
624 | By default, both traditional (process-associated) and open file description |
625 | record locks are advisory. | |
fea681da | 626 | Advisory locks are not enforced and are useful only between |
c13182ef | 627 | cooperating processes. |
00d7bbcf | 628 | |
9acee578 | 629 | Both lock types can also be mandatory. |
c13182ef | 630 | Mandatory locks are enforced for all processes. |
00d7bbcf MK |
631 | If a process tries to perform an incompatible access (e.g., |
632 | .BR read (2) | |
633 | or | |
634 | .BR write (2)) | |
635 | on a file region that has an incompatible mandatory lock, | |
636 | then the result depends upon whether the | |
637 | .B O_NONBLOCK | |
638 | flag is enabled for its open file description. | |
c13182ef | 639 | If the |
00d7bbcf MK |
640 | .B O_NONBLOCK |
641 | flag is not enabled, then | |
6799ba26 | 642 | the system call is blocked until the lock is removed |
00d7bbcf | 643 | or converted to a mode that is compatible with the access. |
c13182ef MK |
644 | If the |
645 | .B O_NONBLOCK | |
00d7bbcf | 646 | flag is enabled, then the system call fails with the error |