Annotation of src/lib/libc/sys/fcntl.2, Revision 1.23
1.23 ! christos 1: .\" $NetBSD: fcntl.2,v 1.22 2002/02/08 01:28:17 ross Exp $
1.6 cgd 2: .\"
3: .\" Copyright (c) 1983, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 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. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
1.6 cgd 34: .\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94
1.1 cgd 35: .\"
1.19 kleink 36: .Dd May 5, 2001
1.1 cgd 37: .Dt FCNTL 2
1.14 garbled 38: .Os
1.1 cgd 39: .Sh NAME
40: .Nm fcntl
1.12 fair 41: .Nd file descriptor control
1.18 kleink 42: .Sh LIBRARY
43: .Lb libc
1.1 cgd 44: .Sh SYNOPSIS
1.22 ross 45: .Fd #include \*[Lt]fcntl.h\*[Gt]
1.1 cgd 46: .Ft int
1.17 ross 47: .Fn fcntl "int fd" "int cmd" "..."
1.1 cgd 48: .Sh DESCRIPTION
1.13 lukem 49: .Fn fcntl
1.1 cgd 50: provides for control over descriptors.
51: The argument
52: .Fa fd
53: is a descriptor to be operated on by
54: .Fa cmd
1.16 perry 55: as described below.
1.17 ross 56: The third parameter is called
1.16 perry 57: .Fa arg
1.17 ross 58: and is technically a pointer to void, but it is
59: interpreted as an int by some commands and ignored by others.
1.16 perry 60: .Pp
61: Commands are:
1.1 cgd 62: .Bl -tag -width F_GETOWNX
63: .It Dv F_DUPFD
64: Return a new descriptor as follows:
65: .Pp
66: .Bl -bullet -compact -offset 4n
67: .It
68: Lowest numbered available descriptor greater than or equal to
1.16 perry 69: .Fa arg ,
70: which is interpreted as an int.
1.1 cgd 71: .It
72: Same object references as the original descriptor.
73: .It
74: New descriptor shares the same file offset if the object
75: was a file.
76: .It
77: Same access mode (read, write or read/write).
78: .It
79: Same file status flags (i.e., both file descriptors
80: share the same file status flags).
81: .It
82: The close-on-exec flag associated with the new file descriptor
83: is set to remain open across
1.8 mikel 84: .Xr execve 2
1.1 cgd 85: system calls.
86: .El
87: .It Dv F_GETFD
88: Get the close-on-exec flag associated with the file descriptor
1.23 ! christos 89: .Fa fd
! 90: as
! 91: .Dv FD_CLOEXEC .
! 92: If the returned value ANDed with
! 93: .Dv FD_CLOEXEC
! 94: is 0,
1.1 cgd 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
1.23 ! christos 104: to
! 105: .Fa arg ,
! 106: where
1.1 cgd 107: .Fa arg
1.23 ! christos 108: is either 0 or
! 109: .Dv FD_CLOEXEC ,
! 110: as described above.
1.1 cgd 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
1.16 perry 117: .Fa arg ,
118: which is interpreted as an int.
1.1 cgd 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
1.20 wiz 138: as negative, otherwise
1.1 cgd 139: .Fa arg
140: is interpreted as a process ID.
1.16 perry 141: The argument
142: .Fa arg
143: is interpreted as an int.
1.1 cgd 144: .El
145: .Pp
146: The flags for the
147: .Dv F_GETFL
148: and
149: .Dv F_SETFL
150: flags are as follows:
1.6 cgd 151: .Bl -tag -width O_NONBLOCKX
152: .It Dv O_NONBLOCK
1.1 cgd 153: Non-blocking I/O; if no data is available to a
1.8 mikel 154: .Xr read 2
1.1 cgd 155: call, or if a
1.8 mikel 156: .Xr write 2
1.1 cgd 157: operation would block,
158: the read or write call returns -1 with the error
1.6 cgd 159: .Er EAGAIN .
1.1 cgd 160: .It Dv O_APPEND
161: Force each write to append at the end of file;
162: corresponds to the
163: .Dv O_APPEND
164: flag of
165: .Xr open 2 .
166: .It Dv O_ASYNC
167: Enable the
168: .Dv SIGIO
169: signal to be sent to the process group
170: when I/O is possible, e.g.,
171: upon availability of data to be read.
172: .El
1.6 cgd 173: .Pp
174: Several commands are available for doing advisory file locking;
175: they all operate on the following structure:
176: .Bd -literal
177: struct flock {
178: off_t l_start; /* starting offset */
179: off_t l_len; /* len = 0 means until end of file */
180: pid_t l_pid; /* lock owner */
181: short l_type; /* lock type: read/write, etc. */
182: short l_whence; /* type of l_start */
183: };
184: .Ed
185: The commands available for advisory record locking are as follows:
186: .Bl -tag -width F_SETLKWX
187: .It Dv F_GETLK
188: Get the first lock that blocks the lock description pointed to by the
189: third argument,
190: .Fa arg ,
191: taken as a pointer to a
192: .Fa "struct flock"
193: (see above).
194: The information retrieved overwrites the information passed to
1.12 fair 195: .Nm
1.6 cgd 196: in the
197: .Fa flock
198: structure.
199: If no lock is found that would prevent this lock from being created,
200: the structure is left unchanged by this function call except for the
1.19 kleink 201: lock type
202: .Fa l_type ,
203: which is set to
1.6 cgd 204: .Dv F_UNLCK .
205: .It Dv F_SETLK
206: Set or clear a file segment lock according to the lock description
207: pointed to by the third argument,
208: .Fa arg ,
209: taken as a pointer to a
210: .Fa "struct flock"
211: (see above).
1.19 kleink 212: As specified by the value of
213: .Fa l_type ,
1.6 cgd 214: .Dv F_SETLK
215: is used to establish shared (or read) locks
216: .Dv (F_RDLCK)
217: or exclusive (or write) locks,
218: .Dv (F_WRLCK) ,
219: as well as remove either type of lock
220: .Dv (F_UNLCK) .
221: If a shared or exclusive lock cannot be set,
1.12 fair 222: .Nm
1.6 cgd 223: returns immediately with
1.11 fair 224: .Er EAGAIN .
1.6 cgd 225: .It Dv F_SETLKW
226: This command is the same as
227: .Dv F_SETLK
228: except that if a shared or exclusive lock is blocked by other locks,
229: the process waits until the request can be satisfied.
230: If a signal that is to be caught is received while
1.12 fair 231: .Nm
1.6 cgd 232: is waiting for a region, the
1.12 fair 233: .Nm
1.6 cgd 234: will be interrupted if the signal handler has not specified the
235: .Dv SA_RESTART
236: (see
237: .Xr sigaction 2 ) .
238: .El
239: .Pp
240: When a shared lock has been set on a segment of a file,
241: other processes can set shared locks on that segment
242: or a portion of it.
243: A shared lock prevents any other process from setting an exclusive
244: lock on any portion of the protected area.
245: A request for a shared lock fails if the file descriptor was not
246: opened with read access.
247: .Pp
248: An exclusive lock prevents any other process from setting a shared lock or
249: an exclusive lock on any portion of the protected area.
250: A request for an exclusive lock fails if the file was not
251: opened with write access.
252: .Pp
253: The value of
254: .Fa l_whence
255: is
256: .Dv SEEK_SET ,
257: .Dv SEEK_CUR ,
258: or
259: .Dv SEEK_END
260: to indicate that the relative offset,
261: .Fa l_start
262: bytes, will be measured from the start of the file,
263: current position, or end of the file, respectively.
264: The value of
265: .Fa l_len
266: is the number of consecutive bytes to be locked.
267: If
268: .Fa l_len
269: is negative, the result is undefined.
270: The
271: .Fa l_pid
272: field is only used with
273: .Dv F_GETLK
274: to return the process ID of the process holding a blocking lock.
275: After a successful
276: .Dv F_GETLK
277: request, the value of
278: .Fa l_whence
279: is
280: .Dv SEEK_SET .
281: .Pp
282: Locks may start and extend beyond the current end of a file,
283: but may not start or extend before the beginning of the file.
284: A lock is set to extend to the largest possible value of the
285: file offset for that file if
286: .Fa l_len
287: is set to zero. If
288: .Fa l_whence
289: and
290: .Fa l_start
291: point to the beginning of the file, and
292: .Fa l_len
293: is zero, the entire file is locked.
294: If an application wishes only to do entire file locking, the
295: .Xr flock 2
296: system call is much more efficient.
297: .Pp
298: There is at most one type of lock set for each byte in the file.
299: Before a successful return from an
300: .Dv F_SETLK
301: or an
302: .Dv F_SETLKW
303: request when the calling process has previously existing locks
304: on bytes in the region specified by the request,
305: the previous lock type for each byte in the specified
306: region is replaced by the new lock type.
307: As specified above under the descriptions
308: of shared locks and exclusive locks, an
309: .Dv F_SETLK
310: or an
311: .Dv F_SETLKW
312: request fails or blocks respectively when another process has existing
313: locks on bytes in the specified region and the type of any of those
314: locks conflicts with the type specified in the request.
315: .Pp
1.12 fair 316: This interface follows the completely stupid semantics of
317: .At V
318: and
1.6 cgd 319: .St -p1003.1-88
320: that require that all locks associated with a file for a given process are
321: removed when \fIany\fP file descriptor for that file is closed by that process.
322: This semantic means that applications must be aware of any files that
323: a subroutine library may access.
324: For example if an application for updating the password file locks the
325: password file database while making the update, and then calls
1.12 fair 326: .Xr getpwnam 3
1.6 cgd 327: to retrieve a record,
1.20 wiz 328: the lock will be lost because
1.12 fair 329: .Xr getpwnam 3
1.6 cgd 330: opens, reads, and closes the password database.
331: The database close will release all locks that the process has
332: associated with the database, even if the library routine never
333: requested a lock on the database.
334: Another minor semantic problem with this interface is that
335: locks are not inherited by a child process created using the
336: .Xr fork 2
337: function.
338: The
339: .Xr flock 2
340: interface has much more rational last close semantics and
341: allows locks to be inherited by child processes.
1.12 fair 342: Calling
343: .Xr flock 2
1.6 cgd 344: is recommended for applications that want to ensure the integrity
345: of their locks when using library routines or wish to pass locks
346: to their children.
1.20 wiz 347: Note that
1.6 cgd 348: .Xr flock 2
1.20 wiz 349: and
1.6 cgd 350: .Xr fcntl 2
351: locks may be safely used concurrently.
352: .Pp
353: All locks associated with a file for a given process are
354: removed when the process terminates.
355: .Pp
356: A potential for deadlock occurs if a process controlling a locked region
357: is put to sleep by attempting to lock the locked region of another process.
358: This implementation detects that sleeping until a locked region is unlocked
359: would cause a deadlock and fails with an
360: .Er EDEADLK
361: error.
1.1 cgd 362: .Sh RETURN VALUES
363: Upon successful completion, the value returned depends on
364: .Fa cmd
365: as follows:
366: .Bl -tag -width F_GETOWNX -offset indent
367: .It Dv F_DUPFD
368: A new file descriptor.
369: .It Dv F_GETFD
370: Value of flag (only the low-order bit is defined).
371: .It Dv F_GETFL
372: Value of flags.
373: .It Dv F_GETOWN
374: Value of file descriptor owner.
375: .It other
376: Value other than -1.
377: .El
378: .Pp
379: Otherwise, a value of -1 is returned and
380: .Va errno
381: is set to indicate the error.
382: .Sh ERRORS
1.13 lukem 383: .Fn fcntl
1.1 cgd 384: will fail if:
385: .Bl -tag -width Er
1.11 fair 386: .It Bq Er EAGAIN
1.6 cgd 387: The argument
388: .Fa arg
389: is
390: .Dv F_SETLK ,
391: the type of lock
392: .Fa (l_type)
393: is a shared lock
394: .Dv (F_RDLCK)
395: or exclusive lock
396: .Dv (F_WRLCK) ,
397: and the segment of a file to be locked is already
398: exclusive-locked by another process;
399: or the type is an exclusive lock and some portion of the
400: segment of a file to be locked is already shared-locked or
401: exclusive-locked by another process.
1.1 cgd 402: .It Bq Er EBADF
1.13 lukem 403: .Fa fildes
1.1 cgd 404: is not a valid open file descriptor.
1.6 cgd 405: .Pp
406: The argument
407: .Fa cmd
408: is
409: .Dv F_SETLK
410: or
411: .Dv F_SETLKW ,
412: the type of lock
413: .Fa (l_type)
414: is a shared lock
415: .Dv (F_RDLCK) ,
416: and
417: .Fa fildes
418: is not a valid file descriptor open for reading.
419: .Pp
420: The argument
421: .Fa cmd
422: is
423: .Dv F_SETLK
424: or
425: .Dv F_SETLKW ,
426: the type of lock
427: .Fa (l_type)
428: is an exclusive lock
429: .Dv (F_WRLCK) ,
430: and
431: .Fa fildes
432: is not a valid file descriptor open for writing.
1.1 cgd 433: .It Bq Er EMFILE
1.13 lukem 434: .Fa cmd
1.1 cgd 435: is
436: .Dv F_DUPFD
437: and the maximum allowed number of file descriptors are currently
438: open.
1.6 cgd 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.
1.1 cgd 451: .It Bq Er EINVAL
1.13 lukem 452: .Fa cmd
1.1 cgd 453: is
454: .Dv F_DUPFD
455: and
456: .Fa arg
457: is negative or greater than the maximum allowable number
458: (see
1.8 mikel 459: .Xr getdtablesize 3 ) .
1.6 cgd 460: .Pp
461: The argument
462: .Fa cmd
463: is
464: .Dv F_GETLK ,
465: .Dv F_SETLK ,
466: or
467: .Dv F_SETLKW
468: and the data to which
469: .Fa arg
470: points is not valid, or
471: .Fa fildes
472: refers to a file that does not support locking.
473: .It Bq Er EMFILE
474: The argument
475: .Fa cmd
476: is
1.10 mikel 477: .Dv F_DUPFD
1.6 cgd 478: and the maximum number of file descriptors permitted for the
479: process are already in use,
480: or no file descriptors greater than or equal to
481: .Fa arg
482: are available.
483: .It Bq Er ENOLCK
484: The argument
485: .Fa cmd
486: is
487: .Dv F_SETLK
488: or
489: .Dv F_SETLKW ,
490: and satisfying the lock or unlock request would result in the
491: number of locked regions in the system exceeding a system-imposed limit.
1.1 cgd 492: .It Bq Er ESRCH
1.13 lukem 493: .Fa cmd
1.1 cgd 494: is
495: .Dv F_SETOWN
496: and
497: the process ID given as argument is not in use.
498: .El
499: .Sh SEE ALSO
500: .Xr close 2 ,
501: .Xr execve 2 ,
1.6 cgd 502: .Xr flock 2 ,
1.1 cgd 503: .Xr open 2 ,
1.21 wiz 504: .Xr sigaction 2 ,
505: .Xr getdtablesize 3
1.7 kleink 506: .Sh STANDARDS
507: The
508: .Fn fcntl
509: function conforms to
1.9 kleink 510: .St -p1003.1-90 .
1.1 cgd 511: .Sh HISTORY
512: The
1.3 jtc 513: .Fn fcntl
1.1 cgd 514: function call appeared in
515: .Bx 4.2 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to fcntl.2 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / sys