| blob | 7d75901818b786f420650cc4d72a442d7399a811 |
1 .TH FCNTL 2
2 .SH NAME
3 fcntl \- miscellaneous file descriptor control functions
4 .SH SYNOPSIS
5 .nf
6 .ft B
7 #include <fcntl.h>
9 int fcntl(int \fIfd\fP, int \fIcmd\fP, \fR[\fP\fIdata\fP\fR]\fP)
10 .ft P
11 .fi
12 .SH DESCRIPTION
13 .de SP
14 .if t .sp 0.4
15 .if n .sp
16 ..
17 .B Fcntl()
18 performs several file descriptor related functions, like duplicating a file
19 descriptor, setting the "close on exec" attribute, etc. The
20 .I fd
21 argument is the file descriptor to operate on,
22 .I cmd
23 is the command code of the operation to perform, and
24 .I data
25 is an optional argument to give or receive parameters. The command
26 codes and other symbols and types are declared in <fcntl.h>. The commands
27 are:
28 .SP
29 .BI "fcntl(" fd ", F_DUPFD, int " fd2 ")"
30 .RS
31 Returns a new file descriptor that is a duplicate of file descriptor
32 .IR fd .
33 It shares the same file pointer and the same file status flags, but has
34 separate file descriptor flags that are initially off. The value of the
35 duplicate file descriptor is the first free file descriptor greater than
36 or equal to
37 .IR fd2 .
38 .RE
39 .SP
40 .BI "fcntl(" fd ", F_DUPFD_CLOEXEC, int " fd2 ")"
41 .RS
42 As
43 .BR F_DUPFD ,
44 but the "close on exec" flag is set on the returned file descriptor.
45 .RE
46 .SP
47 .BI "fcntl(" fd ", F_GETFD)"
48 .RS
49 Returns the file descriptor flags associated with file descriptor
50 .IR fd .
51 The flags are the "close on exec" flag
52 .B FD_CLOEXEC
53 that, when set, causes the file descriptor to be closed when the process
54 executes another program. The Minix-vmd specific
55 .B FD_ASYNCHIO
56 flag marks a file descriptor for asynchronous I/O operation.
57 .RE
58 .SP
59 .BI "fcntl(" fd ", F_SETFD, int " flags ")"
60 .RS
61 Set the file descriptor flags of
62 .I fd
63 to
64 .IR flags .
65 .RE
66 .SP
67 .BI "fcntl(" fd ", F_GETFL)"
68 .RS
69 Return the file status flags and file access modes associated with the file
70 associated with file descriptor
71 .IR fd .
72 The file status flags are
73 .B O_NONBLOCK
74 (non blocking I/O) and
75 .B O_APPEND
76 (append mode). The file access modes are
77 .B O_RDONLY
78 (read-only),
79 .B O_WRONLY
80 (write-only) and
81 .B O_RDWR
82 (read-write). These flags are also used in the second argument of
83 .BR open (2).
84 .RE
85 .SP
86 .BI "fcntl(" fd ", F_SETFL, int " flags ")"
87 .RS
88 Set the file status flags of the file referenced by
89 .I fd
90 to
91 .IR flags .
92 Only
93 .B O_NONBLOCK
94 and
95 .B O_APPEND
96 may be changed. Access mode flags are ignored.
97 .RE
98 .SP
99 The next four commands use a parameter of type
100 .B struct flock
101 that is defined in <fcntl.h> as:
102 .SP
103 .RS
104 .nf
105 .ta +4n +8n +12n
106 struct flock {
107 short l_type; /* F_RDLCK, F_WRLCK, or F_UNLCK */
108 short l_whence; /* SEEK_SET, SEEK_CUR, or SEEK_END */
109 off_t l_start; /* byte offset to start of segment */
110 off_t l_len; /* length of segment */
111 pid_t l_pid; /* process id of the locks' owner */
112 };
113 .fi
114 .RE
115 .SP
116 This structure describes a segment of a file.
117 .B L_type
118 is the lock operation performed on the file segment:
119 .B F_RDLCK
120 to set a read lock,
121 .B F_WRLCK
122 to set a write lock, and
123 .B F_UNLCK
124 to remove a lock. Several processes may have a read lock on a segment, but
125 only one process can have a write lock.
126 .B L_whence
127 tells if the
128 .B l_start
129 offset must be interpreted from the start of the file
130 .RB ( SEEK_SET ),
131 the current file position
132 .RB ( SEEK_CUR ),
133 or the end of the file
134 .RB ( SEEK_END ).
135 This is analogous to the third parameter of
136 .BR lseek (2).
137 These
138 .B SEEK_*
139 symbols are declared in <unistd.h>.
140 .B L_start
141 is the starting offset of the segment of the file.
142 .B L_end
143 is the length of the segment. If zero then the segment extends until end of
144 file.
145 .B L_pid
146 is the process-id of the process currently holding a lock on the segment.
147 It is returned by
148 .BR F_GETLK .
149 .SP
150 .BI "fcntl(" fd ", F_GETLK, struct flock *" lkp ")"
151 .RS
152 Find out if some other process has a lock on a segment of the file
153 associated by file descriptor
154 .I fd
155 that overlaps with the segment described by the
156 .B flock
157 structure pointed to by
158 .IR lkp .
159 If the segment is not locked then
160 .B l_type
161 is set to
162 .BR F_UNLCK .
163 Otherwise an
164 .B flock
165 structure is returned through
166 .I lkp
167 that describes the lock held by the other process.
168 .B L_start
169 is set relative to the start of the file.
170 .RE
171 .SP
172 .BI "fcntl(" fd ", F_SETLK, struct flock *" lkp ")"
173 .RS
174 Register a lock on a segment of the file associated with file descriptor
175 .IR fd .
176 The file segment is described by the
177 .B struct flock
178 pointed to by
179 .IR lkp .
180 This call returns an error if any part of the segment is already locked.
181 .RE
182 .SP
183 .BI "fcntl(" fd ", F_SETLKW, struct flock *" lkp ")"
184 .RS
185 Register a lock on a segment of the file associated with file descriptor
186 .IR fd .
187 The file segment is described by the
188 .B struct flock
189 pointed to by
190 .IR lkp .
191 This call blocks waiting for the lock to be released if any part of the
192 segment is already locked.
193 .RE
194 .SP
195 .BI "fcntl(" fd ", F_FREESP, struct flock *" lkp ")"
196 .RS
197 This call frees a segment of disk space occupied by the
198 file associated with file descriptor
199 .IR fd .
200 The segment is described by the
201 .B struct flock
202 pointed to by
203 .IR lkp .
204 The file is truncated in length to the byte position indicated by
205 .B l_start
206 if
207 .B l_len
208 is zero. If
209 .B l_len
210 is nonzero then the file keeps its size, but the freed bytes now read as
211 zeros. (Other than sharing the flock structure, this call has nothing to do
212 with locking.) (This call is common among UNIX(-like) systems.)
213 .RE
214 .SP
215 .BI "fcntl(" fd ", F_SEEK, u64_t " pos ")"
216 .RS
217 This Minix-vmd specific call sets the file position of the file associated
218 with file descriptor
219 .I fd
220 to the byte offset indicated by the 64-bit number
221 .IR pos .
222 This is analogous to the call
223 .SP
224 .RS
225 .BI "lseek(" fd ", " pos ", SEEK_SET)"
226 .RE
227 .SP
228 except that
229 .B F_SEEK
230 can be used on devices larger than 4 gigabyte.
231 .RE
232 .SH "SEE ALSO"
233 .BR open (2),
234 .BR dup (2),
235 .BR lseek (2),
236 .BR ftruncate (3),
237 .BR int64 (3).
238 .SH DIAGNOSTICS
239 .B Fcntl
240 returns a file descriptor, flags, or
241 .B 0
242 to indicate success. On error
243 .B \-1
244 is returned, with
245 .B errno
246 set to the appropriate error code. The most notable errors are:
247 .TP 5
248 .B EINTR
249 If a blocked
250 .B F_SETLKW
251 operation is interrupted by a signal that is caught.
252 .TP
253 .B EAGAIN
254 By
255 .B F_SETLK
256 if a segment cannot be locked.
257 .TP
258 .B EBADF
259 A bad file descriptor in general, or an attempt to place a write lock on a
260 file that is not open for writing, etc.
261 .TP
262 .B ENOLCK
263 No locks available, the file system code has run out of internal table
264 space.
265 .SH AUTHOR
266 Kees J. Bot <kjb@cs.vu.nl>
268 .\"
269 .\" $PchId: fcntl.2,v 1.2 2000/08/11 19:39:51 philip Exp $