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 .Bl -tag -width F_DUP2FD_CLOEXEC
59 Return a new descriptor as follows:
61 .Bl -bullet -compact -offset 4n
63 Lowest numbered available descriptor greater than or equal to
66 Same object references as the original descriptor.
68 New descriptor shares the same file offset if the object
71 Same access mode (read, write or read/write).
73 Same file status flags (i.e., both file descriptors
74 share the same file status flags).
76 The close-on-exec flag
78 associated with the new file descriptor is cleared, so the file descriptor is
83 .It Dv F_DUPFD_CLOEXEC
88 flag associated with the new file descriptor is set, so the file descriptor
93 It is functionally equivalent to
94 .Bd -literal -offset indent
97 .It Dv F_DUP2FD_CLOEXEC
102 flag associated with the new file descriptor is set.
108 constants are not portable, so they should not be used if
109 portability is needed.
115 Get the close-on-exec flag associated with the file descriptor
119 If the returned value ANDed with
122 the file will remain open across
124 otherwise the file will be closed upon execution of
129 Set the close-on-exec flag associated with
139 Get descriptor status flags, as described below
143 Set descriptor status flags to
146 Get the process ID or process group
151 signals; process groups are returned
156 Set the process or process group
162 process groups are specified by supplying
164 as negative, otherwise
166 is interpreted as a process ID.
168 Set or clear the read ahead amount for sequential access to the third
171 which is rounded up to the nearest block size.
174 turns off read ahead, a negative value restores the system default.
176 Equivalent to Darwin counterpart which sets read ahead amount of 128KB
177 when the third argument,
182 turns off read ahead.
184 Add seals to the file as described below, if the underlying filesystem supports
187 Get seals associated with the file, if the underlying filesystem supports seals.
188 .It Dv F_ISUNIONSTACK
189 Check if the vnode is part of a union stack (either the "union" flag from
192 This is a hack not intended to be used outside of libc.
199 flags are as follows:
200 .Bl -tag -width O_NONBLOCKX
202 Non-blocking I/O; if no data is available to a
206 operation would block,
207 the read or write call returns -1 with the error
210 Force each write to append at the end of file;
216 Minimize or eliminate the cache effects of reading and writing.
218 will attempt to avoid caching the data you read or write.
220 avoid caching the data, it will minimize the impact the data has on the cache.
221 Use of this flag can drastically reduce performance if not used with care.
225 signal to be sent to the process group
226 when I/O is possible, e.g.,
227 upon availability of data to be read.
230 The seals that may be applied with
233 .Bl -tag -width F_SEAL_SHRINK
235 Prevent any further seals from being applied to the file.
237 Prevent the file from being shrunk with
240 Prevent the file from being enlarged with
246 Any writes in progress will finish before
249 If any writeable mappings exist, F_ADD_SEALS will fail and return
253 Seals are on a per-inode basis and require support by the underlying filesystem.
254 If the underlying filesystem does not support seals,
261 Several commands are available for doing advisory file locking;
262 they all operate on the following structure:
265 off_t l_start; /* starting offset */
266 off_t l_len; /* len = 0 means until end of file */
267 pid_t l_pid; /* lock owner */
268 short l_type; /* lock type: read/write, etc. */
269 short l_whence; /* type of l_start */
270 int l_sysid; /* remote system id or zero for local */
273 The commands available for advisory record locking are as follows:
274 .Bl -tag -width F_SETLKWX
276 Get the first lock that blocks the lock description pointed to by the
279 taken as a pointer to a
282 The information retrieved overwrites the information passed to
287 If no lock is found that would prevent this lock from being created,
288 the structure is left unchanged by this system call except for the
289 lock type which is set to
292 Set or clear a file segment lock according to the lock description
293 pointed to by the third argument,
295 taken as a pointer to a
299 is used to establish shared (or read) locks
301 or exclusive (or write) locks,
303 as well as remove either type of lock
305 If a shared or exclusive lock cannot be set,
307 returns immediately with
310 This command is the same as
312 except that if a shared or exclusive lock is blocked by other locks,
313 the process waits until the request can be satisfied.
314 If a signal that is to be caught is received while
316 is waiting for a region, the
318 will be interrupted if the signal handler has not specified the
324 When a shared lock has been set on a segment of a file,
325 other processes can set shared locks on that segment
327 A shared lock prevents any other process from setting an exclusive
328 lock on any portion of the protected area.
329 A request for a shared lock fails if the file descriptor was not
330 opened with read access.
332 An exclusive lock prevents any other process from setting a shared lock or
333 an exclusive lock on any portion of the protected area.
334 A request for an exclusive lock fails if the file was not
335 opened with write access.
344 to indicate that the relative offset,
346 bytes, will be measured from the start of the file,
347 current position, or end of the file, respectively.
350 is the number of consecutive bytes to be locked.
355 means end edge of the region.
360 fields are only used with
362 to return the process ID of the process holding a blocking lock and
363 the system ID of the system that owns that process.
364 Locks created by the local system will have a system ID of zero.
367 request, the value of
372 Locks may start and extend beyond the current end of a file,
373 but may not start or extend before the beginning of the file.
374 A lock is set to extend to the largest possible value of the
375 file offset for that file if
382 point to the beginning of the file, and
384 is zero, the entire file is locked.
385 If an application wishes only to do entire file locking, the
387 system call is much more efficient.
389 There is at most one type of lock set for each byte in the file.
390 Before a successful return from an
394 request when the calling process has previously existing locks
395 on bytes in the region specified by the request,
396 the previous lock type for each byte in the specified
397 region is replaced by the new lock type.
398 As specified above under the descriptions
399 of shared locks and exclusive locks, an
403 request fails or blocks respectively when another process has existing
404 locks on bytes in the specified region and the type of any of those
405 locks conflicts with the type specified in the request.
409 requests on local files is fair;
410 that is, while the thread is blocked,
411 subsequent requests conflicting with its requests will not be granted,
412 even if these requests do not conflict with existing locks.
414 This interface follows the completely stupid semantics of System V and
416 that require that all locks associated with a file for a given process are
419 file descriptor for that file is closed by that process.
420 This semantic means that applications must be aware of any files that
421 a subroutine library may access.
422 For example if an application for updating the password file locks the
423 password file database while making the update, and then calls
425 to retrieve a record,
426 the lock will be lost because
428 opens, reads, and closes the password database.
429 The database close will release all locks that the process has
430 associated with the database, even if the library routine never
431 requested a lock on the database.
432 Another minor semantic problem with this interface is that
433 locks are not inherited by a child process created using the
438 interface has much more rational last close semantics and
439 allows locks to be inherited by child processes.
442 system call is recommended for applications that want to ensure the integrity
443 of their locks when using library routines or wish to pass locks
451 locks are compatible.
452 Processes using different locking interfaces can cooperate
453 over the same file safely.
454 However, only one of such interfaces should be used within
456 If a file is locked by a process through
458 any record within the file will be seen as locked
459 from the viewpoint of another process using
468 if the process holding a blocking lock previously locked the
472 All locks associated with a file for a given process are
473 removed when the process terminates.
475 All locks obtained before a call to
477 remain in effect until the new program releases them.
478 If the new program does not know about the locks, they will not be
479 released until the program exits.
481 A potential for deadlock occurs if a process controlling a locked region
482 is put to sleep by attempting to lock the locked region of another process.
483 This implementation detects that sleeping until a locked region is unlocked
484 would cause a deadlock and fails with an
488 Upon successful completion, the value returned depends on
491 .Bl -tag -width F_GETOWNX -offset indent
493 A new file descriptor.
495 A file descriptor equal to
498 Value of flag (only the low-order bit is defined).
502 Value of file descriptor owner.
507 Otherwise, a value of -1 is returned and
509 is set to indicate the error.
513 system call will fail if:
526 and the segment of a file to be locked is already
527 exclusive-locked by another process;
528 or the type is an exclusive lock and some portion of the
529 segment of a file to be locked is already shared-locked or
530 exclusive-locked by another process.
535 is not a valid open file descriptor.
543 is not a valid file descriptor.
557 is not a valid file descriptor open for reading.
571 is not a valid file descriptor open for writing.
579 and writeable mappings of the file exist.
585 and a deadlock condition was detected.
591 and the system call was interrupted by a signal.
600 is negative or greater than the maximum allowable number
602 .Xr getdtablesize 2 ) .
611 and the data to which
621 and the underlying filesystem does not support sealing.
631 and the maximum number of file descriptors permitted for the
632 process are already in use,
633 or no file descriptors greater than or equal to
639 argument is not a valid file descriptor for the requested operation.
640 This may be the case if
642 is a device node, or a descriptor returned by
651 and satisfying the lock or unlock request would result in the
652 number of locked regions in the system exceeding a system-imposed limit.
663 refers to a file for which locking is not supported.
674 calculation overflowed.
682 the process ID or process group given as an argument is in a
683 different session than the caller.
692 seal has already been set.
700 the process ID given as argument is not in use.
705 refers to a descriptor open on a terminal device (as opposed to a
706 descriptor open on a socket), a
710 can fail for the same reasons as in
716 for the reasons as stated in
723 .Xr getdtablesize 2 ,
732 constant is non portable.
733 It is provided for compatibility with AIX and Solaris.
741 after any caught signal
742 and should continue waiting during thread suspension such as a stop signal.
743 However, in this implementation a call with
745 is restarted after catching a signal with a
747 handler or a thread suspension such as a stop signal.
751 system call appeared in
756 constant first appeared in