kernel: Add three new commands to fctnl
[dragonfly.git] / lib / libc / sys / fcntl.2
1 .\" Copyright (c) 1983, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\"    may be used to endorse or promote products derived from this software
14 .\"    without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\"     @(#)fcntl.2     8.2 (Berkeley) 1/12/94
29 .\" $FreeBSD: src/lib/libc/sys/fcntl.2,v 1.16.2.13 2002/07/22 15:15:16 bde Exp $
30 .\"
31 .Dd June 12, 2013
32 .Dt FCNTL 2
33 .Os
34 .Sh NAME
35 .Nm fcntl
36 .Nd file control
37 .Sh LIBRARY
38 .Lb libc
39 .Sh SYNOPSIS
40 .In fcntl.h
41 .Ft int
42 .Fn fcntl "int fd" "int cmd" "..."
43 .Sh DESCRIPTION
44 The
45 .Fn fcntl
46 system call provides for control over descriptors.
47 The argument
48 .Fa fd
49 is a descriptor to be operated on by
50 .Fa cmd
51 as described below.
52 Depending on the value of
53 .Fa cmd ,
54 .Fn fcntl
55 can take an additional third argument
56 .Fa "int arg" .
57 .Bl -tag -width F_DUP2FD_CLOEXEC
58 .It Dv F_DUPFD
59 Return a new descriptor as follows:
60 .Pp
61 .Bl -bullet -compact -offset 4n
62 .It
63 Lowest numbered available descriptor greater than or equal to
64 .Fa arg .
65 .It
66 Same object references as the original descriptor.
67 .It
68 New descriptor shares the same file offset if the object
69 was a file.
70 .It
71 Same access mode (read, write or read/write).
72 .It
73 Same file status flags (i.e., both file descriptors
74 share the same file status flags).
75 .It
76 The close-on-exec flag
77 .Dv FD_CLOEXEC
78 associated with the new file descriptor is cleared, so the file descriptor is
79 to remain open across
80 .Xr execve 2
81 system calls.
82 .El
83 .It Dv F_DUPFD_CLOEXEC
84 Like
85 .Dv F_DUPFD ,
86 but the
87 .Dv FD_CLOEXEC
88 flag associated with the new file descriptor is set, so the file descriptor
89 is closed when
90 .Xr execve 2
91 system call executes.
92 .It Dv F_DUP2FD
93 It is functionally equivalent to
94 .Bd -literal -offset indent
95 dup2(fd, arg)
96 .Ed
97 .It Dv F_DUP2FD_CLOEXEC
98 Like
99 .Dv F_DUP2FD ,
100 but the
101 .Dv FD_CLOEXEC
102 flag associated with the new file descriptor is set.
103 .Pp
104 The
105 .Dv F_DUP2FD
106 and
107 .Dv F_DUP2FD_CLOEXEC
108 constants are not portable, so they should not be used if
109 portability is needed.
110 Use
111 .Fn dup2
112 instead of
113 .Dv F_DUP2FD .
114 .It Dv F_GETFD
115 Get the close-on-exec flag associated with the file descriptor
116 .Fa fd
117 as
118 .Dv FD_CLOEXEC .
119 If the returned value ANDed with
120 .Dv FD_CLOEXEC
121 is 0,
122 the file will remain open across
123 .Fn exec ,
124 otherwise the file will be closed upon execution of
125 .Fn exec
126 .Fa ( arg
127 is ignored).
128 .It Dv F_SETFD
129 Set the close-on-exec flag associated with
130 .Fa fd
131 to
132 .Fa arg ,
133 where
134 .Fa arg
135 is either 0 or
136 .Dv FD_CLOEXEC ,
137 as described above.
138 .It Dv F_GETFL
139 Get descriptor status flags, as described below
140 .Fa ( arg
141 is ignored).
142 .It Dv F_SETFL
143 Set descriptor status flags to
144 .Fa arg .
145 .It Dv F_GETOWN
146 Get the process ID or process group
147 currently receiving
148 .Dv SIGIO
149 and
150 .Dv SIGURG
151 signals; process groups are returned
152 as negative values
153 .Fa ( arg
154 is ignored).
155 .It Dv F_SETOWN
156 Set the process or process group
157 to receive
158 .Dv SIGIO
159 and
160 .Dv SIGURG
161 signals;
162 process groups are specified by supplying
163 .Fa arg
164 as negative, otherwise
165 .Fa arg
166 is interpreted as a process ID.
167 .El
168 .Pp
169 The flags for the
170 .Dv F_GETFL
171 and
172 .Dv F_SETFL
173 flags are as follows:
174 .Bl -tag -width O_NONBLOCKX
175 .It Dv O_NONBLOCK
176 Non-blocking I/O; if no data is available to a
177 .Xr read 2
178 system call, or if a
179 .Xr write 2
180 operation would block,
181 the read or write call returns -1 with the error
182 .Er EAGAIN .
183 .It Dv O_APPEND
184 Force each write to append at the end of file;
185 corresponds to the
186 .Dv O_APPEND
187 flag of
188 .Xr open 2 .
189 .It Dv O_DIRECT
190 Minimize or eliminate the cache effects of reading and writing.
191 The system
192 will attempt to avoid caching the data you read or write.
193 If it cannot
194 avoid caching the data, it will minimize the impact the data has on the cache.
195 Use of this flag can drastically reduce performance if not used with care.
196 .It Dv O_ASYNC
197 Enable the
198 .Dv SIGIO
199 signal to be sent to the process group
200 when I/O is possible, e.g.,
201 upon availability of data to be read.
202 .El
203 .Pp
204 Several commands are available for doing advisory file locking;
205 they all operate on the following structure:
206 .Bd -literal
207 struct flock {
208         off_t   l_start;        /* starting offset */
209         off_t   l_len;          /* len = 0 means until end of file */
210         pid_t   l_pid;          /* lock owner */
211         short   l_type;         /* lock type: read/write, etc. */
212         short   l_whence;       /* type of l_start */
213 };
214 .Ed
215 The commands available for advisory record locking are as follows:
216 .Bl -tag -width F_SETLKWX
217 .It Dv F_GETLK
218 Get the first lock that blocks the lock description pointed to by the
219 third argument,
220 .Fa arg ,
221 taken as a pointer to a
222 .Fa "struct flock"
223 (see above).
224 The information retrieved overwrites the information passed to
225 .Fn fcntl
226 in the
227 .Fa flock
228 structure.
229 If no lock is found that would prevent this lock from being created,
230 the structure is left unchanged by this system call except for the
231 lock type which is set to
232 .Dv F_UNLCK .
233 .It Dv F_SETLK
234 Set or clear a file segment lock according to the lock description
235 pointed to by the third argument,
236 .Fa arg ,
237 taken as a pointer to a
238 .Fa "struct flock"
239 (see above).
240 .Dv F_SETLK
241 is used to establish shared (or read) locks
242 .Pq Dv F_RDLCK
243 or exclusive (or write) locks,
244 .Pq Dv F_WRLCK ,
245 as well as remove either type of lock
246 .Pq Dv F_UNLCK .
247 If a shared or exclusive lock cannot be set,
248 .Fn fcntl
249 returns immediately with
250 .Er EAGAIN .
251 .It Dv F_SETLKW
252 This command is the same as
253 .Dv F_SETLK
254 except that if a shared or exclusive lock is blocked by other locks,
255 the process waits until the request can be satisfied.
256 If a signal that is to be caught is received while
257 .Fn fcntl
258 is waiting for a region, the
259 .Fn fcntl
260 will be interrupted if the signal handler has not specified the
261 .Dv SA_RESTART
262 (see
263 .Xr sigaction 2 ) .
264 .El
265 .Pp
266 When a shared lock has been set on a segment of a file,
267 other processes can set shared locks on that segment
268 or a portion of it.
269 A shared lock prevents any other process from setting an exclusive
270 lock on any portion of the protected area.
271 A request for a shared lock fails if the file descriptor was not
272 opened with read access.
273 .Pp
274 An exclusive lock prevents any other process from setting a shared lock or
275 an exclusive lock on any portion of the protected area.
276 A request for an exclusive lock fails if the file was not
277 opened with write access.
278 .Pp
279 The value of
280 .Fa l_whence
281 is
282 .Dv SEEK_SET ,
283 .Dv SEEK_CUR ,
284 or
285 .Dv SEEK_END
286 to indicate that the relative offset,
287 .Fa l_start
288 bytes, will be measured from the start of the file,
289 current position, or end of the file, respectively.
290 The value of
291 .Fa l_len
292 is the number of consecutive bytes to be locked.
293 If
294 .Fa l_len
295 is negative, the result is undefined.
296 The
297 .Fa l_pid
298 field is only used with
299 .Dv F_GETLK
300 to return the process ID of the process holding a blocking lock.
301 After a successful
302 .Dv F_GETLK
303 request, the value of
304 .Fa l_whence
305 is
306 .Dv SEEK_SET .
307 .Pp
308 Locks may start and extend beyond the current end of a file,
309 but may not start or extend before the beginning of the file.
310 A lock is set to extend to the largest possible value of the
311 file offset for that file if
312 .Fa l_len
313 is set to zero.
314 If
315 .Fa l_whence
316 and
317 .Fa l_start
318 point to the beginning of the file, and
319 .Fa l_len
320 is zero, the entire file is locked.
321 If an application wishes only to do entire file locking, the
322 .Xr flock 2
323 system call is much more efficient.
324 .Pp
325 There is at most one type of lock set for each byte in the file.
326 Before a successful return from an
327 .Dv F_SETLK
328 or an
329 .Dv F_SETLKW
330 request when the calling process has previously existing locks
331 on bytes in the region specified by the request,
332 the previous lock type for each byte in the specified
333 region is replaced by the new lock type.
334 As specified above under the descriptions
335 of shared locks and exclusive locks, an
336 .Dv F_SETLK
337 or an
338 .Dv F_SETLKW
339 request fails or blocks respectively when another process has existing
340 locks on bytes in the specified region and the type of any of those
341 locks conflicts with the type specified in the request.
342 .Pp
343 This interface follows the completely stupid semantics of System V and
344 .St -p1003.1-88
345 that require that all locks associated with a file for a given process are
346 removed when
347 .Em any
348 file descriptor for that file is closed by that process.
349 This semantic means that applications must be aware of any files that
350 a subroutine library may access.
351 For example if an application for updating the password file locks the
352 password file database while making the update, and then calls
353 .Xr getpwnam 3
354 to retrieve a record,
355 the lock will be lost because
356 .Xr getpwnam 3
357 opens, reads, and closes the password database.
358 The database close will release all locks that the process has
359 associated with the database, even if the library routine never
360 requested a lock on the database.
361 Another minor semantic problem with this interface is that
362 locks are not inherited by a child process created using the
363 .Xr fork 2
364 system call.
365 The
366 .Xr flock 2
367 interface has much more rational last close semantics and
368 allows locks to be inherited by child processes.
369 The
370 .Xr flock 2
371 system call is recommended for applications that want to ensure the integrity
372 of their locks when using library routines or wish to pass locks
373 to their children.
374 .Pp
375 The
376 .Fn fcntl ,
377 .Xr flock 2 ,
378 and
379 .Xr lockf 3
380 locks are compatible.
381 Processes using different locking interfaces can cooperate
382 over the same file safely.
383 However, only one of such interfaces should be used within
384 the same process.
385 If a file is locked by a process through
386 .Xr flock 2 ,
387 any record within the file will be seen as locked
388 from the viewpoint of another process using
389 .Fn fcntl
390 or
391 .Xr lockf 3 ,
392 and vice versa.
393 Note that
394 .Fn fcntl F_GETLK
395 returns \-1 in
396 .Fa l_pid
397 if the process holding a blocking lock previously locked the
398 file descriptor by
399 .Xr flock 2 .
400 .Pp
401 All locks associated with a file for a given process are
402 removed when the process terminates.
403 .Pp
404 All locks obtained before a call to
405 .Xr execve 2
406 remain in effect until the new program releases them.
407 If the new program does not know about the locks, they will not be
408 released until the program exits.
409 .Pp
410 A potential for deadlock occurs if a process controlling a locked region
411 is put to sleep by attempting to lock the locked region of another process.
412 This implementation detects that sleeping until a locked region is unlocked
413 would cause a deadlock and fails with an
414 .Er EDEADLK
415 error.
416 .Sh RETURN VALUES
417 Upon successful completion, the value returned depends on
418 .Fa cmd
419 as follows:
420 .Bl -tag -width F_GETOWNX -offset indent
421 .It Dv F_DUPFD
422 A new file descriptor.
423 .It Dv F_DUP2FD
424 A file descriptor equal to
425 .Fa arg .
426 .It Dv F_GETFD
427 Value of flag (only the low-order bit is defined).
428 .It Dv F_GETFL
429 Value of flags.
430 .It Dv F_GETOWN
431 Value of file descriptor owner.
432 .It other
433 Value other than -1.
434 .El
435 .Pp
436 Otherwise, a value of -1 is returned and
437 .Va errno
438 is set to indicate the error.
439 .Sh ERRORS
440 The
441 .Fn fcntl
442 system call will fail if:
443 .Bl -tag -width Er
444 .It Bq Er EAGAIN
445 The argument
446 .Fa cmd
447 is
448 .Dv F_SETLK ,
449 the type of lock
450 .Pq Fa l_type
451 is a shared lock
452 .Pq Dv F_RDLCK
453 or exclusive lock
454 .Pq Dv F_WRLCK ,
455 and the segment of a file to be locked is already
456 exclusive-locked by another process;
457 or the type is an exclusive lock and some portion of the
458 segment of a file to be locked is already shared-locked or
459 exclusive-locked by another process.
460 .It Bq Er EBADF
461 The
462 .Fa fd
463 argument
464 is not a valid open file descriptor.
465 .Pp
466 The argument
467 .Fa cmd
468 is
469 .Dv F_DUP2FD ,
470 and
471 .Fa arg
472 is not a valid file descriptor.
473 .Pp
474 The argument
475 .Fa cmd
476 is
477 .Dv F_SETLK
478 or
479 .Dv F_SETLKW ,
480 the type of lock
481 .Pq Fa l_type
482 is a shared lock
483 .Pq Dv F_RDLCK ,
484 and
485 .Fa fd
486 is not a valid file descriptor open for reading.
487 .Pp
488 The argument
489 .Fa cmd
490 is
491 .Dv F_SETLK
492 or
493 .Dv F_SETLKW ,
494 the type of lock
495 .Pq Fa l_type
496 is an exclusive lock
497 .Pq Dv F_WRLCK ,
498 and
499 .Fa fd
500 is not a valid file descriptor open for writing.
501 .It Bq Er EDEADLK
502 The argument
503 .Fa cmd
504 is
505 .Dv F_SETLKW ,
506 and a deadlock condition was detected.
507 .It Bq Er EINTR
508 The argument
509 .Fa cmd
510 is
511 .Dv F_SETLKW ,
512 and the system call was interrupted by a signal.
513 .It Bq Er EINVAL
514 The
515 .Fa cmd
516 argument
517 is
518 .Dv F_DUPFD
519 and
520 .Fa arg
521 is negative or greater than the maximum allowable number
522 (see
523 .Xr getdtablesize 2 ) .
524 .Pp
525 The argument
526 .Fa cmd
527 is
528 .Dv F_GETLK ,
529 .Dv F_SETLK
530 or
531 .Dv F_SETLKW
532 and the data to which
533 .Fa arg
534 points is not valid.
535 .It Bq Er EMFILE
536 The argument
537 .Fa cmd
538 is
539 .Dv F_DUPFD
540 and the maximum number of file descriptors permitted for the
541 process are already in use,
542 or no file descriptors greater than or equal to
543 .Fa arg
544 are available.
545 .It Bq Er ENOLCK
546 The argument
547 .Fa cmd
548 is
549 .Dv F_SETLK
550 or
551 .Dv F_SETLKW ,
552 and satisfying the lock or unlock request would result in the
553 number of locked regions in the system exceeding a system-imposed limit.
554 .It Bq Er EPERM
555 The
556 .Fa cmd
557 argument
558 is
559 .Dv F_SETOWN
560 and
561 the process ID or process group given as an argument is in a
562 different session than the caller.
563 .It Bq Er ESRCH
564 The
565 .Fa cmd
566 argument
567 is
568 .Dv F_SETOWN
569 and
570 the process ID given as argument is not in use.
571 .El
572 .Pp
573 In addition, if
574 .Fa fd
575 refers to a descriptor open on a terminal device (as opposed to a
576 descriptor open on a socket), a
577 .Fa cmd
578 of
579 .Dv F_SETOWN
580 can fail for the same reasons as in
581 .Xr tcsetpgrp 3 ,
582 and a
583 .Fa cmd
584 of
585 .Dv F_GETOWN
586 for the reasons as stated in
587 .Xr tcgetpgrp 3 .
588 .Sh SEE ALSO
589 .Xr close 2 ,
590 .Xr dup2 2 ,
591 .Xr execve 2 ,
592 .Xr flock 2 ,
593 .Xr getdtablesize 2 ,
594 .Xr open 2 ,
595 .Xr sigaction 2 ,
596 .Xr lockf 3 ,
597 .Xr tcgetpgrp 3 ,
598 .Xr tcsetpgrp 3
599 .Sh STANDARDS
600 The
601 .Dv F_DUP2FD
602 constant is non portable.
603 It is provided for compatibility with AIX and Solaris.
604 .Sh HISTORY
605 The
606 .Fn fcntl
607 system call appeared in
608 .Bx 4.2 .
609 .Pp
610 The
611 .Dv F_DUP_CLOEXEC ,
612 .Dv F_DUP2FD
613 and
614 .Dv F_DUP2FD_CLOEXEC
615 constants first appeared in
616 .Dx 3.5 .