| blob | a22fe0496f621c691bc7ac292127844c833ff937 |
1 .\" $NetBSD: fcntl.2,v 1.37 2010/05/17 12:16:43 jruoho 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 May 17, 2010
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 .Sh COMPATIBILITY
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 .Pp
338 Another minor semantic problem with this interface is that
339 locks are not inherited by a child process created using the
340 .Xr fork 2
341 function.
342 The
343 .Xr flock 2
344 interface has much more rational last close semantics and
345 allows locks to be inherited by child processes.
346 Calling
347 .Xr flock 2
348 is recommended for applications that want to ensure the integrity
349 of their locks when using library routines or wish to pass locks
350 to their children.
351 Note that
352 .Xr flock 2
353 and
354 .Nm
355 locks may be safely used concurrently.
356 .Pp
357 All locks associated with a file for a given process are
358 removed when the process terminates.
359 .Pp
360 A potential for deadlock occurs if a process controlling a locked region
361 is put to sleep by attempting to lock the locked region of another process.
362 This implementation detects that sleeping until a locked region is unlocked
363 would cause a deadlock and fails with an
364 .Er EDEADLK
365 error.
366 .Sh RETURN VALUES
367 Upon successful completion, the value returned depends on
368 .Fa cmd
369 as follows:
370 .Bl -tag -width F_GETOWNX -offset indent
371 .It Dv F_DUPFD
372 A new file descriptor.
373 .It Dv F_GETFD
374 Value of flag (only the low-order bit is defined).
375 .It Dv F_GETFL
376 Value of flags.
377 .It Dv F_GETOWN
378 Value of file descriptor owner.
379 .It Dv F_MAXFD
380 Value of the highest file descriptor open by the process.
381 .It other
382 Value other than \-1.
383 .El
384 .Pp
385 Otherwise, a value of \-1 is returned and
386 .Va errno
387 is set to indicate the error.
388 .Sh ERRORS
389 .Fn fcntl
390 will fail if:
391 .Bl -tag -width Er
392 .It Bq Er EAGAIN
393 The argument
394 .Fa arg
395 is
396 .Dv F_SETLK ,
397 the type of lock
398 .Pq Fa l_type
399 is a shared lock
400 .Pq Dv F_RDLCK
401 or exclusive lock
402 .Pq Dv F_WRLCK ,
403 and the segment of a file to be locked is already
404 exclusive-locked by another process;
405 or the type is an exclusive lock and some portion of the
406 segment of a file to be locked is already shared-locked or
407 exclusive-locked by another process.
408 .It Bq Er EBADF
409 .Fa fildes
410 is not a valid open file descriptor.
411 .Pp
412 The argument
413 .Fa cmd
414 is
415 .Dv F_SETLK
416 or
417 .Dv F_SETLKW ,
418 the type of lock
419 .Pq Fa l_type
420 is a shared lock
421 .Pq Dv F_RDLCK ,
422 and
423 .Fa fildes
424 is not a valid file descriptor open for reading.
425 .Pp
426 The argument
427 .Fa cmd
428 is
429 .Dv F_SETLK
430 or
431 .Dv F_SETLKW ,
432 the type of lock
433 .Pq Fa l_type
434 is an exclusive lock
435 .Pq Dv F_WRLCK ,
436 and
437 .Fa fildes
438 is not a valid file descriptor open for writing.
439 .It Bq Er EDEADLK
440 The argument
441 .Fa cmd
442 is
443 .Dv F_SETLKW ,
444 and a deadlock condition was detected.
445 .It Bq Er EINTR
446 The argument
447 .Fa cmd
448 is
449 .Dv F_SETLKW ,
450 and the function was interrupted by a signal.
451 .It Bq Er EINVAL
452 The argument
453 .Fa cmd
454 is invalid.
455 .Pp
456 The argument
457 .Fa cmd
458 is
459 .Dv F_DUPFD
460 and
461 .Fa arg
462 is negative or greater than the maximum allowable number
463 (see
464 .Xr getdtablesize 3 ) .
465 .Pp
466 The argument
467 .Fa cmd
468 is
469 .Dv F_GETLK ,
470 .Dv F_SETLK ,
471 or
472 .Dv F_SETLKW
473 and the data to which
474 .Fa arg
475 points is not valid, or
476 .Fa fildes
477 refers to a file that does not support locking.
478 .It Bq Er EMFILE
479 The argument
480 .Fa cmd
481 is
482 .Dv F_DUPFD
483 and the maximum number of file descriptors permitted for the
484 process are already in use,
485 or no file descriptors greater than or equal to
486 .Fa arg
487 are available.
488 .It Bq Er ENFILE
489 .Fa cmd
490 is
491 .Dv F_DUPFD
492 and system-wide the maximum allowed number of file descriptors are
493 currently open.
494 .It Bq Er ENOLCK
495 The argument
496 .Fa cmd
497 is
498 .Dv F_SETLK
499 or
500 .Dv F_SETLKW ,
501 and satisfying the lock or unlock request would result in the
502 number of locked regions in the system exceeding a system-imposed limit.
503 .It Bq Er ESRCH
504 .Fa cmd
505 is
506 .Dv F_SETOWN
507 and
508 the process ID given as argument is not in use.
509 .El
510 .Sh SEE ALSO
511 .Xr close 2 ,
512 .Xr execve 2 ,
513 .Xr flock 2 ,
514 .Xr open 2 ,
515 .Xr sigaction 2 ,
516 .Xr getdtablesize 3
517 .Sh STANDARDS
518 The
519 .Fn fcntl
520 function conforms to
521 .St -p1003.1-90 .
522 .Sh HISTORY
523 The
524 .Fn fcntl
525 function call appeared in
526 .Bx 4.2 .