Commit | Line | Data |
---|---|---|
88b3ccf2 KB |
1 | .\" Copyright (c) 1983 The Regents of the University of California. |
2 | .\" All rights reserved. | |
c24fefdc | 3 | .\" |
88b3ccf2 KB |
4 | .\" Redistribution and use in source and binary forms are permitted |
5 | .\" provided that the above copyright notice and this paragraph are | |
6 | .\" duplicated in all such forms and that any documentation, | |
7 | .\" advertising materials, and other materials related to such | |
8 | .\" distribution and use acknowledge that the software was developed | |
9 | .\" by the University of California, Berkeley. The name of the | |
10 | .\" University may not be used to endorse or promote products derived | |
11 | .\" from this software without specific prior written permission. | |
12 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
13 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
14 | .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
15 | .\" | |
16 | .\" @(#)fcntl.2 6.5 (Berkeley) %G% | |
c24fefdc | 17 | .\" |
4ef918f1 | 18 | .TH FCNTL 2 "" |
c24fefdc KM |
19 | .UC 5 |
20 | .SH NAME | |
21 | fcntl \- file control | |
22 | .SH SYNOPSIS | |
23 | .nf | |
24 | .ft B | |
25 | #include <fcntl.h> | |
26 | .PP | |
27 | .ft B | |
28 | res = fcntl(fd, cmd, arg) | |
29 | int res; | |
30 | int fd, cmd, arg; | |
31 | .ft R | |
32 | .SH DESCRIPTION | |
33 | .I Fcntl | |
34 | provides for control over descriptors. | |
35 | The argument | |
36 | .I fd | |
37 | is a descriptor to be operated on by | |
38 | .I cmd | |
39 | as follows: | |
40 | .TP 15 | |
41 | F_DUPFD | |
42 | Return a new descriptor as follows: | |
43 | .IP | |
44 | Lowest numbered available descriptor greater than or equal to | |
45 | .I arg. | |
46 | .IP | |
47 | Same object references as the original descriptor. | |
48 | .IP | |
49 | New descriptor shares the same file pointer if the object | |
50 | was a file. | |
51 | .IP | |
52 | Same access mode (read, write or read/write). | |
53 | .IP | |
54 | Same file status flags (i.e., both file descriptors | |
55 | share the same file status flags). | |
56 | .IP | |
57 | The close-on-exec flag associated with the new file descriptor | |
58 | is set to remain open across | |
59 | .IR execv (2) | |
60 | system calls. | |
61 | .TP 15 | |
62 | F_GETFD | |
63 | Get the close-on-exec flag associated with the file descriptor | |
64 | .IR fd . | |
65 | If the low-order bit is 0, the file will remain open across | |
66 | .IR exec , | |
67 | otherwise the file will be closed upon execution of | |
68 | .I exec. | |
69 | .TP 15 | |
70 | F_SETFD | |
71 | Set the close-on-exec flag associated with | |
72 | .I fd | |
73 | to the low order bit of | |
74 | .I arg | |
75 | (0 or 1 as above). | |
76 | .TP 15 | |
77 | F_GETFL | |
78 | Get descriptor status flags, as described below. | |
79 | .TP 15 | |
80 | F_SETFL | |
81 | Set descriptor status flags. | |
82 | .TP 15 | |
83 | F_GETOWN | |
84 | Get the process ID or process group | |
85 | currently receiving SIGIO and SIGURG | |
86 | signals; process groups are returned | |
87 | as negative values. | |
88 | .TP | |
89 | F_SETOWN | |
90 | Set the process or process group | |
91 | to receive SIGIO and SIGURG signals; | |
92 | process groups are specified by supplying | |
93 | .I arg | |
94 | as negative, otherwise | |
95 | .I arg | |
96 | is interpreted as a process ID. | |
97 | .LP | |
98 | The flags for the F_GETFL and F_SETFL flags are as follows: | |
99 | .TP 15 | |
100 | FNDELAY | |
101 | Non-blocking I/O; if no data is available to a | |
102 | .I read | |
103 | call, or if a write operation would block, | |
104 | the call returns -1 with the error EWOULDBLOCK. | |
105 | .TP | |
106 | FAPPEND | |
107 | Force each write to append at the end of file; | |
108 | corresponds to the O_APPEND flag of | |
109 | .IR open (2). | |
110 | .TP | |
111 | FASYNC | |
112 | Enable the SIGIO signal to be sent to the process group | |
d4bad45b | 113 | when I/O is possible, e.g., |
c24fefdc KM |
114 | upon availability of data to be read. |
115 | .SH "RETURN VALUE | |
116 | Upon successful completion, the value returned depends on | |
117 | .I cmd | |
118 | as follows: | |
119 | .sp .5v | |
120 | .nf | |
121 | .ta .25i 1.25i | |
122 | F_DUPFD A new file descriptor. | |
123 | F_GETFD Value of flag (only the low-order bit is defined). | |
124 | F_GETFL Value of flags. | |
125 | F_GETOWN Value of file descriptor owner. | |
126 | other Value other than \-1. | |
127 | .fi | |
128 | .sp .5v | |
129 | Otherwise, a value of \-1 is returned and | |
130 | .I errno | |
131 | is set to indicate the error. | |
132 | .SH ERRORS | |
133 | .I Fcntl | |
134 | will fail if one or more of the following are true: | |
135 | .TP 15 | |
136 | [EBADF] | |
137 | .I Fildes | |
138 | is not a valid open file descriptor. | |
139 | .TP 15 | |
140 | [EMFILE] | |
141 | .I Cmd | |
142 | is F_DUPFD and the maximum allowed number of file descriptors are currently | |
143 | open. | |
144 | .TP 15 | |
145 | [EINVAL] | |
146 | .I Cmd | |
147 | is F_DUPFD and | |
148 | .I arg | |
d4bad45b | 149 | is negative or greater than the maximum allowable number |
c24fefdc KM |
150 | (see |
151 | .IR getdtablesize (2)). | |
cae3bf24 MK |
152 | .TP 15 |
153 | [ESRCH] | |
154 | .I Cmd | |
155 | is F_SETOWN and | |
156 | the process ID given as argument is not in use. | |
c24fefdc KM |
157 | .SH "SEE ALSO |
158 | close(2), execve(2), getdtablesize(2), open(2), sigvec(2) | |
159 | .SH BUGS | |
160 | The asynchronous I/O facilities of FNDELAY and FASYNC | |
1df601cf | 161 | are currently available only for tty and socket operations. |