Copyright (c) 1983, 1993
The Regents of the University of California. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the University nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
@(#)fcntl.2 8.2 (Berkeley) 1/12/94
.Dd July 8, 2025 .Dt FCNTL 2 .Os .Sh NAME .Nm fcntl .Nd file descriptor control .Sh LIBRARY .Lb libc .Sh SYNOPSIS n fcntl.h .Ft int .Fn fcntl "int fd" "int cmd" "..." .Sh DESCRIPTION .Fn fcntl provides for control over descriptors. The argument .Fa fd is a descriptor to be operated on by .Fa cmd as described below. The third parameter is called .Fa arg and is technically a pointer to void, but it is interpreted as an int by some commands and ignored by others.
p Commands are: l -tag -width F_DUPFD_CLOEXEC t Dv F_DUPFD Return a new descriptor as follows:
p l -bullet -compact -offset 4n t Lowest numbered available descriptor greater than or equal to .Fa arg , which is interpreted as an int. t Same object references as the original descriptor. t New descriptor shares the same file offset if the object was a file. t Same access mode (read, write or read/write). t Same file status flags (i.e., both file descriptors share the same file status flags). t The close-on-exec flag associated with the new file descriptor is cleared to allow the file descriptor to remain open across .Xr execve 2 system calls. t The close-on-fork flag .Dv FD_CLOFORK associated with the new file descriptor is cleared, so the file descriptor will remain open across .Xr fork 2 system calls. .El t Dv F_DUPFD_CLOEXEC Same as .Dv F_DUPFD , but sets the close-on-exec property on the file descriptor created. t Dv F_DUPFD_CLOFORK Same as .Dv F_DUPFD , but sets the close-on-fork property on the file descriptor created. t Dv F_DUPFD_CLOBOTH Same as .Dv F_DUPFD , but sets both the close-on-exec and close-on-fork properties on the file descriptor created. t Dv F_GETFD Get the flags associated with the file descriptor .Fa fd .Fa ( arg is ignored). If the returned value ANDed with .Dv FD_CLOEXEC is 0, the file will remain open across .Fn exec , otherwise the file will be closed upon execution of .Fn exec . If the returned value ANDed with .Dv FD_CLOFORK is not 0, the file will be closed upon execution of the .Fn fork family of system calls. t Dv F_SETFD Set flags associated with .Fa fd . The available flags, passed as .Fa arg (treated as an integer), are .Dv FD_CLOEXEC and .Dv FD_CLOFORK . t Dv F_GETFL Get descriptor status flags, as described below .Fa ( arg is ignored). t Dv F_SETFL Set descriptor status flags to .Fa arg , which is interpreted as an int. t Dv F_GETOWN Get the process ID or process group currently receiving .Dv SIGIO and .Dv SIGURG signals; process groups are returned as negative values .Fa ( arg is ignored). t Dv F_SETOWN Set the process or process group to receive .Dv SIGIO and .Dv SIGURG signals; process groups are specified by supplying .Fa arg as negative, otherwise .Fa arg is interpreted as a process ID. The argument .Fa arg is interpreted as an int. t Dv F_CLOSEM Close all file descriptors greater than or equal to .Fa fd , .Fa ( arg is ignored). t Dv F_MAXFD Return the maximum file descriptor number currently open by the process. .Fa ( arg is ignored). t Dv F_GETNOSIGPIPE Return 1 if the .Dv O_NOSIGPIPE flag is set in the file descriptor, otherwise 0 .Fa ( arg is ignored). t Dv F_SETNOSIGPIPE If .Fa arg is 0, clear the .Dv O_NOSIGPIPE status in the file descriptor, otherwise set it. t Dv F_GETPATH Place a pathname corresponding to .Fa fd in the buffer pointed to by .Fa arg . .Fa arg should be pointing to a buffer of at least .Dv MAXPATHLEN bytes. t Dv F_ADD_SEALS Add seals specified in .Fa arg to .Fa fd to restrict possible operations on .Fa fd as described below. Like flags, multiple seals can be specified at once. Additionally, specifying seals that are already associated with .Fa fd is a no-op. t Dv F_GET_SEALS Get the seals currently associated with .Fa fd as described below .Fa ( arg is ignored). .El
p The set of valid flags for the .Dv F_GETFL and .Dv F_SETFL flags are as follows: .Dv O_APPEND , .Dv O_ASYNC , .Dv O_SYNC , .Dv O_NONBLOCK , .Dv O_DSYNC , .Dv O_RSYNC , .Dv O_ALT_IO , .Dv O_DIRECT , .Dv O_NOSIGPIPE . These flags are described in .Xr open 2 .
p Several commands are available for doing advisory file locking; they all operate on the following structure: d -literal struct flock { off_t l_start; /* starting offset */ off_t l_len; /* len = 0 means until end of file */ pid_t l_pid; /* lock owner */ short l_type; /* lock type: read/write, etc. */ short l_whence; /* type of l_start */ }; .Ed
p The commands available for advisory record locking are as follows: l -tag -width F_SETLKWX t Dv F_GETLK Get the first lock that blocks the lock description pointed to by the third argument, .Fa arg , taken as a pointer to a .Fa "struct flock" (see above). The information retrieved overwrites the information passed to .Nm in the .Fa flock structure. If no lock is found that would prevent this lock from being created, the structure is left unchanged by this function call except for the lock type .Fa l_type , which is set to .Dv F_UNLCK . t Dv F_SETLK Set or clear a file segment lock according to the lock description pointed to by the third argument, .Fa arg , taken as a pointer to a .Fa "struct flock" (see above). As specified by the value of .Fa l_type , .Dv F_SETLK is used to establish shared (or read) locks
q Dv F_RDLCK or exclusive (or write) locks,
q Dv F_WRLCK , as well as remove either type of lock
q Dv F_UNLCK . If a shared or exclusive lock cannot be set, .Nm returns immediately with .Er EAGAIN . t Dv F_SETLKW This command is the same as .Dv F_SETLK except that if a shared or exclusive lock is blocked by other locks, the process waits until the request can be satisfied. If a signal that is to be caught is received while .Nm is waiting for a region, the .Nm will be interrupted if the signal handler has not specified the .Dv SA_RESTART (see .Xr sigaction 2 ) . .El
p When a shared lock has been set on a segment of a file, other processes can set shared locks on that segment or a portion of it. A shared lock prevents any other process from setting an exclusive lock on any portion of the protected area. A request for a shared lock fails if the file descriptor was not opened with read access.
p An exclusive lock prevents any other process from setting a shared lock or an exclusive lock on any portion of the protected area. A request for an exclusive lock fails if the file was not opened with write access.
p The value of .Fa l_whence is .Dv SEEK_SET , .Dv SEEK_CUR , or .Dv SEEK_END to indicate that the relative offset, .Fa l_start bytes, will be measured from the start of the file, current position, or end of the file, respectively. The value of .Fa l_len is the number of consecutive bytes to be locked. If .Fa l_len is negative, the result is undefined. The .Fa l_pid field is only used with .Dv F_GETLK to return the process ID of the process holding a blocking lock. After a successful .Dv F_GETLK request, the value of .Fa l_whence is .Dv SEEK_SET .
p Locks may start and extend beyond the current end of a file, but may not start or extend before the beginning of the file. A lock is set to extend to the largest possible value of the file offset for that file if .Fa l_len is set to zero. If .Fa l_whence and .Fa l_start point to the beginning of the file, and .Fa l_len is zero, the entire file is locked. If an application wishes only to do entire file locking, the .Xr flock 2 system call is much more efficient.
p There is at most one type of lock set for each byte in the file. Before a successful return from an .Dv F_SETLK or an .Dv F_SETLKW request when the calling process has previously existing locks on bytes in the region specified by the request, the previous lock type for each byte in the specified region is replaced by the new lock type. As specified above under the descriptions of shared locks and exclusive locks, an .Dv F_SETLK or an .Dv F_SETLKW request fails or blocks respectively when another process has existing locks on bytes in the specified region and the type of any of those locks conflicts with the type specified in the request.
p Possible seals are: l -tag -width F_SEAL_FUTURE_WRITE t Dv F_SEAL_SEAL Prevent any further seals from being added to .Fa fd . t Dv F_SEAL_SHRINK Prevent the size of .Fa fd from decreasing. t Dv F_SEAL_GROW Prevent the size of .Fa fd from increasing. t Dv F_SEAL_WRITE Prevent any write operations to .Fa fd . .Dv F_SEAL_WRITE cannot be applied if .Fa fd has any memory mappings. t Dv F_SEAL_FUTURE_WRITE Like .Dv F_SEAL_WRITE but allow any current memory mappings of .Fa fd to remain open, including those with .Dv PROT_WRITE . .El .Sh NOTES For .Dv F_GETPATH : l -bullet -compact t For vnodes, functionality is implemented using the reverse .Xr namei 9 cache. The implications of this are l -bullet -compact t For hard links where the file descriptor can resolve to multiple pathnames, the first entry found in the cache is returned. t .Dv F_GETPATH may fail if the corresponding entry has been evicted from the LRU .Xr namei 9 cache and return .Er ENOENT . .El t For a file descriptor created by .Xr memfd_create 2 , the name provided at .Fa fd creation, with the prefix .Dq memfd: is used. t Other types of file descriptors are not handled, as well as symbolic links since there is currently no way to obtain a file descriptor pointing to a symbolic link. .El .Sh RETURN VALUES Upon successful completion, the value returned depends on .Fa cmd as follows: l -tag -width F_GET_SEALS -offset indent t Dv F_DUPFD A new file descriptor. t Dv F_GETFD Value of flag (one or both of the bits .Dv FD_CLOEXEC and .Dv FD_CLOFORK ) . t Dv F_GETFL Value of flags. t Dv F_GETOWN Value of file descriptor owner. t Dv F_MAXFD Value of the highest file descriptor open by the process. t Dv F_GET_SEALS Value of the seals currently associated with .Fa fd . t other Value other than -1. .El
p Otherwise, a value of -1 is returned and .Va errno is set to indicate the error. .Sh COMPATIBILITY This interface follows the completely stupid semantics of .At V and .St -p1003.1-88 that require that all locks associated with a file for a given process are removed when any file descriptor for that file is closed by that process. This semantic means that applications must be aware of any files that a subroutine library may access. For example if an application for updating the password file locks the password file database while making the update, and then calls .Xr getpwnam 3 to retrieve a record, the lock will be lost because .Xr getpwnam 3 opens, .Fa cmd is .Dv F_GETPATH and the resulting path would be greater than .Dv MAXPATHLEN . t Bq Er ESRCH .Fa cmd is .Dv F_SETOWN and the process ID given as argument is not in use. .El .Sh SEE ALSO .Xr close 2 , .Xr execve 2 , .Xr flock 2 , .Xr open 2 , .Xr sigaction 2 , .Xr getdtablesize 3 .Sh STANDARDS The .Fn fcntl function conforms to .St -p1003.1-90 . .Sh HISTORY The .Fn fcntl function call appeared in x 4.2 . The .Dv F_DUPFD_CLOBOTH operation first appeared in .Nx 11.0 .
Indexes created Wed Sep 24 05:09:52 GMT 2025