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