| blob | 80d351ad71a166bcf8e1701a44251edda736f586 |
1 .\" $NetBSD: fcntl.2,v 1.35 2009/06/01 09:56:06 njoly 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 June 1, 2009
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_GETOWNX
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_GETFD
84 Get the close-on-exec flag associated with the file descriptor
85 .Fa fd
86 as
87 .Dv FD_CLOEXEC .
88 If the returned value ANDed with
89 .Dv FD_CLOEXEC
90 is 0,
91 the file will remain open across
92 .Fn exec ,
93 otherwise the file will be closed upon execution of
94 .Fn exec
95 .Fa ( arg
96 is ignored).
97 .It Dv F_SETFD
98 Set the close-on-exec flag associated with
99 .Fa fd
100 to
101 .Fa arg ,
102 where
103 .Fa arg
104 is either 0 or
105 .Dv FD_CLOEXEC ,
106 as described above.
107 .It Dv F_GETFL
108 Get descriptor status flags, as described below
109 .Fa ( arg
110 is ignored).
111 .It Dv F_SETFL
112 Set descriptor status flags to
113 .Fa arg ,
114 which is interpreted as an int.
115 .It Dv F_GETOWN
116 Get the process ID or process group
117 currently receiving
118 .Dv SIGIO
119 and
120 .Dv SIGURG
121 signals; process groups are returned
122 as negative values
123 .Fa ( arg
124 is ignored).
125 .It Dv F_SETOWN
126 Set the process or process group
127 to receive
128 .Dv SIGIO
129 and
130 .Dv SIGURG
131 signals;
132 process groups are specified by supplying
133 .Fa arg
134 as negative, otherwise
135 .Fa arg
136 is interpreted as a process ID.
137 The argument
138 .Fa arg
139 is interpreted as an int.
140 .It Dv F_CLOSEM
141 Close all file descriptors greater than or equal to
142 .Ar fd .
143 .It Dv F_MAXFD
144 Return the maximum file descriptor number currently open by the process.
145 .El
146 .Pp
147 The flags for the
148 .Dv F_GETFL
149 and
150 .Dv F_SETFL
151 flags are as follows:
152 .Bl -tag -width O_NONBLOCKX
153 .It Dv O_NONBLOCK
154 Non-blocking I/O; if no data is available to a
155 .Xr read 2
156 call, or if a
157 .Xr write 2
158 operation would block,
159 the read or write call returns \-1 with the error
160 .Er EAGAIN .
161 .It Dv O_APPEND
162 Force each write to append at the end of file;
163 corresponds to the
164 .Dv O_APPEND
165 flag of
166 .Xr open 2 .
167 .It Dv O_ASYNC
168 Enable the
169 .Dv SIGIO
170 signal to be sent to the process group
171 when I/O is possible, e.g.,
172 upon availability of data to be read.
173 .El
174 .Pp
175 Several commands are available for doing advisory file locking;
176 they all operate on the following structure:
177 .Bd -literal
178 struct flock {
179 off_t l_start; /* starting offset */
180 off_t l_len; /* len = 0 means until end of file */
181 pid_t l_pid; /* lock owner */
182 short l_type; /* lock type: read/write, etc. */
183 short l_whence; /* type of l_start */
184 };
185 .Ed
186 .Pp
187 The commands available for advisory record locking are as follows:
188 .Bl -tag -width F_SETLKWX
189 .It Dv F_GETLK
190 Get the first lock that blocks the lock description pointed to by the
191 third argument,
192 .Fa arg ,
193 taken as a pointer to a
194 .Fa "struct flock"
195 (see above).
196 The information retrieved overwrites the information passed to
197 .Nm
198 in the
199 .Fa flock
200 structure.
201 If no lock is found that would prevent this lock from being created,
202 the structure is left unchanged by this function call except for the
203 lock type
204 .Fa l_type ,
205 which is set to
206 .Dv F_UNLCK .
207 .It Dv F_SETLK
208 Set or clear a file segment lock according to the lock description
209 pointed to by the third argument,
210 .Fa arg ,
211 taken as a pointer to a
212 .Fa "struct flock"
213 (see above).
214 As specified by the value of
215 .Fa l_type ,
216 .Dv F_SETLK
217 is used to establish shared (or read) locks
218 .Pq Dv F_RDLCK
219 or exclusive (or write) locks,
220 .Pq Dv F_WRLCK ,
221 as well as remove either type of lock
222 .Pq Dv F_UNLCK .
223 If a shared or exclusive lock cannot be set,
224 .Nm
225 returns immediately with
226 .Er EAGAIN .
227 .It Dv F_SETLKW
228 This command is the same as
229 .Dv F_SETLK
230 except that if a shared or exclusive lock is blocked by other locks,
231 the process waits until the request can be satisfied.
232 If a signal that is to be caught is received while
233 .Nm
234 is waiting for a region, the
235 .Nm
236 will be interrupted if the signal handler has not specified the
237 .Dv SA_RESTART
238 (see
239 .Xr sigaction 2 ) .
240 .El
241 .Pp
242 When a shared lock has been set on a segment of a file,
243 other processes can set shared locks on that segment
244 or a portion of it.
245 A shared lock prevents any other process from setting an exclusive
246 lock on any portion of the protected area.
247 A request for a shared lock fails if the file descriptor was not
248 opened with read access.
249 .Pp
250 An exclusive lock prevents any other process from setting a shared lock or
251 an exclusive lock on any portion of the protected area.
252 A request for an exclusive lock fails if the file was not
253 opened with write access.
254 .Pp
255 The value of
256 .Fa l_whence
257 is
258 .Dv SEEK_SET ,
259 .Dv SEEK_CUR ,
260 or
261 .Dv SEEK_END
262 to indicate that the relative offset,
263 .Fa l_start
264 bytes, will be measured from the start of the file,
265 current position, or end of the file, respectively.
266 The value of
267 .Fa l_len
268 is the number of consecutive bytes to be locked.
269 If
270 .Fa l_len
271 is negative, the result is undefined.
272 The
273 .Fa l_pid
274 field is only used with
275 .Dv F_GETLK
276 to return the process ID of the process holding a blocking lock.
277 After a successful
278 .Dv F_GETLK
279 request, the value of
280 .Fa l_whence
281 is
282 .Dv SEEK_SET .
283 .Pp
284 Locks may start and extend beyond the current end of a file,
285 but may not start or extend before the beginning of the file.
286 A lock is set to extend to the largest possible value of the
287 file offset for that file if
288 .Fa l_len
289 is set to zero.
290 If
291 .Fa l_whence
292 and
293 .Fa l_start
294 point to the beginning of the file, and
295 .Fa l_len
296 is zero, the entire file is locked.
297 If an application wishes only to do entire file locking, the
298 .Xr flock 2
299 system call is much more efficient.
300 .Pp
301 There is at most one type of lock set for each byte in the file.
302 Before a successful return from an
303 .Dv F_SETLK
304 or an
305 .Dv F_SETLKW
306 request when the calling process has previously existing locks
307 on bytes in the region specified by the request,
308 the previous lock type for each byte in the specified
309 region is replaced by the new lock type.
310 As specified above under the descriptions
311 of shared locks and exclusive locks, an
312 .Dv F_SETLK
313 or an
314 .Dv F_SETLKW
315 request fails or blocks respectively when another process has existing
316 locks on bytes in the specified region and the type of any of those
317 locks conflicts with the type specified in the request.
318 .Pp
319 This interface follows the completely stupid semantics of
320 .At V
321 and
322 .St -p1003.1-88
323 that require that all locks associated with a file for a given process are
324 removed when \fIany\fP file descriptor for that file is closed by that process.
325 This semantic means that applications must be aware of any files that
326 a subroutine library may access.
327 For example if an application for updating the password file locks the
328 password file database while making the update, and then calls
329 .Xr getpwnam 3
330 to retrieve a record,
331 the lock will be lost because
332 .Xr getpwnam 3
333 opens, reads, and closes the password database.
334 The database close will release all locks that the process has
335 associated with the database, even if the library routine never
336 requested a lock on the database.
337 Another minor semantic problem with this interface is that
338 locks are not inherited by a child process created using the
339 .Xr fork 2
340 function.
341 The
342 .Xr flock 2
343 interface has much more rational last close semantics and
344 allows locks to be inherited by child processes.
345 Calling
346 .Xr flock 2
347 is recommended for applications that want to ensure the integrity
348 of their locks when using library routines or wish to pass locks
349 to their children.
350 Note that
351 .Xr flock 2
352 and
353 .Nm
354 locks may be safely used concurrently.
355 .Pp
356 All locks associated with a file for a given process are
357 removed when the process terminates.
358 .Pp
359 A potential for deadlock occurs if a process controlling a locked region
360 is put to sleep by attempting to lock the locked region of another process.
361 This implementation detects that sleeping until a locked region is unlocked
362 would cause a deadlock and fails with an
363 .Er EDEADLK
364 error.
365 .Sh RETURN VALUES
366 Upon successful completion, the value returned depends on
367 .Fa cmd
368 as follows:
369 .Bl -tag -width F_GETOWNX -offset indent
370 .It Dv F_DUPFD
371 A new file descriptor.
372 .It Dv F_GETFD
373 Value of flag (only the low-order bit is defined).
374 .It Dv F_GETFL
375 Value of flags.
376 .It Dv F_GETOWN
377 Value of file descriptor owner.
378 .It Dv F_MAXFD
379 Value of the highest file descriptor open by the process.
380 .It other
381 Value other than \-1.
382 .El
383 .Pp
384 Otherwise, a value of \-1 is returned and
385 .Va errno
386 is set to indicate the error.
387 .Sh ERRORS
388 .Fn fcntl
389 will fail if:
390 .Bl -tag -width Er
391 .It Bq Er EAGAIN
392 The argument
393 .Fa arg
394 is
395 .Dv F_SETLK ,
396 the type of lock
397 .Pq Fa l_type
398 is a shared lock
399 .Pq Dv F_RDLCK
400 or exclusive lock
401 .Pq Dv F_WRLCK ,
402 and the segment of a file to be locked is already
403 exclusive-locked by another process;
404 or the type is an exclusive lock and some portion of the
405 segment of a file to be locked is already shared-locked or
406 exclusive-locked by another process.
407 .It Bq Er EBADF
408 .Fa fildes
409 is not a valid open file descriptor.
410 .Pp
411 The argument
412 .Fa cmd
413 is
414 .Dv F_SETLK
415 or
416 .Dv F_SETLKW ,
417 the type of lock
418 .Pq Fa l_type
419 is a shared lock
420 .Pq Dv F_RDLCK ,
421 and
422 .Fa fildes
423 is not a valid file descriptor open for reading.
424 .Pp
425 The argument
426 .Fa cmd
427 is
428 .Dv F_SETLK
429 or
430 .Dv F_SETLKW ,
431 the type of lock
432 .Pq Fa l_type
433 is an exclusive lock
434 .Pq Dv F_WRLCK ,
435 and
436 .Fa fildes
437 is not a valid file descriptor open for writing.
438 .It Bq Er EDEADLK
439 The argument
440 .Fa cmd
441 is
442 .Dv F_SETLKW ,
443 and a deadlock condition was detected.
444 .It Bq Er EINTR
445 The argument
446 .Fa cmd
447 is
448 .Dv F_SETLKW ,
449 and the function was interrupted by a signal.
450 .It Bq Er EINVAL
451 The argument
452 .Fa cmd
453 is invalid.
454 .Pp
455 The argument
456 .Fa cmd
457 is
458 .Dv F_DUPFD
459 and
460 .Fa arg
461 is negative or greater than the maximum allowable number
462 (see
463 .Xr getdtablesize 3 ) .
464 .Pp
465 The argument
466 .Fa cmd
467 is
468 .Dv F_GETLK ,
469 .Dv F_SETLK ,
470 or
471 .Dv F_SETLKW
472 and the data to which
473 .Fa arg
474 points is not valid, or
475 .Fa fildes
476 refers to a file that does not support locking.
477 .It Bq Er EMFILE
478 The argument
479 .Fa cmd
480 is
481 .Dv F_DUPFD
482 and the maximum number of file descriptors permitted for the
483 process are already in use,
484 or no file descriptors greater than or equal to
485 .Fa arg
486 are available.
487 .It Bq Er ENFILE
488 .Fa cmd
489 is
490 .Dv F_DUPFD
491 and system-wide the maximum allowed number of file descriptors are
492 currently open.
493 .It Bq Er ENOLCK
494 The argument
495 .Fa cmd
496 is
497 .Dv F_SETLK
498 or
499 .Dv F_SETLKW ,
500 and satisfying the lock or unlock request would result in the
501 number of locked regions in the system exceeding a system-imposed limit.
502 .It Bq Er ESRCH
503 .Fa cmd
504 is
505 .Dv F_SETOWN
506 and
507 the process ID given as argument is not in use.
508 .El
509 .Sh SEE ALSO
510 .Xr close 2 ,
511 .Xr execve 2 ,
512 .Xr flock 2 ,
513 .Xr open 2 ,
514 .Xr sigaction 2 ,
515 .Xr getdtablesize 3
516 .Sh STANDARDS
517 The
518 .Fn fcntl
519 function conforms to
520 .St -p1003.1-90 .
521 .Sh HISTORY
522 The
523 .Fn fcntl
524 function call appeared in
525 .Bx 4.2 .