Commit | Line | Data |
---|---|---|
88b3ccf2 KB |
1 | .\" Copyright (c) 1983 The Regents of the University of California. |
2 | .\" All rights reserved. | |
c24fefdc | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
88b3ccf2 | 5 | .\" |
bc422869 | 6 | .\" @(#)fcntl.2 6.11 (Berkeley) %G% |
c24fefdc | 7 | .\" |
931b8415 CL |
8 | .Dd |
9 | .Dt FCNTL 2 | |
10 | .Os BSD 4.2 | |
11 | .Sh NAME | |
12 | .Nm fcntl | |
13 | .Nd file control | |
14 | .Sh SYNOPSIS | |
ac6404fc | 15 | .Fd #include <fcntl.h> |
931b8415 CL |
16 | .Ft int |
17 | .Fn fcntl "int fd" "int cmd" "int arg" | |
18 | .Sh DESCRIPTION | |
19 | .Fn Fcntl | |
c24fefdc KM |
20 | provides for control over descriptors. |
21 | The argument | |
931b8415 | 22 | .Fa fd |
c24fefdc | 23 | is a descriptor to be operated on by |
931b8415 | 24 | .Fa cmd |
c24fefdc | 25 | as follows: |
931b8415 CL |
26 | .Bl -tag -width F_GETOWNX |
27 | .It Dv F_DUPFD | |
c24fefdc | 28 | Return a new descriptor as follows: |
931b8415 CL |
29 | .Pp |
30 | .Bl -bullet -compact -offset 4n | |
31 | .It | |
c24fefdc | 32 | Lowest numbered available descriptor greater than or equal to |
931b8415 CL |
33 | .Fa arg . |
34 | .It | |
c24fefdc | 35 | Same object references as the original descriptor. |
931b8415 CL |
36 | .It |
37 | New descriptor shares the same file offset if the object | |
c24fefdc | 38 | was a file. |
931b8415 | 39 | .It |
c24fefdc | 40 | Same access mode (read, write or read/write). |
931b8415 | 41 | .It |
c24fefdc KM |
42 | Same file status flags (i.e., both file descriptors |
43 | share the same file status flags). | |
931b8415 | 44 | .It |
c24fefdc KM |
45 | The close-on-exec flag associated with the new file descriptor |
46 | is set to remain open across | |
931b8415 | 47 | .Xr execv 2 |
c24fefdc | 48 | system calls. |
931b8415 CL |
49 | .El |
50 | .It Dv F_GETFD | |
c24fefdc | 51 | Get the close-on-exec flag associated with the file descriptor |
931b8415 CL |
52 | .Fa fd . |
53 | If the low-order bit of the returned value is 0, | |
54 | the file will remain open across | |
55 | .Fn exec , | |
c24fefdc | 56 | otherwise the file will be closed upon execution of |
931b8415 CL |
57 | .Fn exec |
58 | .Fa ( arg | |
59 | is ignored). | |
60 | .It Dv F_SETFD | |
c24fefdc | 61 | Set the close-on-exec flag associated with |
931b8415 | 62 | .Fa fd |
c24fefdc | 63 | to the low order bit of |
931b8415 | 64 | .Fa arg |
c24fefdc | 65 | (0 or 1 as above). |
931b8415 CL |
66 | .It Dv F_GETFL |
67 | Get descriptor status flags, as described below | |
68 | .Fa ( arg | |
69 | is ignored). | |
70 | .It Dv F_SETFL | |
71 | Set descriptor status flags to | |
72 | .Fa arg . | |
73 | .It Dv F_GETOWN | |
c24fefdc | 74 | Get the process ID or process group |
931b8415 CL |
75 | currently receiving |
76 | .Dv SIGIO | |
77 | and | |
78 | .Dv SIGURG | |
c24fefdc | 79 | signals; process groups are returned |
931b8415 CL |
80 | as negative values |
81 | .Fa ( arg | |
82 | is ignored). | |
83 | .It Dv F_SETOWN | |
c24fefdc | 84 | Set the process or process group |
931b8415 CL |
85 | to receive |
86 | .Dv SIGIO | |
87 | and | |
88 | .Dv SIGURG | |
89 | signals; | |
c24fefdc | 90 | process groups are specified by supplying |
931b8415 | 91 | .Fa arg |
c24fefdc | 92 | as negative, otherwise |
931b8415 | 93 | .Fa arg |
c24fefdc | 94 | is interpreted as a process ID. |
931b8415 CL |
95 | .El |
96 | .Pp | |
97 | The flags for the | |
98 | .Dv F_GETFL | |
99 | and | |
100 | .Dv F_SETFL | |
101 | flags are as follows: | |
bc422869 | 102 | .Bl -tag -width O_NONBLOCKX |
d9927876 | 103 | .It Dv O_NONBLOCK |
c24fefdc | 104 | Non-blocking I/O; if no data is available to a |
931b8415 CL |
105 | .Xr read |
106 | call, or if a | |
107 | .Xr write | |
108 | operation would block, | |
109 | the read or write call returns -1 with the error | |
3a2b8980 | 110 | .Er EAGAIN . |
931b8415 | 111 | .It Dv O_APPEND |
c24fefdc | 112 | Force each write to append at the end of file; |
931b8415 CL |
113 | corresponds to the |
114 | .Dv O_APPEND | |
115 | flag of | |
116 | .Xr open 2 . | |
117 | .It Dv O_ASYNC | |
118 | Enable the | |
119 | .Dv SIGIO | |
120 | signal to be sent to the process group | |
d4bad45b | 121 | when I/O is possible, e.g., |
c24fefdc | 122 | upon availability of data to be read. |
931b8415 | 123 | .El |
bc422869 KM |
124 | .Pp |
125 | Several commands are available for doing advisory file locking; | |
126 | they all operate on the following structure: | |
127 | .Bd -literal | |
128 | struct flock { | |
129 | off_t l_start; /* starting offset */ | |
130 | off_t l_len; /* len = 0 means until end of file */ | |
131 | pid_t l_pid; /* lock owner */ | |
132 | short l_type; /* lock type: read/write, etc. */ | |
133 | short l_whence; /* type of l_start */ | |
134 | }; | |
135 | .Ed | |
136 | The commands available for advisory record locking are as follows: | |
137 | .Bl -tag -width F_SETLKWX | |
138 | .It Dv F_GETLK | |
139 | Get the first lock that blocks the lock description pointed to by the | |
140 | third argument, | |
141 | .Fa arg , | |
142 | taken as a pointer to a | |
143 | .Fa "struct flock" | |
144 | (see above). | |
145 | The information retrieved overwrites the information passed to | |
146 | .Nm fcntl | |
147 | in the | |
148 | .Fa flock | |
149 | structure. | |
150 | If no lock is found that would prevent this lock from being created, | |
151 | the structure is left unchanged by this function call except for the | |
152 | lock type which is set to | |
153 | .Dv F_UNLCK . | |
154 | .It Dv F_SETLK | |
155 | Set or clear a file segment lock according to the lock description | |
156 | pointed to by the third argument, | |
157 | .Fa arg , | |
158 | taken as a pointer to a | |
159 | .Fa "struct flock" | |
160 | (see above). | |
161 | .Dv F_SETLK | |
162 | is used to establish shared (or read) locks | |
163 | .Dv (F_RDLCK) | |
164 | or exclusive (or write) locks, | |
165 | .Dv (F_WRLCK) , | |
166 | as well as remove either type of lock | |
167 | .Dv (F_UNLCK) . | |
168 | If a shared or exclusive lock cannot be set, | |
169 | .Nm fcntl | |
170 | returns immediately with | |
171 | .Er EACCES . | |
172 | .It Dv F_SETLKW | |
173 | This command is the same as | |
174 | .Dv F_SETLK | |
175 | except that if a shared or exclusive lock is blocked by other locks, | |
176 | the process waits until the request can be satisfied. | |
177 | If a signal that is to be caught is received while | |
178 | .Nm fcntl | |
179 | is waiting for a region, the | |
180 | .Nm fcntl | |
181 | will be interrupted if the signal handler has not specified the | |
182 | .Dv SA_RESTART | |
183 | (see | |
184 | .Xr sigaction 2 ) . | |
185 | .El | |
186 | .Pp | |
187 | When a shared lock has been set on a segment of a file, | |
188 | other processes can set shared locks on that segment | |
189 | or a portion of it. | |
190 | A shared lock prevents any other process from setting an exclusive | |
191 | lock on any portion of the protected area. | |
192 | A request for a shared lock fails if the file descriptor was not | |
193 | opened with read access. | |
194 | .Pp | |
195 | An exclusive lock prevents any other process from setting a shared lock or | |
196 | an exclusive lock on any portion of the protected area. | |
197 | A request for an exclusive lock fails if the file was not | |
198 | opened with write access. | |
199 | .Pp | |
200 | The value of | |
201 | .Fa l_whence | |
202 | is | |
203 | .Dv SEEK_SET , | |
204 | .Dv SEEK_CUR , | |
205 | or | |
206 | .Dv SEEK_END | |
207 | to indicate that the relative offset, | |
208 | .Fa l_start | |
209 | bytes, will be measured from the start of the file, | |
210 | current position, or end of the file, respectively. | |
211 | The value of | |
212 | .Fa l_len | |
213 | is the number of consecutive bytes to be locked. | |
214 | If | |
215 | .Fa l_len | |
216 | is negative, the result is undefined. | |
217 | The | |
218 | .Fa l_pid | |
219 | field is only used with | |
220 | .Dv F_GETLK | |
221 | to return the process ID of the process holding a blocking lock. | |
222 | After a successful | |
223 | .Dv F_GETLK | |
224 | request, the value of | |
225 | .Fa l_whence | |
226 | is | |
227 | .Dv SEEK_SET . | |
228 | .Pp | |
229 | Locks may start and extend beyond the current end of a file, | |
230 | but may not start or extend before the beginning of the file. | |
231 | A lock is set to extend to the largest possible value of the | |
232 | file offset for that file if | |
233 | .Fa l_len | |
234 | is set to zero. If | |
235 | .Fa l_whence | |
236 | and | |
237 | .Fa l_start | |
238 | point to the beginning of the file, and | |
239 | .Fa l_len | |
240 | is zero, the entire file is locked. | |
241 | If an application wishes only to do entire file locking, the | |
242 | .Xr flock 2 | |
243 | system call is much more efficient. | |
244 | .Pp | |
245 | There is at most one type of lock set for each byte in the file. | |
246 | Before a successful return from an | |
247 | .Dv F_SETLK | |
248 | or an | |
249 | .Dv F_SETLKW | |
250 | request when the calling process has previously existing locks | |
251 | on bytes in the region specified by the request, | |
252 | the previous lock type for each byte in the specified | |
253 | region is replaced by the new lock type. | |
254 | As specified above under the descriptions | |
255 | of shared locks and exclusive locks, an | |
256 | .Dv F_SETLK | |
257 | or an | |
258 | .Dv F_SETLKW | |
259 | request fails or blocks respectively when another process has existing | |
260 | locks on bytes in the specified region and the type of any of those | |
261 | locks conflicts with the type specified in the request. | |
262 | .Pp | |
263 | This interface follows the completely stupid semantics of System V and | |
264 | .St -p1003.1-88 | |
265 | that require that all locks associated with a file for a given process are | |
266 | removed when \fIany\fP file descriptor for that file is closed by that process. | |
267 | This semantic means that applications must be aware of any files that | |
268 | a subroutine library may access. | |
269 | For example if an application for updating the password file locks the | |
270 | password file database while making the update, and then calls | |
271 | .Xr getpwname 3 | |
272 | to retrieve a record, | |
273 | the lock will be lost because | |
274 | .Xr getpwname 3 | |
275 | opens, reads, and closes the password database. | |
276 | The database close will release all locks that the process has | |
277 | associated with the database, even if the library routine never | |
278 | requested a lock on the database. | |
279 | Another minor semantic problem with this interface is that | |
280 | locks are not inherited by a child process created using the | |
281 | .Xr fork 2 | |
282 | function. | |
283 | The | |
284 | .Xr flock 2 | |
285 | interface has much more rational last close semantics and | |
286 | allows locks to be inherited by child processes. | |
287 | .Xr Flock 2 | |
288 | is recommended for applications that want to ensure the integrity | |
289 | of their locks when using library routines or wish to pass locks | |
290 | to their children. | |
291 | Note that | |
292 | .Xr flock 2 | |
293 | and | |
294 | .Xr fcntl 2 | |
295 | locks may be safely used concurrently. | |
296 | .Pp | |
297 | All locks associated with a file for a given process are | |
298 | removed when the process terminates. | |
299 | .Pp | |
300 | A potential for deadlock occurs if a process controlling a locked region | |
301 | is put to sleep by attempting to lock the locked region of another process. | |
302 | This implementation detects that sleeping until a locked region is unlocked | |
303 | would cause a deadlock and fails with an | |
304 | .Er EDEADLK | |
305 | error. | |
931b8415 | 306 | .Sh RETURN VALUES |
c24fefdc | 307 | Upon successful completion, the value returned depends on |
931b8415 | 308 | .Fa cmd |
c24fefdc | 309 | as follows: |
931b8415 CL |
310 | .Bl -tag -width F_GETOWNX -offset indent |
311 | .It Dv F_DUPFD | |
312 | A new file descriptor. | |
313 | .It Dv F_GETFD | |
314 | Value of flag (only the low-order bit is defined). | |
315 | .It Dv F_GETFL | |
316 | Value of flags. | |
317 | .It Dv F_GETOWN | |
318 | Value of file descriptor owner. | |
319 | .It other | |
320 | Value other than -1. | |
321 | .El | |
322 | .Pp | |
323 | Otherwise, a value of -1 is returned and | |
324 | .Va errno | |
c24fefdc | 325 | is set to indicate the error. |
931b8415 CL |
326 | .Sh ERRORS |
327 | .Fn Fcntl | |
328 | will fail if: | |
329 | .Bl -tag -width Er | |
bc422869 KM |
330 | .It Bq Er EACCES |
331 | The argument | |
332 | .Fa arg | |
333 | is | |
334 | .Dv F_SETLK , | |
335 | the type of lock | |
336 | .Fa (l_type) | |
337 | is a shared lock | |
338 | .Dv (F_RDLCK) | |
339 | or exclusive lock | |
340 | .Dv (F_WRLCK) , | |
341 | and the segment of a file to be locked is already | |
342 | exclusive-locked by another process; | |
343 | or the type is an exclusive lock and some portion of the | |
344 | segment of a file to be locked is already shared-locked or | |
345 | exclusive-locked by another process. | |
931b8415 CL |
346 | .It Bq Er EBADF |
347 | .Fa Fildes | |
c24fefdc | 348 | is not a valid open file descriptor. |
bc422869 KM |
349 | .Pp |
350 | The argument | |
351 | .Fa cmd | |
352 | is | |
353 | .Dv F_SETLK | |
354 | or | |
355 | .Dv F_SETLKW , | |
356 | the type of lock | |
357 | .Fa (l_type) | |
358 | is a shared lock | |
359 | .Dv (F_RDLCK) , | |
360 | and | |
361 | .Fa fildes | |
362 | is not a valid file descriptor open for reading. | |
363 | .Pp | |
364 | The argument | |
365 | .Fa cmd | |
366 | is | |
367 | .Dv F_SETLK | |
368 | or | |
369 | .Dv F_SETLKW , | |
370 | the type of lock | |
371 | .Fa (l_type) | |
372 | is an exclusive lock | |
373 | .Dv (F_WRLCK) , | |
374 | and | |
375 | .Fa fildes | |
376 | is not a valid file descriptor open for writing. | |
931b8415 CL |
377 | .It Bq Er EMFILE |
378 | .Fa Cmd | |
379 | is | |
380 | .Dv F_DUPFD | |
381 | and the maximum allowed number of file descriptors are currently | |
c24fefdc | 382 | open. |
bc422869 KM |
383 | .It Bq Er EDEADLK |
384 | The argument | |
385 | .Fa cmd | |
386 | is | |
387 | .Dv F_SETLKW , | |
388 | and a deadlock condition was detected. | |
389 | .It Bq Er EINTR | |
390 | The argument | |
391 | .Fa cmd | |
392 | is | |
393 | .Dv F_SETLKW , | |
394 | and the function was interrupted by a signal. | |
931b8415 CL |
395 | .It Bq Er EINVAL |
396 | .Fa Cmd | |
397 | is | |
398 | .Dv F_DUPFD | |
399 | and | |
400 | .Fa arg | |
d4bad45b | 401 | is negative or greater than the maximum allowable number |
c24fefdc | 402 | (see |
931b8415 | 403 | .Xr getdtablesize 2 ) . |
bc422869 KM |
404 | .Pp |
405 | The argument | |
406 | .Fa cmd | |
407 | is | |
408 | .Dv F_GETLK , | |
409 | .Dv F_SETLK , | |
410 | or | |
411 | .Dv F_SETLKW | |
412 | and the data to which | |
413 | .Fa arg | |
414 | points is not valid, or | |
415 | .Fa fildes | |
416 | refers to a file that does not support locking. | |
417 | .It Bq Er EMFILE | |
418 | The argument | |
419 | .Fa cmd | |
420 | is | |
421 | .Dv F_DUPED | |
422 | and the maximum number of file descriptors permitted for the | |
423 | process are already in use, | |
424 | or no file descriptors greater than or equal to | |
425 | .Fa arg | |
426 | are available. | |
427 | .It Bq Er ENOLCK | |
428 | The argument | |
429 | .Fa cmd | |
430 | is | |
431 | .Dv F_SETLK | |
432 | or | |
433 | .Dv F_SETLKW , | |
434 | and satisfying the lock or unlock request would result in the | |
435 | number of locked regions in the system exceeding a system-imposed limit. | |
931b8415 CL |
436 | .It Bq Er ESRCH |
437 | .Fa Cmd | |
438 | is | |
439 | .Dv F_SETOWN | |
440 | and | |
cae3bf24 | 441 | the process ID given as argument is not in use. |
931b8415 CL |
442 | .El |
443 | .Sh SEE ALSO | |
444 | .Xr close 2 , | |
445 | .Xr execve 2 , | |
bc422869 | 446 | .Xr flock 2 , |
931b8415 CL |
447 | .Xr getdtablesize 2 , |
448 | .Xr open 2 , | |
449 | .Xr sigvec 2 | |
450 | .Sh BUGS | |
451 | The asynchronous I/O facilities of | |
452 | .Dv FNDELAY | |
453 | and | |
454 | .Dv FASYNC | |
1df601cf | 455 | are currently available only for tty and socket operations. |
931b8415 CL |
456 | .Sh HISTORY |
457 | The | |
458 | .Nm | |
459 | function call appeared in | |
460 | .Bx 4.2 . |