]>
Commit | Line | Data |
---|---|---|
1 | .\" | |
2 | .\" Copyright (c) 2011 Apple Inc. All rights reserved. | |
3 | .\" | |
4 | .\" @APPLE_LICENSE_HEADER_START@ | |
5 | .\" | |
6 | .\" This file contains Original Code and/or Modifications of Original Code | |
7 | .\" as defined in and that are subject to the Apple Public Source License | |
8 | .\" Version 2.0 (the 'License'). You may not use this file except in | |
9 | .\" compliance with the License. Please obtain a copy of the License at | |
10 | .\" http://www.opensource.apple.com/apsl/ and read it before using this | |
11 | .\" file. | |
12 | .\" | |
13 | .\" The Original Code and all software distributed under the License are | |
14 | .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER | |
15 | .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, | |
16 | .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, | |
17 | .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. | |
18 | .\" Please see the License for the specific language governing rights and | |
19 | .\" limitations under the License. | |
20 | .\" | |
21 | .\" @APPLE_LICENSE_HEADER_END@ | |
22 | .\" | |
23 | .\" | |
24 | .\" $NetBSD: fcntl.2,v 1.6 1995/02/27 12:32:29 cgd Exp $ | |
25 | .\" | |
26 | .\" Copyright (c) 1983, 1993 | |
27 | .\" The Regents of the University of California. All rights reserved. | |
28 | .\" | |
29 | .\" Redistribution and use in source and binary forms, with or without | |
30 | .\" modification, are permitted provided that the following conditions | |
31 | .\" are met: | |
32 | .\" 1. Redistributions of source code must retain the above copyright | |
33 | .\" notice, this list of conditions and the following disclaimer. | |
34 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
35 | .\" notice, this list of conditions and the following disclaimer in the | |
36 | .\" documentation and/or other materials provided with the distribution. | |
37 | .\" 3. All advertising materials mentioning features or use of this software | |
38 | .\" must display the following acknowledgement: | |
39 | .\" This product includes software developed by the University of | |
40 | .\" California, Berkeley and its contributors. | |
41 | .\" 4. Neither the name of the University nor the names of its contributors | |
42 | .\" may be used to endorse or promote products derived from this software | |
43 | .\" without specific prior written permission. | |
44 | .\" | |
45 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
46 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
47 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
48 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
49 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
50 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
51 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
52 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
53 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
54 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
55 | .\" SUCH DAMAGE. | |
56 | .\" | |
57 | .\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94 | |
58 | .\" | |
59 | .Dd August 24, 2017 | |
60 | .Dt FCNTL 2 | |
61 | .Os BSD 4.2 | |
62 | .Sh NAME | |
63 | .Nm fcntl | |
64 | .Nd file control | |
65 | .Sh SYNOPSIS | |
66 | .Fd #include <fcntl.h> | |
67 | .Ft int | |
68 | .Fo fcntl | |
69 | .Fa "int fildes" | |
70 | .Fa "int cmd" | |
71 | .Fa "..." | |
72 | .Fc | |
73 | .Sh DESCRIPTION | |
74 | .Fn fcntl | |
75 | provides for control over descriptors. | |
76 | The argument | |
77 | .Fa fildes | |
78 | is a descriptor to be operated on by | |
79 | .Fa cmd | |
80 | as follows: | |
81 | .Bl -tag -width F_WRITEBOOTSTRAPX | |
82 | .It Dv F_DUPFD | |
83 | Return a new descriptor as follows: | |
84 | .Pp | |
85 | .Bl -bullet -compact -offset 4n | |
86 | .It | |
87 | Lowest numbered available descriptor greater than or equal to | |
88 | .Fa arg . | |
89 | .It | |
90 | Same object references as the original descriptor. | |
91 | .It | |
92 | New descriptor shares the same file offset if the object | |
93 | was a file. | |
94 | .It | |
95 | Same access mode (read, write or read/write). | |
96 | .It | |
97 | Same file status flags (i.e., both file descriptors | |
98 | share the same file status flags). | |
99 | .It | |
100 | The close-on-exec flag associated with the new file descriptor | |
101 | is cleared so that the descriptor remains open across an | |
102 | .Xr execv 2 | |
103 | system call. | |
104 | .El | |
105 | .It Dv F_DUPFD_CLOEXEC | |
106 | Like | |
107 | .Dv F_DUPFD , | |
108 | except that the close-on-exec flag associated with the new file descriptor | |
109 | is set. | |
110 | .It Dv F_GETFD | |
111 | Get the flags associated with the file descriptor | |
112 | .Fa fildes , | |
113 | as described below | |
114 | .Fa ( arg | |
115 | is ignored). | |
116 | .It Dv F_SETFD | |
117 | Set the file descriptor flags to | |
118 | .Fa arg . | |
119 | .It Dv F_GETFL | |
120 | Get descriptor status flags, as described below | |
121 | .Fa ( arg | |
122 | is ignored). | |
123 | .It Dv F_SETFL | |
124 | Set descriptor status flags to | |
125 | .Fa arg . | |
126 | .It Dv F_GETOWN | |
127 | Get the process ID or process group | |
128 | currently receiving | |
129 | .Dv SIGIO | |
130 | and | |
131 | .Dv SIGURG | |
132 | signals; process groups are returned | |
133 | as negative values | |
134 | .Fa ( arg | |
135 | is ignored). | |
136 | .It Dv F_SETOWN | |
137 | Set the process or process group | |
138 | to receive | |
139 | .Dv SIGIO | |
140 | and | |
141 | .Dv SIGURG | |
142 | signals; | |
143 | process groups are specified by supplying | |
144 | .Fa arg | |
145 | as negative, otherwise | |
146 | .Fa arg | |
147 | is interpreted as a process ID. | |
148 | .It Dv F_GETPATH | |
149 | Get the path of the file descriptor | |
150 | .Fa Fildes . | |
151 | The argument must be a buffer of size | |
152 | .Sy MAXPATHLEN | |
153 | or greater. | |
154 | .It Dv F_PREALLOCATE | |
155 | Preallocate file storage space. Note: upon success, | |
156 | the space that is allocated can be the size requested, | |
157 | larger than the size requested, or (if the | |
158 | .Dv F_ALLOCATEALL | |
159 | flag is not provided) smaller than the space requested. | |
160 | .It Dv F_PUNCHHOLE | |
161 | Deallocate a region and replace it with a hole. Subsequent reads of the | |
162 | affected region will return bytes of zeros that are usually not backed by | |
163 | physical blocks. This will not change the actual file size. Holes must be | |
164 | aligned to file system block boundaries. This will fail on | |
165 | file systems that do not support this interface. | |
166 | .It Dv F_SETSIZE | |
167 | Truncate a file without zeroing space. | |
168 | The calling process must have root privileges. | |
169 | .It Dv F_RDADVISE | |
170 | Issue an advisory read async with no copy to user. | |
171 | .It Dv F_RDAHEAD | |
172 | Turn read ahead off/on. | |
173 | A zero value in | |
174 | .Fa arg | |
175 | disables read ahead. | |
176 | A non-zero value in | |
177 | .Fa arg | |
178 | turns read ahead on. | |
179 | .It Dv F_READBOOTSTRAP | |
180 | Read bootstrap from disk. | |
181 | .It Dv F_WRITEBOOTSTRAP | |
182 | Write bootstrap on disk. | |
183 | The calling process must have root privileges. | |
184 | .It Dv F_NOCACHE | |
185 | Turns data caching off/on. A non-zero value in | |
186 | .Fa arg | |
187 | turns data caching off. | |
188 | A value of zero in | |
189 | .Fa arg | |
190 | turns data caching on. | |
191 | .It Dv F_LOG2PHYS | |
192 | Get disk device information. | |
193 | Currently this only returns the | |
194 | disk device address that corresponds | |
195 | to the current file offset. Note that the system | |
196 | may return -1 as the disk device address if the file is not | |
197 | backed by physical blocks. This is subject | |
198 | to change. | |
199 | .It Dv F_LOG2PHYS_EXT | |
200 | Variant of F_LOG2PHYS that uses the passed in | |
201 | file offset and length. | |
202 | .It Dv F_FULLFSYNC | |
203 | Does the same thing as | |
204 | .Xr fsync 2 | |
205 | then asks the drive to | |
206 | flush all buffered data to | |
207 | the permanent storage device | |
208 | .Fa ( arg | |
209 | is ignored). | |
210 | This is currently implemented on HFS, MS-DOS (FAT), | |
211 | and Universal Disk Format (UDF) file systems. | |
212 | The operation may take quite a while to complete. | |
213 | Certain FireWire drives have also been known | |
214 | to ignore the request to flush their buffered data. | |
215 | .It Dv F_SETNOSIGPIPE | |
216 | Determines whether a | |
217 | .Dv SIGPIPE | |
218 | signal will be generated when a write fails on a pipe or socket for | |
219 | which there is no reader. If | |
220 | .Fa arg | |
221 | is non-zero, | |
222 | .Dv SIGPIPE | |
223 | generation is disabled for descriptor | |
224 | .Fa fildes , | |
225 | while an | |
226 | .Fa arg | |
227 | of zero enables it (the default). | |
228 | .It Dv F_GETNOSIGPIPE | |
229 | Returns whether a | |
230 | .Dv SIGPIPE | |
231 | signal will be generated when a write fails on a pipe or socket | |
232 | for which there is no reader. The semantics of the return value | |
233 | match those of the | |
234 | .Fa arg | |
235 | of | |
236 | .Dv F_SETNOSIGPIPE . | |
237 | .El | |
238 | .Pp | |
239 | The flags for the | |
240 | .Dv F_GETFD | |
241 | and | |
242 | .Dv F_SETFD | |
243 | commands are as follows: | |
244 | .Bl -tag -width FD_CLOEXECX -offset indent | |
245 | .It Dv FD_CLOEXEC | |
246 | Close-on-exec; the given file descriptor will be automatically | |
247 | closed in the successor process image when one of the | |
248 | .Xr execv 2 | |
249 | or | |
250 | .Xr posix_spawn 2 | |
251 | family of system calls is invoked. | |
252 | .El | |
253 | .Pp | |
254 | The flags for the | |
255 | .Dv F_GETFL | |
256 | and | |
257 | .Dv F_SETFL | |
258 | commands are as follows: | |
259 | .Bl -tag -width O_NONBLOCKX -offset indent | |
260 | .It Dv O_NONBLOCK | |
261 | Non-blocking I/O; if no data is available to a | |
262 | .Xr read | |
263 | call, or if a | |
264 | .Xr write | |
265 | operation would block, | |
266 | the read or write call returns -1 with the error | |
267 | .Er EAGAIN . | |
268 | .It Dv O_APPEND | |
269 | Force each write to append at the end of file; | |
270 | corresponds to the | |
271 | .Dv O_APPEND | |
272 | flag of | |
273 | .Xr open 2 . | |
274 | .It Dv O_ASYNC | |
275 | Enable the | |
276 | .Dv SIGIO | |
277 | signal to be sent to the process group | |
278 | when I/O is possible, e.g., | |
279 | upon availability of data to be read. | |
280 | .El | |
281 | .Pp | |
282 | Several commands are available for doing advisory file locking; | |
283 | they all operate on the following structure: | |
284 | .ne 7v | |
285 | .Bd -literal | |
286 | struct flock { | |
287 | off_t l_start; /* starting offset */ | |
288 | off_t l_len; /* len = 0 means until end of file */ | |
289 | pid_t l_pid; /* lock owner */ | |
290 | short l_type; /* lock type: read/write, etc. */ | |
291 | short l_whence; /* type of l_start */ | |
292 | }; | |
293 | .Ed | |
294 | .Pp | |
295 | The commands available for advisory record locking are as follows: | |
296 | .Bl -tag -width F_SETLKWX | |
297 | .It Dv F_GETLK | |
298 | Get the first lock that blocks the lock description pointed to by the | |
299 | third argument, | |
300 | .Fa arg , | |
301 | taken as a pointer to a | |
302 | .Fa "struct flock" | |
303 | (see above). | |
304 | The information retrieved overwrites the information passed to | |
305 | .Nm fcntl | |
306 | in the | |
307 | .Fa flock | |
308 | structure. | |
309 | If no lock is found that would prevent this lock from being created, | |
310 | the structure is left unchanged by this function call except for the | |
311 | lock type which is set to | |
312 | .Dv F_UNLCK . | |
313 | .It Dv F_SETLK | |
314 | Set or clear a file segment lock according to the lock description | |
315 | pointed to by the third argument, | |
316 | .Fa arg , | |
317 | taken as a pointer to a | |
318 | .Fa "struct flock" | |
319 | (see above). | |
320 | .Dv F_SETLK | |
321 | is used to establish shared (or read) locks | |
322 | .Dv (F_RDLCK) | |
323 | or exclusive (or write) locks, | |
324 | .Dv (F_WRLCK) , | |
325 | as well as remove either type of lock | |
326 | .Dv (F_UNLCK) . | |
327 | If a shared or exclusive lock cannot be set, | |
328 | .Nm fcntl | |
329 | returns immediately with | |
330 | .Er EAGAIN . | |
331 | .It Dv F_SETLKW | |
332 | This command is the same as | |
333 | .Dv F_SETLK | |
334 | except that if a shared or exclusive lock is blocked by other locks, | |
335 | the process waits until the request can be satisfied. | |
336 | If a signal that is to be caught is received while | |
337 | .Nm fcntl | |
338 | is waiting for a region, the | |
339 | .Nm fcntl | |
340 | will be interrupted if the signal handler has not specified the | |
341 | .Dv SA_RESTART | |
342 | (see | |
343 | .Xr sigaction 2 ) . | |
344 | .El | |
345 | .Pp | |
346 | When a shared lock has been set on a segment of a file, | |
347 | other processes can set shared locks on that segment | |
348 | or a portion of it. | |
349 | A shared lock prevents any other process from setting an exclusive | |
350 | lock on any portion of the protected area. | |
351 | A request for a shared lock fails if the file descriptor was not | |
352 | opened with read access. | |
353 | .Pp | |
354 | An exclusive lock prevents any other process from setting a shared lock or | |
355 | an exclusive lock on any portion of the protected area. | |
356 | A request for an exclusive lock fails if the file was not | |
357 | opened with write access. | |
358 | .Pp | |
359 | The value of | |
360 | .Fa l_whence | |
361 | is | |
362 | .Dv SEEK_SET , | |
363 | .Dv SEEK_CUR , | |
364 | or | |
365 | .Dv SEEK_END | |
366 | to indicate that the relative offset, | |
367 | .Fa l_start | |
368 | bytes, will be measured from the start of the file, | |
369 | current position, or end of the file, respectively. | |
370 | The value of | |
371 | .Fa l_len | |
372 | is the number of consecutive bytes to be locked. | |
373 | If | |
374 | .Fa l_len | |
375 | is negative, the result is undefined. | |
376 | The | |
377 | .Fa l_pid | |
378 | field is only used with | |
379 | .Dv F_GETLK | |
380 | to return the process ID of the process holding a blocking lock. | |
381 | After a successful | |
382 | .Dv F_GETLK | |
383 | request, the value of | |
384 | .Fa l_whence | |
385 | is | |
386 | .Dv SEEK_SET . | |
387 | .Pp | |
388 | Locks may start and extend beyond the current end of a file, | |
389 | but may not start or extend before the beginning of the file. | |
390 | A lock is set to extend to the largest possible value of the | |
391 | file offset for that file if | |
392 | .Fa l_len | |
393 | is set to zero. If | |
394 | .Fa l_whence | |
395 | and | |
396 | .Fa l_start | |
397 | point to the beginning of the file, and | |
398 | .Fa l_len | |
399 | is zero, the entire file is locked. | |
400 | If an application wishes only to do entire file locking, the | |
401 | .Xr flock 2 | |
402 | system call is much more efficient. | |
403 | .Pp | |
404 | There is at most one type of lock set for each byte in the file. | |
405 | Before a successful return from an | |
406 | .Dv F_SETLK | |
407 | or an | |
408 | .Dv F_SETLKW | |
409 | request when the calling process has previously existing locks | |
410 | on bytes in the region specified by the request, | |
411 | the previous lock type for each byte in the specified | |
412 | region is replaced by the new lock type. | |
413 | As specified above under the descriptions | |
414 | of shared locks and exclusive locks, an | |
415 | .Dv F_SETLK | |
416 | or an | |
417 | .Dv F_SETLKW | |
418 | request fails or blocks respectively when another process has existing | |
419 | locks on bytes in the specified region and the type of any of those | |
420 | locks conflicts with the type specified in the request. | |
421 | .Pp | |
422 | This interface follows the completely stupid semantics of System V and | |
423 | .St -p1003.1-88 | |
424 | that require that all locks associated with a file for a given process are | |
425 | removed when \fIany\fP file descriptor for that file is closed by that process. | |
426 | This semantic means that applications must be aware of any files that | |
427 | a subroutine library may access. | |
428 | For example if an application for updating the password file locks the | |
429 | password file database while making the update, and then calls | |
430 | .Xr getpwname 3 | |
431 | to retrieve a record, | |
432 | the lock will be lost because | |
433 | .Xr getpwname 3 | |
434 | opens, reads, and closes the password database. | |
435 | The database close will release all locks that the process has | |
436 | associated with the database, even if the library routine never | |
437 | requested a lock on the database. | |
438 | Another minor semantic problem with this interface is that | |
439 | locks are not inherited by a child process created using the | |
440 | .Xr fork 2 | |
441 | function. | |
442 | The | |
443 | .Xr flock 2 | |
444 | interface has much more rational last close semantics and | |
445 | allows locks to be inherited by child processes. | |
446 | .Xr Flock 2 | |
447 | is recommended for applications that want to ensure the integrity | |
448 | of their locks when using library routines or wish to pass locks | |
449 | to their children. | |
450 | Note that | |
451 | .Xr flock 2 | |
452 | and | |
453 | .Xr fcntl 2 | |
454 | locks may be safely used concurrently. | |
455 | .Pp | |
456 | All locks associated with a file for a given process are | |
457 | removed when the process terminates. | |
458 | .Pp | |
459 | A potential for deadlock occurs if a process controlling a locked region | |
460 | is put to sleep by attempting to lock the locked region of another process. | |
461 | This implementation detects that sleeping until a locked region is unlocked | |
462 | would cause a deadlock and fails with an | |
463 | .Er EDEADLK | |
464 | error. | |
465 | .Pp | |
466 | The | |
467 | .Dv F_PREALLOCATE | |
468 | command operates on the following structure: | |
469 | .ne 7v | |
470 | .Bd -literal | |
471 | typedef struct fstore { | |
472 | u_int32_t fst_flags; /* IN: flags word */ | |
473 | int fst_posmode; /* IN: indicates offset field */ | |
474 | off_t fst_offset; /* IN: start of the region */ | |
475 | off_t fst_length; /* IN: size of the region */ | |
476 | off_t fst_bytesalloc; /* OUT: number of bytes allocated */ | |
477 | } fstore_t; | |
478 | .Ed | |
479 | .Pp | |
480 | The flags (fst_flags) for the | |
481 | .Dv F_PREALLOCATE | |
482 | command are as follows: | |
483 | .Bl -tag -width F_ALLOCATECONTIGX -offset indent | |
484 | .It Dv F_ALLOCATECONTIG | |
485 | Allocate contiguous space. | |
486 | .It Dv F_ALLOCATEALL | |
487 | Allocate all requested space or no space at all. | |
488 | .El | |
489 | .Pp | |
490 | The position modes (fst_posmode) for the | |
491 | .Dv F_PREALLOCATE | |
492 | command indicate how to use the offset field. | |
493 | The modes are as follows: | |
494 | .Bl -tag -width F_PEOFPOSMODEX -offset indent | |
495 | .It Dv F_PEOFPOSMODE | |
496 | Allocate from the physical end of file. | |
497 | .It Dv F_VOLPOSMODE | |
498 | Allocate from the volume offset. | |
499 | .El | |
500 | .Pp | |
501 | The | |
502 | .Dv F_PUNCHHOLE | |
503 | command operates on the following structure: | |
504 | .ne 7v | |
505 | .Bd -literal | |
506 | typedef struct fpunchhole { | |
507 | u_int32_t fp_flags; /* unused */ | |
508 | u_int32_t reserved; /* (to maintain 8-byte alignment) */ | |
509 | off_t fp_offset; /* IN: start of the region */ | |
510 | off_t fp_length; /* IN: size of the region */ | |
511 | } fpunchhole_t; | |
512 | .Ed | |
513 | .Pp | |
514 | The | |
515 | .Dv F_RDADVISE | |
516 | command operates on the following structure | |
517 | which holds information passed from the | |
518 | user to the system: | |
519 | .ne 7v | |
520 | .Bd -literal | |
521 | struct radvisory { | |
522 | off_t ra_offset; /* offset into the file */ | |
523 | int ra_count; /* size of the read */ | |
524 | }; | |
525 | .Ed | |
526 | .Pp | |
527 | The | |
528 | .Dv F_READBOOTSTRAP and F_WRITEBOOTSTRAP | |
529 | commands operate on the following structure. | |
530 | .ne 7v | |
531 | .Bd -literal | |
532 | typedef struct fbootstraptransfer { | |
533 | off_t fbt_offset; /* IN: offset to start read/write */ | |
534 | size_t fbt_length; /* IN: number of bytes to transfer */ | |
535 | void *fbt_buffer; /* IN: buffer to be read/written */ | |
536 | } fbootstraptransfer_t; | |
537 | .Ed | |
538 | .Pp | |
539 | The | |
540 | .Dv F_LOG2PHYS | |
541 | command operates on the following structure: | |
542 | .ne 7v | |
543 | .Bd -literal | |
544 | struct log2phys { | |
545 | u_int32_t l2p_flags; /* unused so far */ | |
546 | off_t l2p_contigbytes; /* unused so far */ | |
547 | off_t l2p_devoffset; /* bytes into device */ | |
548 | }; | |
549 | .Ed | |
550 | .Pp | |
551 | The | |
552 | .Dv F_LOG2PHYS_EXT | |
553 | command operates on the same structure as F_LOG2PHYS but treats it as an in/out: | |
554 | .ne 7v | |
555 | .Bd -literal | |
556 | struct log2phys { | |
557 | u_int32_t l2p_flags; /* unused so far */ | |
558 | off_t l2p_contigbytes; /* IN: number of bytes to be queried; | |
559 | OUT: number of contiguous bytes allocated at this position */ | |
560 | off_t l2p_devoffset; /* IN: bytes into file; | |
561 | OUT: bytes into device */ | |
562 | }; | |
563 | .Ed | |
564 | .Pp | |
565 | If | |
566 | .Fa fildes | |
567 | is a socket, then the | |
568 | .Dv F_SETNOSIGPIPE | |
569 | and | |
570 | .Dv F_GETNOSIGPIPE | |
571 | commands are directly analogous, and fully interoperate with the | |
572 | .Dv SO_NOSIGPIPE | |
573 | option of | |
574 | .Xr setsockopt 2 | |
575 | and | |
576 | .Xr getsockopt 2 | |
577 | respectively. | |
578 | .Sh RETURN VALUES | |
579 | Upon successful completion, the value returned depends on | |
580 | .Fa cmd | |
581 | as follows: | |
582 | .Bl -tag -width F_GETOWNX -offset indent | |
583 | .It Dv F_DUPFD | |
584 | A new file descriptor. | |
585 | .It Dv F_GETFD | |
586 | Value of flag (only the low-order bit is defined). | |
587 | .It Dv F_GETFL | |
588 | Value of flags. | |
589 | .It Dv F_GETOWN | |
590 | Value of file descriptor owner. | |
591 | .It other | |
592 | Value other than -1. | |
593 | .El | |
594 | .Pp | |
595 | Otherwise, a value of -1 is returned and | |
596 | .Va errno | |
597 | is set to indicate the error. | |
598 | .Sh ERRORS | |
599 | The | |
600 | .Fn fcntl | |
601 | system call will fail if: | |
602 | .Bl -tag -width Er | |
603 | .\" ========== | |
604 | .It Bq Er EAGAIN | |
605 | The argument | |
606 | .Fa cmd | |
607 | is | |
608 | .Dv F_SETLK , | |
609 | the type of lock | |
610 | .Fa (l_type) | |
611 | is a shared lock | |
612 | .Dv (F_RDLCK) | |
613 | or exclusive lock | |
614 | .Dv (F_WRLCK) , | |
615 | and the segment of a file to be locked is already | |
616 | exclusive-locked by another process; | |
617 | or the type is an exclusive lock and some portion of the | |
618 | segment of a file to be locked is already shared-locked or | |
619 | exclusive-locked by another process. | |
620 | .It Bq Er EACCESS | |
621 | The argument | |
622 | .Fa cmd | |
623 | is either | |
624 | .Dv F_SETSIZE | |
625 | or | |
626 | .Dv F_WRITEBOOTSTRAP | |
627 | and the calling process does not have root privileges. | |
628 | .\" ========== | |
629 | .It Bq Er EBADF | |
630 | .Fa Fildes | |
631 | is not a valid open file descriptor. | |
632 | .Pp | |
633 | The argument | |
634 | .Fa cmd | |
635 | is | |
636 | .Dv F_SETLK | |
637 | or | |
638 | .Dv F_SETLKW , | |
639 | the type of lock | |
640 | .Fa (l_type) | |
641 | is a shared lock | |
642 | .Dv (F_RDLCK) , | |
643 | and | |
644 | .Fa fildes | |
645 | is not a valid file descriptor open for reading. | |
646 | .Pp | |
647 | The argument | |
648 | .Fa cmd | |
649 | is | |
650 | .Dv F_SETLK | |
651 | or | |
652 | .Dv F_SETLKW , | |
653 | the type of lock | |
654 | .Fa (l_type) | |
655 | is an exclusive lock | |
656 | .Dv (F_WRLCK) , | |
657 | and | |
658 | .Fa fildes | |
659 | is not a valid file descriptor open for writing. | |
660 | .Pp | |
661 | The argument | |
662 | .Fa cmd | |
663 | is | |
664 | .Dv F_PREALLOCATE | |
665 | and the calling process does not have | |
666 | file write permission. | |
667 | .Pp | |
668 | The argument | |
669 | .Fa cmd | |
670 | is | |
671 | .Dv F_LOG2PHYS | |
672 | or | |
673 | .Dv F_LOG2PHYS_EXT | |
674 | and | |
675 | .Fa fildes | |
676 | is not a valid file descriptor open for reading. | |
677 | .\" ========== | |
678 | .It Bq Er EDEADLK | |
679 | The argument | |
680 | .Fa cmd | |
681 | is | |
682 | .Dv F_SETLKW , | |
683 | and a deadlock condition was detected. | |
684 | .\" ========== | |
685 | .It Bq Er EINTR | |
686 | The argument | |
687 | .Fa cmd | |
688 | is | |
689 | .Dv F_SETLKW , | |
690 | and the function was interrupted by a signal. | |
691 | .\" ========== | |
692 | .It Bq Er EINVAL | |
693 | .Fa Cmd | |
694 | is | |
695 | .Dv F_DUPFD | |
696 | and | |
697 | .Fa arg | |
698 | is negative or greater than the maximum allowable number | |
699 | (see | |
700 | .Xr getdtablesize 2 ) . | |
701 | .Pp | |
702 | The argument | |
703 | .Fa cmd | |
704 | is | |
705 | .Dv F_GETLK , | |
706 | .Dv F_SETLK , | |
707 | or | |
708 | .Dv F_SETLKW | |
709 | and the data to which | |
710 | .Fa arg | |
711 | points is not valid, or | |
712 | .Fa fildes | |
713 | refers to a file that does not support locking. | |
714 | .Pp | |
715 | The argument | |
716 | .Fa cmd | |
717 | is | |
718 | .Dv F_PREALLOCATE | |
719 | and the | |
720 | .Fa fst_posmode | |
721 | is not a valid mode, | |
722 | or when | |
723 | .Dv F_PEOFPOSMODE | |
724 | is set and | |
725 | .Fa fst_offset | |
726 | is a non-zero value, | |
727 | or when | |
728 | .Dv F_VOLPOSMODE | |
729 | is set and | |
730 | .Fa fst_offset | |
731 | is a negative or zero value. | |
732 | .Pp | |
733 | The argument | |
734 | .Fa cmd | |
735 | is | |
736 | .Dv F_PUNCHHOLE | |
737 | and | |
738 | either | |
739 | .Fa fp_offset | |
740 | or | |
741 | .Fa fp_length | |
742 | are negative, or both | |
743 | .Fa fp_offset | |
744 | and | |
745 | .Fa fp_length | |
746 | are not multiples of the file system block size. | |
747 | .Pp | |
748 | The argument | |
749 | .Fa cmd | |
750 | is either | |
751 | .Dv F_READBOOTSTRAP | |
752 | or | |
753 | .Dv F_WRITEBOOTSTRAP | |
754 | and the operation was attempted on a non-HFS disk type. | |
755 | .\" ========== | |
756 | .It Bq Er EMFILE | |
757 | .Fa Cmd | |
758 | is | |
759 | .Dv F_DUPFD | |
760 | and the maximum allowed number of file descriptors are currently | |
761 | open. | |
762 | .\" ========== | |
763 | .It Bq Er EMFILE | |
764 | The argument | |
765 | .Fa cmd | |
766 | is | |
767 | .Dv F_DUPED | |
768 | and the maximum number of file descriptors permitted for the | |
769 | process are already in use, | |
770 | or no file descriptors greater than or equal to | |
771 | .Fa arg | |
772 | are available. | |
773 | .\" ========== | |
774 | .It Bq Er ENOLCK | |
775 | The argument | |
776 | .Fa cmd | |
777 | is | |
778 | .Dv F_SETLK | |
779 | or | |
780 | .Dv F_SETLKW , | |
781 | and satisfying the lock or unlock request would result in the | |
782 | number of locked regions in the system exceeding a system-imposed limit. | |
783 | .\" ========== | |
784 | .It Bq Er ENOSPC | |
785 | The argument | |
786 | .Fa cmd | |
787 | is | |
788 | .Dv F_PREALLOCATE | |
789 | and either there is no space available on the volume containing | |
790 | .Fa fildes | |
791 | or | |
792 | .Fa fst_flags | |
793 | contains | |
794 | .Dv F_ALLOCATEALL | |
795 | and there is not enough space available on the volume containing | |
796 | .Fa fildes | |
797 | to satisfy the entire request. | |
798 | .Pp | |
799 | The argument | |
800 | .Fa cmd | |
801 | is | |
802 | .Dv F_PUNCHHOLE | |
803 | and there is not enough space available on the volume containing | |
804 | .Fa fildes | |
805 | to satisfy the request. As an example, a filesystem that supports | |
806 | cloned files may return this error if punching a hole requires the | |
807 | creation of a clone and there is not enough space available to do so. | |
808 | .\" ========== | |
809 | .It Bq Er EOVERFLOW | |
810 | A return value would overflow its representation. | |
811 | For example, | |
812 | .Fa cmd | |
813 | is F_GETLK, F_SETLK, or F_SETLKW | |
814 | and the smallest (or, if l_len is non-zero, the largest) offset | |
815 | of a byte in the requested segment | |
816 | will not fit in an object of type off_t. | |
817 | .\" ========== | |
818 | .It Bq Er EPERM | |
819 | The argument cmd is | |
820 | .Dv F_PUNCHHOLE | |
821 | and the calling process does not have file write permission. | |
822 | .\" ========== | |
823 | .It Bq Er ESRCH | |
824 | .Fa Cmd | |
825 | is | |
826 | .Dv F_SETOWN | |
827 | and | |
828 | the process ID given as argument is not in use. | |
829 | .El | |
830 | .Sh SEE ALSO | |
831 | .Xr close 2 , | |
832 | .Xr execve 2 , | |
833 | .Xr flock 2 , | |
834 | .Xr getdtablesize 2 , | |
835 | .Xr open 2 , | |
836 | .Xr pipe 2 , | |
837 | .Xr socket 2 , | |
838 | .Xr setsockopt 2 , | |
839 | .Xr sigaction 3 | |
840 | .Sh HISTORY | |
841 | The | |
842 | .Fn fcntl | |
843 | function call appeared in | |
844 | .Bx 4.2 . |