]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | '\" t |
2 | .\" Hey Emacs! This file is -*- nroff -*- source. | |
3 | .\" | |
4 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; | |
5 | .\" 1993 Michael Haardt, Ian Jackson; | |
6 | .\" 1998 Jamie Lokier; | |
7 | .\" 2002 Michael Kerrisk. | |
8 | .\" | |
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. | |
17 | .\" | |
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. | |
25 | .\" | |
26 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
27 | .\" the source, must acknowledge the copyright and authors of this work. | |
28 | .\" | |
29 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
30 | .\" Modified 1995-09-26 by Andries Brouwer <aeb@cwi.nl> | |
31 | .\" and again on 960413 and 980804 and 981223. | |
32 | .\" Modified 1998-12-11 by Jamie Lokier <jamie@imbolc.ucc.ie> | |
33 | .\" Applied correction by Christian Ehrhardt - aeb, 990712 | |
305a0578 | 34 | .\" Modified 2002-04-23 by Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da MK |
35 | .\" Added note on F_SETFL and O_DIRECT |
36 | .\" Complete rewrite + expansion of material on file locking | |
37 | .\" Incorporated description of F_NOTIFY, drawing on | |
38 | .\" Stephen Rothwell's notes in Documentation/dnotify.txt. | |
39 | .\" Added description of F_SETLEASE and F_GETLEASE | |
40 | .\" Corrected and polished, aeb, 020527. | |
305a0578 | 41 | .\" Modified 2004-03-03 by Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da MK |
42 | .\" Modified description of file leases: fixed some errors of detail |
43 | .\" Replaced the term "lease contestant" by "lease breaker" | |
305a0578 | 44 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 45 | .\" Added notes on capability requirements |
1c1e15ed | 46 | .\" Modified 2004-12-08, added O_NOATIME after note from Martin Pool |
0ff18470 | 47 | .\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb. |
2f36a807 MK |
48 | .\" 2005-04-08 Jamie Lokier <jamie@shareable.org>, mtk |
49 | .\" Described behaviour of F_SETOWN/F_SETSIG in | |
50 | .\" multi-threaded processes, and generally cleaned | |
51 | .\" up the discussion of F_SETOWN. | |
9d2a7b1f MK |
52 | .\" 2005-05-20, Johannes Nicolai <johannes.nicolai@hpi.uni-potsdam.de>, |
53 | .\" mtk: Noted F_SETOWN bug for socket file descriptor in Linux 2.4 | |
54 | .\" and earlier. Added text on permissions required to send signal. | |
fea681da | 55 | .\" |
a7a05888 | 56 | .TH FCNTL 2 2005-20-13 "Linux 2.6.14" "Linux Programmer's Manual" |
fea681da MK |
57 | .SH NAME |
58 | fcntl \- manipulate file descriptor | |
59 | .SH SYNOPSIS | |
60 | .nf | |
61 | .B #include <unistd.h> | |
62 | .B #include <fcntl.h> | |
63 | .sp | |
64 | .BI "int fcntl(int " fd ", int " cmd ); | |
65 | .BI "int fcntl(int " fd ", int " cmd ", long " arg ); | |
66 | .BI "int fcntl(int " fd ", int " cmd ", struct flock *" lock ); | |
67 | .fi | |
68 | .SH DESCRIPTION | |
cff88e99 MK |
69 | .BR fcntl () |
70 | performs one of the operations described below on the open file descriptor | |
fea681da | 71 | .IR fd . |
cff88e99 | 72 | The operation is determined by |
fea681da | 73 | .IR cmd . |
98740ac7 | 74 | .P |
cff88e99 | 75 | .SS "Duplicating a file descriptor" |
fea681da MK |
76 | .TP |
77 | .B F_DUPFD | |
78 | Find the lowest numbered available file descriptor | |
79 | greater than or equal to | |
80 | .I arg | |
81 | and make it be a copy of | |
82 | .IR fd . | |
cff88e99 | 83 | This is different from |
fea681da MK |
84 | .BR dup2 (2) |
85 | which uses exactly the descriptor specified. | |
86 | .sp | |
fea681da | 87 | On success, the new descriptor is returned. |
cff88e99 MK |
88 | .sp |
89 | See | |
90 | .BR dup (2) | |
91 | for further details. | |
98740ac7 | 92 | .P |
72da38ce | 93 | .SS "File descriptor flags" |
cff88e99 MK |
94 | The following commands manipulate the flags associated with |
95 | a file descriptor. | |
96 | Currently, only one such flag is defined: | |
97 | .BR FD_CLOEXEC , | |
98 | the close-on-exec flag. | |
99 | If the | |
fea681da | 100 | .B FD_CLOEXEC |
cff88e99 MK |
101 | bit is 0, the file descriptor will remain open across an |
102 | .BR execve (2), | |
fea681da MK |
103 | otherwise it will be closed. |
104 | .TP | |
cff88e99 MK |
105 | .B F_GETFD |
106 | Read the file descriptor flags. | |
107 | .TP | |
fea681da | 108 | .B F_SETFD |
cff88e99 | 109 | Set the file descriptor flags to the value specified by |
fea681da | 110 | .IR arg . |
98740ac7 | 111 | .P |
72da38ce | 112 | .SS "File status flags" |
08478724 MK |
113 | Each open file description has certain associated status flags, |
114 | initialized by | |
fea681da MK |
115 | .BR open (2) |
116 | .\" or | |
117 | .\" .BR creat (2), | |
118 | and possibly modified by | |
119 | .BR fcntl (2). | |
cff88e99 MK |
120 | Duplicated file descriptors |
121 | (made with | |
122 | .BR dup (), | |
123 | .BR fcntl (F_DUPFD), | |
124 | .BR fork (), | |
125 | etc.) refer to the same open file description, and thus | |
126 | share the same file status flags. | |
fea681da | 127 | .sp |
cff88e99 | 128 | The file status flags and their semantics are described in |
fea681da MK |
129 | .BR open (2). |
130 | .TP | |
131 | .B F_GETFL | |
cff88e99 | 132 | Read the file status flags. |
fea681da MK |
133 | .TP |
134 | .B F_SETFL | |
cff88e99 | 135 | Set the file status flags to the value specified by |
fea681da | 136 | .IR arg . |
cff88e99 MK |
137 | File access mode |
138 | .RB ( O_RDONLY ", " O_WRONLY ", " O_RDWR ) | |
139 | and file creation flags | |
08478724 | 140 | .RB (e.g., O_CREAT ", " O_EXCL ", " O_TRUNC ) |
cff88e99 | 141 | in |
fea681da MK |
142 | .I arg |
143 | are ignored. | |
1c1e15ed MK |
144 | On Linux this command can only change the |
145 | .BR O_APPEND , | |
146 | .BR O_ASYNC , | |
147 | .BR O_DIRECT , | |
148 | .BR O_NOATIME , | |
149 | and | |
150 | .BR O_NONBLOCK | |
151 | flags. | |
08478724 MK |
152 | .\" FIXME According to SUSv3, O_SYNC should also be modifiable via |
153 | .\" fcntl(2), but currently Linux does not permit this -- MTK, Dec 04 | |
fea681da MK |
154 | .P |
155 | .SS "Advisory locking" | |
156 | .BR F_GETLK ", " F_SETLK " and " F_SETLKW | |
157 | are used to acquire, release, and test for the existence of record | |
158 | locks (also known as file-segment or file-region locks). | |
159 | The third argument | |
160 | .I lock | |
161 | is a pointer to a structure that has at least the following fields | |
162 | (in unspecified order). | |
163 | .in +2n | |
164 | .nf | |
165 | .sp | |
166 | struct flock { | |
167 | ... | |
168 | short l_type; /* Type of lock: F_RDLCK, | |
169 | F_WRLCK, F_UNLCK */ | |
170 | short l_whence; /* How to interpret l_start: | |
171 | SEEK_SET, SEEK_CUR, SEEK_END */ | |
172 | off_t l_start; /* Starting offset for lock */ | |
173 | off_t l_len; /* Number of bytes to lock */ | |
174 | pid_t l_pid; /* PID of process blocking our lock | |
175 | (F_GETLK only) */ | |
176 | ... | |
177 | }; | |
178 | .fi | |
179 | .in -2n | |
180 | .P | |
181 | The | |
182 | .IR l_whence ", " l_start ", and " l_len | |
183 | fields of this structure specify the range of bytes we wish to lock. | |
184 | .I l_start | |
185 | is the starting offset for the lock, and is interpreted | |
186 | relative to either: | |
187 | the start of the file (if | |
188 | .I l_whence | |
189 | is | |
190 | .BR SEEK_SET ); | |
191 | the current file offset (if | |
192 | .I l_whence | |
193 | is | |
194 | .BR SEEK_CUR ); | |
195 | or the end of the file (if | |
196 | .I l_whence | |
197 | is | |
198 | .BR SEEK_END ). | |
199 | In the final two cases, | |
200 | .I l_start | |
201 | can be a negative number provided the | |
202 | offset does not lie before the start of the file. | |
203 | .I l_len | |
204 | is a non-negative integer (but see the NOTES below) specifying | |
205 | the number of bytes to be locked. | |
206 | Bytes past the end of the file may be locked, | |
207 | but not bytes before the start of the file. | |
208 | Specifying 0 for | |
209 | .I l_len | |
210 | has the special meaning: lock all bytes starting at the | |
211 | location specified by | |
212 | .IR l_whence " and " l_start | |
213 | through to the end of file, no matter how large the file grows. | |
214 | .P | |
215 | The | |
216 | .I l_type | |
217 | field can be used to place a read | |
218 | .RB ( F_RDLCK ) | |
219 | or a write | |
1c287bbf | 220 | .RB ( F_WRLCK ) |
fea681da MK |
221 | lock on a file. |
222 | Any number of processes may hold a read lock (shared lock) | |
223 | on a file region, but only one process may hold a write lock | |
224 | (exclusive lock). An exclusive lock excludes all other locks, | |
225 | both shared and exclusive. | |
226 | A single process can hold only one type of lock on a file region; | |
227 | if a new lock is applied to an already-locked region, | |
8c450534 | 228 | then the existing lock is converted to the new lock type. |
fea681da MK |
229 | (Such conversions may involve splitting, shrinking, or coalescing with |
230 | an existing lock if the byte range specified by the new lock does not | |
231 | precisely coincide with the range of the existing lock.) | |
232 | .TP | |
233 | .B F_SETLK | |
234 | Acquire a lock (when | |
235 | .I l_type | |
236 | is | |
237 | .B F_RDLCK | |
238 | or | |
239 | .BR F_WRLCK ) | |
240 | or release a lock (when | |
241 | .I l_type | |
242 | is | |
243 | .BR F_UNLCK ) | |
244 | on the bytes specified by the | |
245 | .IR l_whence ", " l_start ", and " l_len | |
246 | fields of | |
247 | .IR lock . | |
248 | If a conflicting lock is held by another process, | |
249 | this call returns \-1 and sets | |
250 | .I errno | |
251 | to | |
252 | .B EACCES | |
253 | or | |
254 | .BR EAGAIN . | |
255 | .TP | |
256 | .B F_SETLKW | |
257 | As for | |
258 | .BR F_SETLK , | |
259 | but if a conflicting lock is held on the file, then wait for that | |
260 | lock to be released. | |
261 | If a signal is caught while waiting, then the call is interrupted | |
262 | and (after the signal handler has returned) | |
263 | returns immediately (with return value \-1 and | |
264 | .I errno | |
265 | set to | |
266 | .BR EINTR ). | |
267 | .TP | |
268 | .B F_GETLK | |
269 | On input to this call, | |
270 | .I lock | |
271 | describes a lock we would like to place on the file. | |
272 | If the lock could be placed, | |
273 | .BR fcntl () | |
274 | does not actually place it, but returns | |
275 | .B F_UNLCK | |
276 | in the | |
277 | .I l_type | |
278 | field of | |
279 | .I lock | |
280 | and leaves the other fields of the structure unchanged. | |
281 | If one or more incompatible locks would prevent | |
282 | this lock being placed, then | |
283 | .BR fcntl () | |
284 | returns details about one of these locks in the | |
285 | .IR l_type ", " l_whence ", " l_start ", and " l_len | |
286 | fields of | |
287 | .I lock | |
288 | and sets | |
289 | .I l_pid | |
290 | to be the PID of the process holding that lock. | |
291 | .P | |
292 | In order to place a read lock, | |
293 | .I fd | |
294 | must be open for reading. | |
295 | In order to place a write lock, | |
296 | .I fd | |
297 | must be open for writing. | |
298 | To place both types of lock, open a file read-write. | |
299 | .P | |
300 | As well as being removed by an explicit | |
301 | .BR F_UNLCK , | |
302 | record locks are automatically released when the process | |
303 | terminates or if it closes | |
304 | .I any | |
305 | file descriptor referring to a file on which locks are held. | |
306 | .\" (Additional file descriptors referring to the same file | |
307 | .\" may have been obtained by calls to | |
308 | .\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl (2).) | |
309 | This is bad: it means that a process can lose the locks on | |
310 | a file like | |
311 | .I /etc/passwd | |
312 | or | |
313 | .I /etc/mtab | |
314 | when for some reason a library function decides to open, read | |
315 | and close it. | |
316 | .P | |
317 | Record locks are not inherited by a child created via | |
318 | .BR fork (2), | |
319 | but are preserved across an | |
320 | .BR execve (2). | |
321 | .P | |
322 | Because of the buffering performed by the | |
323 | .BR stdio (3) | |
324 | library, the use of record locking with routines in that package | |
325 | should be avoided; use | |
326 | .BR read "(2) and " write (2) | |
327 | instead. | |
328 | .P | |
329 | .SS "Mandatory locking" | |
330 | (Non-POSIX.) | |
331 | The above record locks may be either advisory or mandatory, | |
332 | and are advisory by default. | |
333 | To make use of mandatory locks, mandatory locking must be enabled | |
8c383102 | 334 | (using the "\-o mand" option to |
fea681da MK |
335 | .BR mount (8)) |
336 | for the file system containing the | |
337 | file to be locked and enabled on the file itself (by disabling | |
880f5b4b | 338 | group execute permission on the file and enabling the set-group-ID |
fea681da MK |
339 | permission bit). |
340 | ||
341 | Advisory locks are not enforced and are useful only between | |
342 | cooperating processes. Mandatory locks are enforced for all | |
343 | processes. | |
344 | .P | |
345 | .SS "Managing signals" | |
346 | .BR F_GETOWN ", " F_SETOWN ", " F_GETSIG " and " F_SETSIG | |
347 | are used to manage I/O availability signals: | |
348 | .TP | |
349 | .B F_GETOWN | |
350 | Get the process ID or process group currently receiving SIGIO | |
351 | and SIGURG signals for events on file descriptor | |
352 | .IR fd . | |
2f36a807 MK |
353 | Process IDs are returned as positive values; |
354 | process group IDs are returned as negative values (but see BUGS below). | |
fea681da MK |
355 | .TP |
356 | .B F_SETOWN | |
2f36a807 | 357 | Set the process ID or process group ID that will receive SIGIO |
fea681da MK |
358 | and SIGURG signals for events on file descriptor |
359 | .IR fd . | |
2f36a807 MK |
360 | A process ID is specified as a positive value; |
361 | a process group ID is specified as a negative value. | |
9d2a7b1f MK |
362 | Most commonly, the calling process specifies itself as the owner |
363 | (that is, | |
364 | .I arg | |
365 | is specified as | |
366 | .IR getpid ()). | |
fea681da MK |
367 | |
368 | .\" From glibc.info: | |
369 | If you set the | |
370 | .B O_ASYNC | |
371 | status flag on a file descriptor (either by providing this flag with the | |
2f36a807 MK |
372 | .BR open (2) |
373 | .\" FIXME setting O_ASYNC via open() does not seem to be effective -- MTK | |
fea681da MK |
374 | call, or by using the |
375 | .B F_SETFL | |
376 | command of | |
cff88e99 | 377 | .BR fcntl ()), |
fea681da MK |
378 | a SIGIO signal is sent whenever input or output becomes possible |
379 | on that file descriptor. | |
2f36a807 MK |
380 | .B F_SETSIG |
381 | can be used to obtain delivery of a signal other than SIGIO. | |
9d2a7b1f MK |
382 | If this permission check fails, then the signal is |
383 | silently discarded. | |
384 | ||
385 | Sending a signal to the owner process (group) specified by | |
386 | .B F_SETOWN | |
387 | is subject to the same permissions checks as are described for | |
388 | .BR kill (2), | |
389 | where the sending process is the one that employs | |
390 | .BR F_SETOWN | |
391 | (but see BUGS below). | |
fea681da | 392 | .sp |
2f36a807 MK |
393 | If the file descriptor |
394 | .I fd | |
395 | refers to a socket, | |
fea681da | 396 | .B F_SETOWN |
2f36a807 | 397 | also selects |
fea681da MK |
398 | the recipient of SIGURG signals that are delivered when out-of-band |
399 | data arrives on that socket. (SIGURG is sent in any situation where | |
400 | .BR select (2) | |
401 | would report the socket as having an "exceptional condition".) | |
2f36a807 MK |
402 | .\" The following appears to be rubbish. It doesn't seem to |
403 | .\" be true according to the kernel source, and I can write | |
404 | .\" a program that gets a terminal-generated SIGIO even though | |
405 | .\" it is not the foreground process group of the terminal. | |
406 | .\" -- MTK, 8 Apr 05 | |
407 | .\" | |
408 | .\" If the file descriptor | |
409 | .\" .I fd | |
410 | .\" refers to a terminal device, then SIGIO | |
411 | .\" signals are sent to the foreground process group of the terminal. | |
412 | ||
413 | If a non-zero value is given to | |
414 | .B F_SETSIG | |
7c088cb1 MK |
415 | in a multi-threaded process running with a threading library |
416 | that supports thread groups (e.g., NPTL), | |
cff88e99 | 417 | then a positive value given to |
2f36a807 MK |
418 | .B F_SETOWN |
419 | has a different meaning: | |
420 | .\" The relevant place in the (2.6) kernel source is the | |
421 | .\" 'switch' in fs/fcntl.c::send_sigio_to_task() -- MTK, Apr 2005 | |
422 | instead of being a process ID identifying a whole process, | |
423 | it is a thread ID identifying a specific thread within a process. | |
424 | Consequently, it may be necessary to pass | |
425 | .B F_SETOWN | |
426 | the result of | |
427 | .BR gettid () | |
428 | instead of | |
429 | .BR getpid () | |
430 | to get sensible results when | |
431 | .B F_SETSIG | |
432 | is used. | |
433 | (In current Linux threading implementations, | |
434 | a main thread's thread ID is the same as its process ID. | |
435 | This means that a single-threaded program can equally use | |
436 | .BR gettid () | |
437 | or | |
438 | .BR getpid () | |
439 | in this scenario.) | |
440 | Note, however, that the statements in this paragraph do not apply | |
441 | to the SIGURG signal generated for out-of-band data on a socket: | |
442 | this signal is always sent to either a process or a process group, | |
443 | depending on the value given to | |
444 | .BR F_SETOWN . | |
445 | .\" send_sigurg()/send_sigurg_to_task() bypasses | |
446 | .\" kill_fasync()/send_sigio()/send_sigio_to_task() | |
447 | .\" to directly call send_group_sig_info() | |
448 | .\" -- MTK, Apr 2005 (kernel 2.6.11) | |
7c088cb1 MK |
449 | Note also that Linux imposes a limit on the |
450 | number of real-time signals that may be queued to a | |
451 | process (see | |
452 | .BR getrlimit (2) | |
453 | and | |
454 | .BR signal (7)) | |
455 | and if this limit is reached, then the kernel reverts to | |
456 | delivering SIGIO, and this signal is delivered to the entire | |
7502db97 | 457 | process rather than to a specific thread. |
7c088cb1 | 458 | .\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05 |
fea681da MK |
459 | .TP |
460 | .B F_GETSIG | |
461 | Get the signal sent when input or output becomes possible. A value of | |
462 | zero means SIGIO is sent. Any other value (including SIGIO) is the | |
463 | signal sent instead, and in this case additional info is available to | |
464 | the signal handler if installed with SA_SIGINFO. | |
465 | .TP | |
466 | .B F_SETSIG | |
467 | Sets the signal sent when input or output becomes possible. A value of | |
468 | zero means to send the default SIGIO signal. Any other value (including | |
469 | SIGIO) is the signal to send instead, and in this case additional info | |
470 | is available to the signal handler if installed with SA_SIGINFO. | |
471 | .sp | |
2f36a807 MK |
472 | Additionally, passing a non-zero value to |
473 | .B F_SETSIG | |
474 | changes the signal recipient from a whole process to a specific thread | |
475 | within a process. | |
704a18f0 | 476 | See the description of |
2f36a807 MK |
477 | .B F_SETOWN |
478 | for more details. | |
479 | .sp | |
480 | By using | |
481 | .B F_SETSIG | |
482 | with a non-zero value, and setting SA_SIGINFO for the | |
fea681da MK |
483 | signal handler (see |
484 | .BR sigaction (2)), | |
485 | extra information about I/O events is passed to | |
486 | the handler in a | |
487 | .I siginfo_t | |
488 | structure. | |
489 | If the | |
490 | .I si_code | |
491 | field indicates the source is SI_SIGIO, the | |
492 | .I si_fd | |
493 | field gives the file descriptor associated with the event. Otherwise, | |
494 | there is no indication which file descriptors are pending, and you | |
495 | should use the usual mechanisms | |
496 | .RB ( select (2), | |
497 | .BR poll (2), | |
498 | .BR read (2) | |
499 | with | |
500 | .B O_NONBLOCK | |
501 | set etc.) to determine which file descriptors are available for I/O. | |
502 | .sp | |
503 | By selecting a POSIX.1b real time signal (value >= SIGRTMIN), multiple | |
504 | I/O events may be queued using the same signal numbers. (Queuing is | |
505 | dependent on available memory). Extra information is available | |
506 | if SA_SIGINFO is set for the signal handler, as above. | |
507 | .PP | |
508 | Using these mechanisms, a program can implement fully asynchronous I/O | |
509 | without using | |
510 | .BR select (2) | |
511 | or | |
512 | .BR poll (2) | |
513 | most of the time. | |
514 | .PP | |
515 | The use of | |
516 | .BR O_ASYNC , | |
517 | .BR F_GETOWN , | |
518 | .B F_SETOWN | |
519 | is specific to BSD and Linux. | |
520 | .B F_GETSIG | |
521 | and | |
522 | .B F_SETSIG | |
523 | are Linux-specific. POSIX has asynchronous I/O and the | |
524 | .I aio_sigevent | |
525 | structure to achieve similar things; these are also available | |
526 | in Linux as part of the GNU C Library (Glibc). | |
527 | .P | |
528 | .SS Leases | |
529 | .B F_SETLEASE | |
530 | and | |
531 | .B F_GETLEASE | |
532 | (Linux 2.4 onwards) are used (respectively) to establish and | |
533 | retrieve the current setting of the calling process's lease on | |
534 | the file referred to by | |
535 | .IR fd . | |
536 | A file lease provides a mechanism whereby the process holding | |
537 | the lease (the "lease holder") is notified (via delivery of a signal) | |
a7a05888 | 538 | when a process (the "lease breaker") tries to |
fea681da MK |
539 | .BR open (2) |
540 | or | |
541 | .BR truncate (2) | |
542 | that file. | |
543 | .TP | |
544 | .B F_SETLEASE | |
545 | Set or remove a file lease according to which of the following | |
546 | values is specified in the integer | |
547 | .IR arg : | |
548 | ||
549 | .RS | |
550 | .TP | |
551 | .B F_RDLCK | |
552 | Take out a read lease. | |
1a6d974a | 553 | This will cause the calling process to be notified when |
a7a05888 | 554 | the file is opened for writing or is truncated. |
1a6d974a MK |
555 | .\" The following became true in kernel 2.6.10: |
556 | .\" See the man-pages-2.09 Changelog for further info. | |
557 | A read lease can only be placed on a file descriptor that | |
558 | is opened read-only. | |
fea681da MK |
559 | .TP |
560 | .B F_WRLCK | |
561 | Take out a write lease. | |
a7a05888 MK |
562 | This will cause the caller to be notified when |
563 | the file is opened for reading or writing or is truncated. | |
fea681da MK |
564 | A write lease may be placed on a file only if no other process |
565 | currently has the file open. | |
566 | .TP | |
567 | .B F_UNLCK | |
568 | Remove our lease from the file. | |
569 | .RE | |
570 | .P | |
571 | A process may hold only one type of lease on a file. | |
572 | .P | |
573 | Leases may only be taken out on regular files. | |
574 | An unprivileged process may only take out a lease on a file whose | |
575 | UID matches the file system UID of the process. | |
576 | A process with the | |
577 | .B CAP_LEASE | |
578 | capability may take out leases on arbitrary files. | |
579 | .TP | |
580 | .B F_GETLEASE | |
581 | Indicates what type of lease we hold on the file | |
582 | referred to by | |
583 | .I fd | |
584 | by returning either | |
585 | .BR F_RDLCK ", " F_WRLCK ", or " F_UNLCK, | |
586 | indicating, respectively, that the calling process holds a | |
587 | read, a write, or no lease on the file. | |
588 | (The third argument to | |
589 | .BR fcntl () | |
590 | is omitted.) | |
591 | .PP | |
592 | When a process (the "lease breaker") performs an | |
593 | .BR open () | |
594 | or | |
595 | .BR truncate () | |
596 | that conflicts with a lease established via | |
597 | .BR F_SETLEASE , | |
598 | the system call is blocked by the kernel, unless the | |
599 | .B O_NONBLOCK | |
600 | flag was specified to | |
601 | .BR open (), | |
602 | in which case the system call will return with the error | |
603 | .BR EWOULDBLOCK . | |
604 | The kernel notifies the lease holder by sending it a signal | |
605 | (SIGIO by default). | |
606 | The lease holder should respond to receipt of this signal by doing | |
607 | whatever cleanup is required in preparation for the file to be | |
608 | accessed by another process (e.g., flushing cached buffers) and | |
609 | then either remove or downgrade its lease. | |
610 | A lease is removed by performing an | |
611 | .B F_SETLEASE | |
612 | command specifying | |
613 | .I arg | |
614 | as | |
615 | .BR F_UNLCK . | |
616 | If we currently hold a write lease on the file, | |
617 | and the lease breaker is opening the file for reading, | |
618 | then it is sufficient to downgrade the lease to a read lease. | |
619 | This is done by performing an | |
620 | .B F_SETLEASE | |
621 | command specifying | |
622 | .I arg | |
623 | as | |
624 | .BR F_RDLCK . | |
625 | ||
626 | If the lease holder fails to downgrade or remove the lease within | |
627 | the number of seconds specified in | |
628 | .I /proc/sys/fs/lease-break-time | |
629 | then the kernel forcibly removes or downgrades the lease holder's lease. | |
630 | ||
631 | Once the lease has been voluntarily or forcibly removed or downgraded, | |
632 | and assuming the lease breaker has not unblocked its system call, | |
633 | the kernel permits the lease breaker's system call to proceed. | |
634 | ||
635 | The default signal used to notify the lease holder is SIGIO, | |
636 | but this can be changed using the | |
637 | .B F_SETSIG | |
638 | command to | |
a7a05888 | 639 | .BR fcntl (). |
fea681da MK |
640 | If a |
641 | .B F_SETSIG | |
642 | command is performed (even one specifying SIGIO), and the signal | |
643 | handler is established using SA_SIGINFO, then the handler will | |
644 | receive a | |
645 | .I siginfo_t | |
704a18f0 | 646 | structure as its second argument, and the |
fea681da MK |
647 | .I si_fd |
648 | field of this argument will hold the descriptor of the leased file | |
649 | that has been accessed by another process. | |
650 | (This is useful if the caller holds leases against multiple files). | |
98740ac7 | 651 | .P |
fea681da | 652 | .SS "File and directory change notification" |
18640739 MK |
653 | .\" FIXME -- Eventually we may want to add a note about inotify |
654 | .\" here (MTK, Jun 05) | |
fea681da MK |
655 | .TP |
656 | .B F_NOTIFY | |
657 | (Linux 2.4 onwards) | |
658 | Provide notification when the directory referred to by | |
659 | .I fd | |
660 | or any of the files that it contains is changed. | |
661 | The events to be notified are specified in | |
662 | .IR arg , | |
663 | which is a bit mask specified by ORing together zero or more of | |
664 | the following bits: | |
665 | ||
666 | .TS | |
667 | l l | |
668 | ---- | |
669 | lB l. | |
670 | Bit Description (event in directory) | |
671 | DN_ACCESS A file was accessed (read, pread, readv) | |
672 | DN_MODIFY A file was modified (write, pwrite, | |
673 | writev, truncate, ftruncate) | |
674 | DN_CREATE A file was created (open, creat, mknod, | |
675 | mkdir, link, symlink, rename) | |
676 | DN_DELETE A file was unlinked (unlink, rename to | |
677 | another directory, rmdir) | |
678 | DN_RENAME A file was renamed within this | |
679 | directory (rename) | |
680 | DN_ATTRIB The attributes of a file were changed | |
681 | (chown, chmod, utime[s]) | |
682 | .TE | |
683 | .sp | |
684 | (In order to obtain these definitions, the _GNU_SOURCE macro must be | |
685 | defined before including <fcntl.h>.) | |
686 | .sp | |
687 | Directory notifications are normally "one-shot", and the application | |
688 | must re-register to receive further notifications. | |
689 | Alternatively, if | |
690 | .B DN_MULTISHOT | |
691 | is included in | |
692 | .IR arg , | |
693 | then notification will remain in effect until explicitly removed. | |
694 | ||
695 | .\" The following does seem a poor API-design choice... | |
696 | A series of | |
697 | .B F_NOTIFY | |
698 | requests is cumulative, with the events in | |
699 | .I arg | |
700 | being added to the set already monitored. | |
701 | To disable notification of all events, make an | |
702 | .B F_NOTIFY | |
703 | call specifying | |
704 | .I arg | |
705 | as 0. | |
706 | .sp | |
707 | Notification occurs via delivery of a signal. | |
708 | The default signal is SIGIO, but this can be changed using the | |
709 | .B F_SETSIG | |
710 | command to | |
711 | .BR fcntl (). | |
712 | In the latter case, the signal handler receives a | |
713 | .I siginfo_t | |
714 | structure as its second argument (if the handler was | |
715 | established using SA_SIGINFO) and the | |
716 | .I si_fd | |
717 | field of this structure contains the file descriptor which | |
718 | generated the notification (useful when establishing notification | |
719 | on multiple directories). | |
720 | .sp | |
721 | Especially when using | |
722 | .BR DN_MULTISHOT , | |
704a18f0 | 723 | a POSIX.1b real time signal should be used for notification, |
fea681da MK |
724 | so that multiple notifications can be queued. |
725 | .SH "RETURN VALUE" | |
726 | For a successful call, the return value depends on the operation: | |
727 | .TP 0.9i | |
728 | .B F_DUPFD | |
729 | The new descriptor. | |
730 | .TP | |
731 | .B F_GETFD | |
72da38ce | 732 | Value of flags. |
fea681da MK |
733 | .TP |
734 | .B F_GETFL | |
735 | Value of flags. | |
736 | .TP | |
737 | .B F_GETOWN | |
738 | Value of descriptor owner. | |
739 | .TP | |
740 | .B F_GETSIG | |
741 | Value of signal sent when read or write becomes possible, or zero | |
742 | for traditional SIGIO behaviour. | |
743 | .TP | |
744 | All other commands | |
745 | Zero. | |
746 | .PP | |
747 | On error, \-1 is returned, and | |
748 | .I errno | |
749 | is set appropriately. | |
750 | .SH ERRORS | |
751 | .TP | |
752 | .BR EACCES " or " EAGAIN | |
753 | Operation is prohibited by locks held by other processes. | |
754 | Or, operation is prohibited because the file has been memory-mapped by | |
755 | another process. | |
756 | .TP | |
757 | .B EBADF | |
758 | .I fd | |
759 | is not an open file descriptor, or the command was | |
760 | .B F_SETLK | |
761 | or | |
762 | .B F_SETLKW | |
763 | and the file descriptor open mode doesn't match with the | |
764 | type of lock requested. | |
765 | .TP | |
766 | .B EDEADLK | |
767 | It was detected that the specified | |
768 | .B F_SETLKW | |
769 | command would cause a deadlock. | |
770 | .TP | |
771 | .B EFAULT | |
772 | .I lock | |
773 | is outside your accessible address space. | |
774 | .TP | |
775 | .B EINTR | |
776 | For | |
777 | .BR F_SETLKW , | |
778 | the command was interrupted by a signal. | |
779 | For | |
780 | .BR F_GETLK " and " F_SETLK , | |
781 | the command was interrupted by a signal before the lock was checked or | |
782 | acquired. Most likely when locking a remote file (e.g. locking over | |
783 | NFS), but can sometimes happen locally. | |
784 | .TP | |
785 | .B EINVAL | |
786 | For | |
787 | .BR F_DUPFD , | |
788 | .I arg | |
789 | is negative or is greater than the maximum allowable value. For | |
790 | .BR F_SETSIG , | |
791 | .I arg | |
792 | is not an allowable signal number. | |
793 | .TP | |
794 | .B EMFILE | |
795 | For | |
796 | .BR F_DUPFD , | |
797 | the process already has the maximum number of file descriptors open. | |
798 | .TP | |
799 | .B ENOLCK | |
800 | Too many segment locks open, lock table is full, or a remote locking | |
801 | protocol failed (e.g. locking over NFS). | |
802 | .TP | |
803 | .B EPERM | |
804 | Attempted to clear the | |
805 | .B O_APPEND | |
806 | flag on a file that has the append-only attribute set. | |
807 | .SH NOTES | |
808 | The errors returned by | |
cff88e99 | 809 | .BR dup2 () |
fea681da MK |
810 | are different from those returned by |
811 | .BR F_DUPFD . | |
812 | ||
813 | Since kernel 2.0, there is no interaction between the types of lock | |
814 | placed by | |
815 | .BR flock (2) | |
816 | and | |
817 | .BR fcntl (2). | |
818 | ||
819 | POSIX 1003.1-2001 allows | |
820 | .I l_len | |
821 | to be negative. (And if it is, the interval described by the lock | |
822 | covers bytes | |
823 | .IR l_start + l_len | |
824 | up to and including | |
8729177b | 825 | .IR l_start \-1.) |
fea681da MK |
826 | This is supported by Linux since Linux 2.4.21 and 2.5.49. |
827 | ||
828 | Several systems have more fields in | |
829 | .I "struct flock" | |
830 | such as e.g. | |
831 | .IR l_sysid . | |
832 | Clearly, | |
833 | .I l_pid | |
834 | alone is not going to be very useful if the process holding the lock | |
835 | may live on a different machine. | |
7c3b0e95 | 836 | .SH BUGS |
8505c1f1 MK |
837 | A limitation of the Linux system call conventions on some |
838 | architectures (notably x86) means that if a (negative) | |
839 | process group ID to be returned by | |
7c3b0e95 | 840 | .B F_GETOWN |
8729177b | 841 | falls in the range \-1 to \-4095, then the return value is wrongly |
7c3b0e95 | 842 | interpreted by glibc as an error in the system call; |
8505c1f1 | 843 | .\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h |
7c3b0e95 MK |
844 | that is, the return value of |
845 | .BR fcntl () | |
846 | will be \-1, and | |
847 | .I errno | |
848 | will contain the (positive) process group ID. | |
8505c1f1 MK |
849 | .\" FIXME Dec 04: some limited testing on alpha and ia64 seems to |
850 | .\" indicate that ANY negative PGID value will cause F_GETOWN | |
704a18f0 | 851 | .\" to misinterpret the return as an error. Some other architectures |
8505c1f1 | 852 | .\" seem to have the same range check as x86. -- MTK |
9d2a7b1f MK |
853 | |
854 | In Linux 2.4 and earlier, there is bug that can occur | |
855 | when an unprivileged process uses | |
856 | .B F_SETOWN | |
857 | to specify the owner | |
858 | of a socket file descriptor | |
859 | as a process (group) other than the caller. | |
860 | In this case, | |
861 | .BR fcntl () | |
862 | can return \-1 with | |
863 | .I errno | |
864 | set to | |
865 | .BR EPERM , | |
866 | even when the owner process (group) is one that the caller | |
867 | has permission to send signals to. | |
868 | Despite this error return, the file descriptor owner is set, | |
869 | and signals will be sent to the owner. | |
fea681da | 870 | .SH "CONFORMING TO" |
b14d4aa5 | 871 | SVr4, SVID, POSIX, X/OPEN, 4.3BSD. Only the operations F_DUPFD, |
7c088cb1 MK |
872 | F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK, F_SETLKW, |
873 | F_GETOWN, and F_SETOWN are specified in POSIX.1. | |
874 | F_GETSIG, F_SETSIG, F_NOTIFY, F_GETLEASE, and F_SETLEASE | |
fea681da MK |
875 | are Linux specific. |
876 | (Define the _GNU_SOURCE macro before including <fcntl.h> to | |
877 | obtain these definitions.) | |
878 | The flags legal for F_GETFL/F_SETFL are those supported by | |
879 | .BR open (2) | |
880 | and vary between these systems; O_APPEND, O_NONBLOCK, O_RDONLY, | |
881 | and O_RDWR are specified in POSIX.1. SVr4 supports several other | |
882 | options and flags not documented here. | |
883 | .PP | |
884 | SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. | |
885 | .SH "SEE ALSO" | |
886 | .BR dup2 (2), | |
887 | .BR flock (2), | |
888 | .BR open (2), | |
889 | .BR socket (2), | |
890 | .BR lockf (3), | |
891 | .BR capabilities (7) | |
892 | .P | |
893 | See also locks.txt, mandatory.txt, and dnotify.txt in | |
894 | /usr/src/linux/Documentation. |