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