| blob | 4d3f7799c3e8a90bb5a1733ef16c17122df84ffd |
1 .\" $NetBSD: fcntl.2,v 1.40 2012/01/25 00:28:35 christos Exp $
2 .\"
3 .\" Copyright (c) 1983, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94
31 .\"
32 .Dd January 23, 2012
33 .Dt FCNTL 2
34 .Os
35 .Sh NAME
36 .Nm fcntl
37 .Nd file descriptor control
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In fcntl.h
42 .Ft int
43 .Fn fcntl "int fd" "int cmd" "..."
44 .Sh DESCRIPTION
45 .Fn fcntl
46 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 The third parameter is called
53 .Fa arg
54 and is technically a pointer to void, but it is
55 interpreted as an int by some commands and ignored by others.
56 .Pp
57 Commands are:
58 .Bl -tag -width F_DUPFD_CLOEXEC
59 .It Dv F_DUPFD
60 Return a new descriptor as follows:
61 .Pp
62 .Bl -bullet -compact -offset 4n
63 .It
64 Lowest numbered available descriptor greater than or equal to
65 .Fa arg ,
66 which is interpreted as an int.
67 .It
68 Same object references as the original descriptor.
69 .It
70 New descriptor shares the same file offset if the object
71 was a file.
72 .It
73 Same access mode (read, write or read/write).
74 .It
75 Same file status flags (i.e., both file descriptors
76 share the same file status flags).
77 .It
78 The close-on-exec flag associated with the new file descriptor
79 is cleared to remain open across
80 .Xr execve 2
81 system calls.
82 .El
83 .It Dv F_DUPFD_CLOEXEC
84 Same as
85 .Dv F_DUPFD ,
86 but sets the close-on-exec property on the file descriptor created.
87 .It Dv F_GETFD
88 Get the close-on-exec flag associated with the file descriptor
89 .Fa fd
90 as
91 .Dv FD_CLOEXEC .
92 If the returned value ANDed with
93 .Dv FD_CLOEXEC
94 is 0,
95 the file will remain open across
96 .Fn exec ,
97 otherwise the file will be closed upon execution of
98 .Fn exec
99 .Fa ( arg
100 is ignored).
101 .It Dv F_SETFD
102 Set the close-on-exec flag associated with
103 .Fa fd
104 to
105 .Fa arg ,
106 where
107 .Fa arg
108 is either 0 or
109 .Dv FD_CLOEXEC ,
110 as described above.
111 .It Dv F_GETFL
112 Get descriptor status flags, as described below
113 .Fa ( arg
114 is ignored).
115 .It Dv F_SETFL
116 Set descriptor status flags to
117 .Fa arg ,
118 which is interpreted as an int.
119 .It Dv F_GETOWN
120 Get the process ID or process group
121 currently receiving
122 .Dv SIGIO
123 and
124 .Dv SIGURG
125 signals; process groups are returned
126 as negative values
127 .Fa ( arg
128 is ignored).
129 .It Dv F_SETOWN
130 Set the process or process group
131 to receive
132 .Dv SIGIO
133 and
134 .Dv SIGURG
135 signals;
136 process groups are specified by supplying
137 .Fa arg
138 as negative, otherwise
139 .Fa arg
140 is interpreted as a process ID.
141 The argument
142 .Fa arg
143 is interpreted as an int.
144 .It Dv F_CLOSEM
145 Close all file descriptors greater than or equal to
146 .Ar fd .
147 .It Dv F_MAXFD
148 Return the maximum file descriptor number currently open by the process.
149 .It Dv F_GETNOSIGPIPE
150 Return if the
151 .Dv O_NOSIGPIPE
152 flag is set in the file descriptor.
153 .It Dv F_SETNOSIGPIPE
154 Set or clear the
155 .Dv O_NOSIGPIPE
156 in the file descriptor.
157 .El
158 .Pp
159 The set of valid flags for the
160 .Dv F_GETFL
161 and
162 .Dv F_SETFL
163 flags are as follows:
164 .Dv O_APPEND ,
165 .Dv O_ASYNC ,
166 .Dv O_FSYNC ,
167 .Dv O_NONBLOCK ,
168 .Dv O_DSYNC ,
169 .Dv O_RSYNC ,
170 .Dv O_ALT_IO ,
171 .Dv O_DIRECT ,
172 .Dv O_NOSIGPIPE .
173 These flags are described in
174 .Xr open 2 .
175 .Pp
176 Several commands are available for doing advisory file locking;
177 they all operate on the following structure:
178 .Bd -literal
179 struct flock {
180 off_t l_start; /* starting offset */
181 off_t l_len; /* len = 0 means until end of file */
182 pid_t l_pid; /* lock owner */
183 short l_type; /* lock type: read/write, etc. */
184 short l_whence; /* type of l_start */
185 };
186 .Ed
187 .Pp
188 The commands available for advisory record locking are as follows:
189 .Bl -tag -width F_SETLKWX
190 .It Dv F_GETLK
191 Get the first lock that blocks the lock description pointed to by the
192 third argument,
193 .Fa arg ,
194 taken as a pointer to a
195 .Fa "struct flock"
196 (see above).
197 The information retrieved overwrites the information passed to
198 .Nm
199 in the
200 .Fa flock
201 structure.
202 If no lock is found that would prevent this lock from being created,
203 the structure is left unchanged by this function call except for the
204 lock type
205 .Fa l_type ,
206 which is set to
207 .Dv F_UNLCK .
208 .It Dv F_SETLK
209 Set or clear a file segment lock according to the lock description
210 pointed to by the third argument,
211 .Fa arg ,
212 taken as a pointer to a
213 .Fa "struct flock"
214 (see above).
215 As specified by the value of
216 .Fa l_type ,
217 .Dv F_SETLK
218 is used to establish shared (or read) locks
219 .Pq Dv F_RDLCK
220 or exclusive (or write) locks,
221 .Pq Dv F_WRLCK ,
222 as well as remove either type of lock
223 .Pq Dv F_UNLCK .
224 If a shared or exclusive lock cannot be set,
225 .Nm
226 returns immediately with
227 .Er EAGAIN .
228 .It Dv F_SETLKW
229 This command is the same as
230 .Dv F_SETLK
231 except that if a shared or exclusive lock is blocked by other locks,
232 the process waits until the request can be satisfied.
233 If a signal that is to be caught is received while
234 .Nm
235 is waiting for a region, the
236 .Nm
237 will be interrupted if the signal handler has not specified the
238 .Dv SA_RESTART
239 (see
240 .Xr sigaction 2 ) .
241 .El
242 .Pp
243 When a shared lock has been set on a segment of a file,
244 other processes can set shared locks on that segment
245 or a portion of it.
246 A shared lock prevents any other process from setting an exclusive
247 lock on any portion of the protected area.
248 A request for a shared lock fails if the file descriptor was not
249 opened with read access.
250 .Pp
251 An exclusive lock prevents any other process from setting a shared lock or
252 an exclusive lock on any portion of the protected area.
253 A request for an exclusive lock fails if the file was not
254 opened with write access.
255 .Pp
256 The value of
257 .Fa l_whence
258 is
259 .Dv SEEK_SET ,
260 .Dv SEEK_CUR ,
261 or
262 .Dv SEEK_END
263 to indicate that the relative offset,
264 .Fa l_start
265 bytes, will be measured from the start of the file,
266 current position, or end of the file, respectively.
267 The value of
268 .Fa l_len
269 is the number of consecutive bytes to be locked.
270 If
271 .Fa l_len
272 is negative, the result is undefined.
273 The
274 .Fa l_pid
275 field is only used with
276 .Dv F_GETLK
277 to return the process ID of the process holding a blocking lock.
278 After a successful
279 .Dv F_GETLK
280 request, the value of
281 .Fa l_whence
282 is
283 .Dv SEEK_SET .
284 .Pp
285 Locks may start and extend beyond the current end of a file,
286 but may not start or extend before the beginning of the file.
287 A lock is set to extend to the largest possible value of the
288 file offset for that file if
289 .Fa l_len
290 is set to zero.
291 If
292 .Fa l_whence
293 and
294 .Fa l_start
295 point to the beginning of the file, and
296 .Fa l_len
297 is zero, the entire file is locked.
298 If an application wishes only to do entire file locking, the
299 .Xr flock 2
300 system call is much more efficient.
301 .Pp
302 There is at most one type of lock set for each byte in the file.
303 Before a successful return from an
304 .Dv F_SETLK
305 or an
306 .Dv F_SETLKW
307 request when the calling process has previously existing locks
308 on bytes in the region specified by the request,
309 the previous lock type for each byte in the specified
310 region is replaced by the new lock type.
311 As specified above under the descriptions
312 of shared locks and exclusive locks, an
313 .Dv F_SETLK
314 or an
315 .Dv F_SETLKW
316 request fails or blocks respectively when another process has existing
317 locks on bytes in the specified region and the type of any of those
318 locks conflicts with the type specified in the request.
319 .Sh RETURN VALUES
320 Upon successful completion, the value returned depends on
321 .Fa cmd
322 as follows:
323 .Bl -tag -width F_GETOWNX -offset indent
324 .It Dv F_DUPFD
325 A new file descriptor.
326 .It Dv F_GETFD
327 Value of flag (only the low-order bit is defined).
328 .It Dv F_GETFL
329 Value of flags.
330 .It Dv F_GETOWN
331 Value of file descriptor owner.
332 .It Dv F_MAXFD
333 Value of the highest file descriptor open by the process.
334 .It other
335 Value other than \-1.
336 .El
337 .Pp
338 Otherwise, a value of \-1 is returned and
339 .Va errno
340 is set to indicate the error.
341 .Sh COMPATIBILITY
342 This interface follows the completely stupid semantics of
343 .At V
344 and
345 .St -p1003.1-88
346 that require that all locks associated with a file for a given process are
347 removed when \fIany\fP file descriptor for that file is closed by that process.
348 This semantic means that applications must be aware of any files that
349 a subroutine library may access.
350 For example if an application for updating the password file locks the
351 password file database while making the update, and then calls
352 .Xr getpwnam 3
353 to retrieve a record,
354 the lock will be lost because
355 .Xr getpwnam 3
356 opens, reads, and closes the password database.
357 The database close will release all locks that the process has
358 associated with the database, even if the library routine never
359 requested a lock on the database.
360 .Pp
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 function.
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 Calling
370 .Xr flock 2
371 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 Note that
375 .Xr flock 2
376 and
377 .Nm
378 locks may be safely used concurrently.
379 .Pp
380 All locks associated with a file for a given process are
381 removed when the process terminates.
382 .Pp
383 A potential for deadlock occurs if a process controlling a locked region
384 is put to sleep by attempting to lock the locked region of another process.
385 This implementation detects that sleeping until a locked region is unlocked
386 would cause a deadlock and fails with an
387 .Er EDEADLK
388 error.
389 .Sh ERRORS
390 .Fn fcntl
391 will fail if:
392 .Bl -tag -width Er
393 .It Bq Er EAGAIN
394 The argument
395 .Fa arg
396 is
397 .Dv F_SETLK ,
398 the type of lock
399 .Pq Fa l_type
400 is a shared lock
401 .Pq Dv F_RDLCK
402 or exclusive lock
403 .Pq Dv F_WRLCK ,
404 and the segment of a file to be locked is already
405 exclusive-locked by another process;
406 or the type is an exclusive lock and some portion of the
407 segment of a file to be locked is already shared-locked or
408 exclusive-locked by another process.
409 .It Bq Er EBADF
410 .Fa fildes
411 is not a valid open file descriptor.
412 .Pp
413 The argument
414 .Fa cmd
415 is
416 .Dv F_SETLK
417 or
418 .Dv F_SETLKW ,
419 the type of lock
420 .Pq Fa l_type
421 is a shared lock
422 .Pq Dv F_RDLCK ,
423 and
424 .Fa fildes
425 is not a valid file descriptor open for reading.
426 .Pp
427 The argument
428 .Fa cmd
429 is
430 .Dv F_SETLK
431 or
432 .Dv F_SETLKW ,
433 the type of lock
434 .Pq Fa l_type
435 is an exclusive lock
436 .Pq Dv F_WRLCK ,
437 and
438 .Fa fildes
439 is not a valid file descriptor open for writing.
440 .It Bq Er EDEADLK
441 The argument
442 .Fa cmd
443 is
444 .Dv F_SETLKW ,
445 and a deadlock condition was detected.
446 .It Bq Er EINTR
447 The argument
448 .Fa cmd
449 is
450 .Dv F_SETLKW ,
451 and the function was interrupted by a signal.
452 .It Bq Er EINVAL
453 The argument
454 .Fa cmd
455 is invalid.
456 .Pp
457 The argument
458 .Fa cmd
459 is
460 .Dv F_DUPFD
461 and
462 .Fa arg
463 is negative or greater than the maximum allowable number
464 (see
465 .Xr getdtablesize 3 ) .
466 .Pp
467 The argument
468 .Fa cmd
469 is
470 .Dv F_GETLK ,
471 .Dv F_SETLK ,
472 or
473 .Dv F_SETLKW
474 and the data to which
475 .Fa arg
476 points is not valid, or
477 .Fa fildes
478 refers to a file that does not support locking.
479 .It Bq Er EMFILE
480 The argument
481 .Fa cmd
482 is
483 .Dv F_DUPFD
484 and the maximum number of file descriptors permitted for the
485 process are already in use,
486 or no file descriptors greater than or equal to
487 .Fa arg
488 are available.
489 .It Bq Er ENFILE
490 .Fa cmd
491 is
492 .Dv F_DUPFD
493 and system-wide the maximum allowed number of file descriptors are
494 currently open.
495 .It Bq Er ENOLCK
496 The argument
497 .Fa cmd
498 is
499 .Dv F_SETLK
500 or
501 .Dv F_SETLKW ,
502 and satisfying the lock or unlock request would result in the
503 number of locked regions in the system exceeding a system-imposed limit.
504 .It Bq Er ESRCH
505 .Fa cmd
506 is
507 .Dv F_SETOWN
508 and
509 the process ID given as argument is not in use.
510 .El
511 .Sh SEE ALSO
512 .Xr close 2 ,
513 .Xr execve 2 ,
514 .Xr flock 2 ,
515 .Xr open 2 ,
516 .Xr sigaction 2 ,
517 .Xr getdtablesize 3
518 .Sh STANDARDS
519 The
520 .Fn fcntl
521 function conforms to
522 .St -p1003.1-90 .
523 .Sh HISTORY
524 The
525 .Fn fcntl
526 function call appeared in
527 .Bx 4.2 .