1 .\" Copyright (c) 1983, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94
42 .Fn fcntl "int fd" "int cmd" "..."
46 system call provides for control over descriptors.
49 is a descriptor to be operated on by
52 Depending on the value of
55 can take an additional third argument
57 Unless otherwise noted below for a specific operation,
61 .Bl -tag -width F_DUP2FD_CLOEXEC
63 Return a new descriptor as follows:
65 .Bl -bullet -compact -offset 4n
67 Lowest numbered available descriptor greater than or equal to
70 Same object references as the original descriptor.
72 New descriptor shares the same file offset if the object
75 Same access mode (read, write or read/write).
77 Same file status flags (i.e., both file descriptors
78 share the same file status flags).
80 The close-on-exec flag
82 associated with the new file descriptor is cleared, so the file descriptor is
87 .It Dv F_DUPFD_CLOEXEC
92 flag associated with the new file descriptor is set, so the file descriptor
97 It is functionally equivalent to
98 .Bd -literal -offset indent
101 .It Dv F_DUP2FD_CLOEXEC
106 flag associated with the new file descriptor is set.
112 constants are not portable, so they should not be used if
113 portability is needed.
119 Get the close-on-exec flag associated with the file descriptor
123 If the returned value ANDed with
126 the file will remain open across
128 otherwise the file will be closed upon execution of
133 Set the close-on-exec flag associated with
143 Get descriptor status flags, as described below
147 Set descriptor status flags to
150 Get the process ID or process group
155 signals; process groups are returned
160 Set the process or process group
166 process groups are specified by supplying
168 as negative, otherwise
170 is interpreted as a process ID.
172 Set or clear the read ahead amount for sequential access to the third
175 which is rounded up to the nearest block size.
178 turns off read ahead, a negative value restores the system default.
180 Equivalent to Darwin counterpart which sets read ahead amount of 128KB
181 when the third argument,
186 turns off read ahead.
188 Add seals to the file as described below, if the underlying filesystem supports
191 Get seals associated with the file, if the underlying filesystem supports seals.
192 .It Dv F_ISUNIONSTACK
193 Check if the vnode is part of a union stack (either the "union" flag from
196 This is a hack not intended to be used outside of libc.
199 .Vt struct kinfo_file
200 for the file referenced by the specified file descriptor.
203 argument should point to the storage for
204 .Vt struct kinfo_file .
207 member of the passed structure must be initialized with the sizeof of
208 .Vt struct kinfo_file ,
209 to allow for the interface versioning and evolution.
216 commands are as follows:
217 .Bl -tag -width O_NONBLOCKX
219 Non-blocking I/O; if no data is available to a
223 operation would block,
224 the read or write call returns -1 with the error
227 Force each write to append at the end of file;
233 Minimize or eliminate the cache effects of reading and writing.
235 will attempt to avoid caching the data you read or write.
237 avoid caching the data, it will minimize the impact the data has on the cache.
238 Use of this flag can drastically reduce performance if not used with care.
242 signal to be sent to the process group
243 when I/O is possible, e.g.,
244 upon availability of data to be read.
246 Enable synchronous writes.
252 is an historical synonym for
255 Enable synchronous data writes.
262 The seals that may be applied with
265 .Bl -tag -width F_SEAL_SHRINK
267 Prevent any further seals from being applied to the file.
269 Prevent the file from being shrunk with
272 Prevent the file from being enlarged with
278 Any writes in progress will finish before
281 If any writeable mappings exist, F_ADD_SEALS will fail and return
285 Seals are on a per-inode basis and require support by the underlying filesystem.
286 If the underlying filesystem does not support seals,
293 Several operations are available for doing advisory file locking;
294 they all operate on the following structure:
297 off_t l_start; /* starting offset */
298 off_t l_len; /* len = 0 means until end of file */
299 pid_t l_pid; /* lock owner */
300 short l_type; /* lock type: read/write, etc. */
301 short l_whence; /* type of l_start */
302 int l_sysid; /* remote system id or zero for local */
305 These advisory file locking operations take a pointer to
307 as the third argument
309 The commands available for advisory record locking are as follows:
310 .Bl -tag -width F_SETLKWX
312 Get the first lock that blocks the lock description pointed to by the
315 taken as a pointer to a
318 The information retrieved overwrites the information passed to
323 If no lock is found that would prevent this lock from being created,
324 the structure is left unchanged by this system call except for the
325 lock type which is set to
328 Set or clear a file segment lock according to the lock description
329 pointed to by the third argument,
331 taken as a pointer to a
335 is used to establish shared (or read) locks
337 or exclusive (or write) locks,
339 as well as remove either type of lock
341 If a shared or exclusive lock cannot be set,
343 returns immediately with
346 This command is the same as
348 except that if a shared or exclusive lock is blocked by other locks,
349 the process waits until the request can be satisfied.
350 If a signal that is to be caught is received while
352 is waiting for a region, the
354 will be interrupted if the signal handler has not specified the
360 When a shared lock has been set on a segment of a file,
361 other processes can set shared locks on that segment
363 A shared lock prevents any other process from setting an exclusive
364 lock on any portion of the protected area.
365 A request for a shared lock fails if the file descriptor was not
366 opened with read access.
368 An exclusive lock prevents any other process from setting a shared lock or
369 an exclusive lock on any portion of the protected area.
370 A request for an exclusive lock fails if the file was not
371 opened with write access.
380 to indicate that the relative offset,
382 bytes, will be measured from the start of the file,
383 current position, or end of the file, respectively.
386 is the number of consecutive bytes to be locked.
391 means end edge of the region.
396 fields are only used with
398 to return the process ID of the process holding a blocking lock and
399 the system ID of the system that owns that process.
400 Locks created by the local system will have a system ID of zero.
403 request, the value of
408 Locks may start and extend beyond the current end of a file,
409 but may not start or extend before the beginning of the file.
410 A lock is set to extend to the largest possible value of the
411 file offset for that file if
418 point to the beginning of the file, and
420 is zero, the entire file is locked.
421 If an application wishes only to do entire file locking, the
423 system call is much more efficient.
425 There is at most one type of lock set for each byte in the file.
426 Before a successful return from an
430 request when the calling process has previously existing locks
431 on bytes in the region specified by the request,
432 the previous lock type for each byte in the specified
433 region is replaced by the new lock type.
434 As specified above under the descriptions
435 of shared locks and exclusive locks, an
439 request fails or blocks respectively when another process has existing
440 locks on bytes in the specified region and the type of any of those
441 locks conflicts with the type specified in the request.
445 requests on local files is fair;
446 that is, while the thread is blocked,
447 subsequent requests conflicting with its requests will not be granted,
448 even if these requests do not conflict with existing locks.
450 This interface follows the completely stupid semantics of System V and
452 that require that all locks associated with a file for a given process are
455 file descriptor for that file is closed by that process.
456 This semantic means that applications must be aware of any files that
457 a subroutine library may access.
458 For example if an application for updating the password file locks the
459 password file database while making the update, and then calls
461 to retrieve a record,
462 the lock will be lost because
464 opens, reads, and closes the password database.
465 The database close will release all locks that the process has
466 associated with the database, even if the library routine never
467 requested a lock on the database.
468 Another minor semantic problem with this interface is that
469 locks are not inherited by a child process created using the
474 interface has much more rational last close semantics and
475 allows locks to be inherited by child processes.
478 system call is recommended for applications that want to ensure the integrity
479 of their locks when using library routines or wish to pass locks
487 locks are compatible.
488 Processes using different locking interfaces can cooperate
489 over the same file safely.
490 However, only one of such interfaces should be used within
492 If a file is locked by a process through
494 any record within the file will be seen as locked
495 from the viewpoint of another process using
504 if the process holding a blocking lock previously locked the
508 All locks associated with a file for a given process are
509 removed when the process terminates.
511 All locks obtained before a call to
513 remain in effect until the new program releases them.
514 If the new program does not know about the locks, they will not be
515 released until the program exits.
517 A potential for deadlock occurs if a process controlling a locked region
518 is put to sleep by attempting to lock the locked region of another process.
519 This implementation detects that sleeping until a locked region is unlocked
520 would cause a deadlock and fails with an
524 Upon successful completion, the value returned depends on
527 .Bl -tag -width F_GETOWNX -offset indent
529 A new file descriptor.
531 A file descriptor equal to
534 Value of flag (only the low-order bit is defined).
538 Value of file descriptor owner.
543 Otherwise, a value of -1 is returned and
545 is set to indicate the error.
549 system call will fail if:
562 and the segment of a file to be locked is already
563 exclusive-locked by another process;
564 or the type is an exclusive lock and some portion of the
565 segment of a file to be locked is already shared-locked or
566 exclusive-locked by another process.
571 is not a valid open file descriptor.
579 is not a valid file descriptor.
593 is not a valid file descriptor open for reading.
607 is not a valid file descriptor open for writing.
615 and writeable mappings of the file exist.
621 and a deadlock condition was detected.
627 and the system call was interrupted by a signal.
636 is negative or greater than the maximum allowable number
638 .Xr getdtablesize 2 ) .
647 and the data to which
657 and the underlying filesystem does not support sealing.
667 and the maximum number of file descriptors permitted for the
668 process are already in use,
669 or no file descriptors greater than or equal to
675 argument is not a valid file descriptor for the requested operation.
676 This may be the case if
678 is a device node, or a descriptor returned by
687 and satisfying the lock or unlock request would result in the
688 number of locked regions in the system exceeding a system-imposed limit.
699 refers to a file for which locking is not supported.
710 calculation overflowed.
718 the process ID or process group given as an argument is in a
719 different session than the caller.
728 seal has already been set.
736 the process ID given as argument is not in use.
741 refers to a descriptor open on a terminal device (as opposed to a
742 descriptor open on a socket), a
746 can fail for the same reasons as in
752 for the reasons as stated in
759 .Xr getdtablesize 2 ,
768 constant is non portable.
769 It is provided for compatibility with AIX and Solaris.
777 after any caught signal
778 and should continue waiting during thread suspension such as a stop signal.
779 However, in this implementation a call with
781 is restarted after catching a signal with a
783 handler or a thread suspension such as a stop signal.
787 system call appeared in
792 constant first appeared in