--- name: "fcntl" section: "3p" platform: "linux" package: "man-pages" version: "6.19-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/fcntl/3p" --- # fcntl(3p) file control ## PROLOG This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux. ## NAME fcntl — file control ## SYNOPSIS ``` #include ``` int fcntl(int *fildes*, int *cmd*, ...); ## DESCRIPTION The *fcntl*() function shall perform the operations described below on open files. The *fildes* argument is a file descriptor. The available values for *cmd* are defined in *\* and are as follows: - F\_DUPFD Return a new file descriptor which shall be allocated as described in *Section 2.14*, *File Descriptor Allocation*, except that it shall be the lowest numbered available file descriptor greater than or equal to the third argument, *arg*, taken as an integer of type **int**. The new file descriptor shall refer to the same open file description as the original file descriptor, and shall share any locks. The FD\_CLOEXEC flag associated with the new file descriptor shall be cleared to keep the file open across calls to one of the *exec* functions. - F\_DUPFD\_CLOEXEC Like F\_DUPFD, but the FD\_CLOEXEC flag associated with the new file descriptor shall be set. - F\_GETFD Get the file descriptor flags defined in *\* that are associated with the file descriptor *fildes*. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file. - F\_SETFD Set the file descriptor flags defined in *\*, that are associated with *fildes*, to the third argument, *arg*, taken as type **int**. If the FD\_CLOEXEC flag in the third argument is 0, the file descriptor shall remain open across the *exec* functions; otherwise, the file descriptor shall be closed upon successful execution of one of the *exec* functions. - F\_GETFL Get the file status flags and file access modes, defined in *\*, for the file description associated with *fildes*. The file access modes can be extracted from the return value using the mask O\_ACCMODE, which is defined in *\*. File status flags and file access modes are associated with the file description and do not affect other file descriptors that refer to the same file with different open file descriptions. The flags returned may include non-standard file status flags which the application did not set, provided that these additional flags do not alter the behavior of a conforming application. - F\_SETFL Set the file status flags, defined in *\*, for the file description associated with *fildes* from the corresponding bits in the third argument, *arg*, taken as type **int**. Bits corresponding to the file access mode and the file creation flags, as defined in *\*, that are set in *arg* shall be ignored. If any bits in *arg* other than those mentioned here are changed by the application, the result is unspecified. If *fildes* does not support non-blocking operations, it is unspecified whether the O\_NONBLOCK flag will be ignored. - F\_GETOWN If *fildes* refers to a socket, get the process ID or process group ID specified to receive SIGURG signals when out-of-band data is available. Positive values shall indicate a process ID; negative values, other than -1, shall indicate a process group ID; the value zero shall indicate that no SIGURG signals are to be sent. If *fildes* does not refer to a socket, the results are unspecified. - F\_SETOWN If *fildes* refers to a socket, set the process ID or process group ID specified to receive SIGURG signals when out-of-band data is available, using the value of the third argument, *arg*, taken as type **int**. Positive values shall indicate a process ID; negative values, other than -1, shall indicate a process group ID; the value zero shall indicate that no SIGURG signals are to be sent. Each time a SIGURG signal is sent to the specified process or process group, permission checks equivalent to those performed by *kill*() shall be performed, as if *kill*() were called by a process with the same real user ID, effective user ID, and privileges that the process calling *fcntl*() has at the time of the call; if the *kill*() call would fail, no signal shall be sent. These permission checks may also be performed by the *fcntl*() call. If the process specified by *arg* later terminates, or the process group specified by *arg* later becomes empty, while still being specified to receive SIGURG signals when out-of-band data is available from *fildes*, then no signals shall be sent to any subsequently created process that has the same process ID or process group ID, regardless of permission; it is unspecified whether this is achieved by the equivalent of a *fcntl*(*fildes*, F\_SETOWN, 0) call at the time the process terminates or is waited for or the process group becomes empty, or by other means. If *fildes* does not refer to a socket, the results are unspecified. The following values for *cmd* are available for advisory record locking. Record locking shall be supported for regular files, and may be supported for other files. - F\_GETLK Get any lock which blocks the lock description pointed to by the third argument, *arg*, taken as a pointer to type **struct flock**, defined in *\*. The information retrieved shall overwrite the information passed to *fcntl*() in the structure **flock**. If no lock is found that would prevent this lock from being created, then the structure shall be left unchanged except for the lock type which shall be set to F\_UNLCK. - F\_SETLK Set or clear a file segment lock according to the lock description pointed to by the third argument, *arg*, taken as a pointer to type **struct flock**, defined in *\*. F\_SETLK can establish shared (or read) locks (F\_RDLCK) or exclusive (or write) locks (F\_WRLCK), as well as to remove either type of lock (F\_UNLCK). F\_RDLCK, F\_WRLCK, and F\_UNLCK are defined in *\*. If a shared or exclusive lock cannot be set, *fcntl*() shall return immediately with a return value of -1. - F\_SETLKW This command shall be equivalent to F\_SETLK except that if a shared or exclusive lock is blocked by other locks, the thread shall wait until the request can be satisfied. If a signal that is to be caught is received while *fcntl*() is waiting for a region, *fcntl*() shall be interrupted. Upon return from the signal handler, *fcntl*() shall return -1 with *errno* set to **\[EINTR\]**, and the lock operation shall not be done. Additional implementation-defined values for *cmd* may be defined in *\*. Their names shall start with F\_. When a shared lock is set on a segment of a file, other processes shall be able to 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 shall fail if the file descriptor was not opened with read access. An exclusive lock shall prevent 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 shall fail if the file descriptor was not opened with write access. The structure **flock** describes the type (*l\_type*), starting offset (*l\_whence*), relative offset (*l\_start*), size (*l\_len*), and process ID (*l\_pid*) of the segment of the file to be affected. The value of *l\_whence* is SEEK\_SET, SEEK\_CUR, or SEEK\_END, to indicate that the relative offset *l\_start* bytes shall be measured from the start of the file, current position, or end of the file, respectively. The value of *l\_len* is the number of consecutive bytes to be locked. The value of *l\_len* may be negative (where the definition of **off\_t** permits negative values of *l\_len*). The *l\_pid* field is only used with F\_GETLK to return the process ID of the process holding a blocking lock. After a successful F\_GETLK request, when a blocking lock is found, the values returned in the **flock** structure shall be as follows: - *l\_type* Type of blocking lock found. - *l\_whence* SEEK\_SET. - *l\_start* Start of the blocking lock. - *l\_len* Length of the blocking lock. - *l\_pid* Process ID of the process that holds the blocking lock. If the command is F\_SETLKW and the process must wait for another process to release a lock, then the range of bytes to be locked shall be determined before the *fcntl*() function blocks. If the file size or file descriptor seek offset change while *fcntl*() is blocked, this shall not affect the range of bytes locked. If *l\_len* is positive, the area affected shall start at *l\_start* and end at *l\_start*+ *l\_len*-1. If *l\_len* is negative, the area affected shall start at *l\_start*+ *l\_len* and end at *l\_start*-1. Locks may start and extend beyond the current end of a file, but shall not extend before the beginning of the file. A lock shall be set to extend to the largest possible value of the file offset for that file by setting *l\_len* to 0. If such a lock also has *l\_start* set to 0 and *l\_whence* is set to SEEK\_SET, the whole file shall be locked. There shall be at most one type of lock set for each byte in the file. Before a successful return from an F\_SETLK or an 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 shall be replaced by the new lock type. As specified above under the descriptions of shared locks and exclusive locks, an F\_SETLK or an F\_SETLKW request (respectively) shall fail or block 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. All locks associated with a file for a given process shall be removed when a file descriptor for that file is closed by that process or the process holding that file descriptor terminates. Locks are not inherited by a child process. A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to lock the locked region of another process. If the system detects that sleeping until a locked region is unlocked would cause a deadlock, *fcntl*() shall fail with an **\[EDEADLK\]** error. An unlock (F\_UNLCK) request in which *l\_len* is non-zero and the offset of the last byte of the requested segment is the maximum value for an object of type **off\_t**, when the process has an existing lock in which *l\_len* is 0 and which includes the last byte of the requested segment, shall be treated as a request to unlock from the start of the requested segment with an *l\_len* equal to 0. Otherwise, an unlock (F\_UNLCK) request shall attempt to unlock only the requested segment. When the file descriptor *fildes* refers to a shared memory object, the behavior of *fcntl*() shall be the same as for a regular file except the effect of the following values for the argument *cmd* shall be unspecified: F\_SETFL, F\_GETLK, F\_SETLK, and F\_SETLKW. If *fildes* refers to a typed memory object, the result of the *fcntl*() function is unspecified. ## RETURN VALUE Upon successful completion, the value returned shall depend on *cmd* as follows: - F\_DUPFD A new file descriptor. - F\_DUPFD\_CLOEXEC A new file descriptor. - F\_GETFD Value of flags defined in *\*. The return value shall not be negative. - F\_SETFD Value other than -1. - F\_GETFL Value of file status flags and access modes. The return value is not negative. - F\_SETFL Value other than -1. - F\_GETLK Value other than -1. - F\_SETLK Value other than -1. - F\_SETLKW Value other than -1. - F\_GETOWN Value of the socket owner process or process group; this will not be -1. - F\_SETOWN Value other than -1. Otherwise, -1 shall be returned and *errno* set to indicate the error. ## ERRORS The *fcntl*() function shall fail if: - **EACCES** or **EAGAIN** The *cmd* argument is F\_SETLK; the type of lock (*l\_type*) is a shared (F\_RDLCK) or exclusive (F\_WRLCK) lock and the segment of a file to be locked is already exclusive-locked by another process, or the type is an exclusive lock and some portion of the segment of a file to be locked is already shared-locked or exclusive-locked by another process. - **EBADF** The *fildes* argument is not a valid open file descriptor, or the argument *cmd* is F\_SETLK or F\_SETLKW, the type of lock, *l\_type*, is a shared lock (F\_RDLCK), and *fildes* is not a valid file descriptor open for reading, or the type of lock, *l\_type*, is an exclusive lock (F\_WRLCK), and *fildes* is not a valid file descriptor open for writing. - **EINTR** The *cmd* argument is F\_SETLKW and the function was interrupted by a signal. - **EINVAL** The *cmd* argument is invalid, or the *cmd* argument is F\_DUPFD or F\_DUPFD\_CLOEXEC and *arg* is negative or greater than or equal to {OPEN\_MAX}, or the *cmd* argument is F\_GETLK, F\_SETLK, or F\_SETLKW and the data pointed to by *arg* is not valid, or *fildes* refers to a file that does not support locking. - **EMFILE** The argument *cmd* is F\_DUPFD or F\_DUPFD\_CLOEXEC and all file descriptors available to the process are currently open, or no file descriptors greater than or equal to *arg* are available. - **ENOLCK** The argument *cmd* is F\_SETLK or F\_SETLKW and satisfying the lock or unlock request would result in the number of locked regions in the system exceeding a system-imposed limit. - **EOVERFLOW** One of the values to be returned cannot be represented correctly. - **EOVERFLOW** The *cmd* argument is F\_GETLK, F\_SETLK, or F\_SETLKW and the smallest or, if *l\_len* is non-zero, the largest offset of any byte in the requested segment cannot be represented correctly in an object of type **off\_t**. - **ESRCH** The *cmd* argument is F\_SETOWN and no process or process group can be found corresponding to that specified by *arg*.\ The *fcntl*() function may fail if: - **EDEADLK** The *cmd* argument is F\_SETLKW, the lock is blocked by a lock from another process, and putting the calling process to sleep to wait for that lock to become free would cause a deadlock. - **EINVAL** The *cmd* argument is F\_SETOWN and the value of the argument is not valid as a process or process group identifier. - **EPERM** The *cmd* argument is F\_SETOWN and the calling process does not have permission to send a SIGURG signal to any process specified by *arg*. *The following sections are informative.* ## EXAMPLES ### Locking and Unlocking a File The following example demonstrates how to place a lock on bytes 100 to 109 of a file and then later remove it. F\_SETLK is used to perform a non-blocking lock request so that the process does not have to wait if an incompatible lock is held by another process; instead the process can take some other action. ``` #include #include #include #include #include ``` int main(int argc, char \*argv\[\]) {\ int fd;\ struct flock fl; fd = open("testfile", O\_RDWR);\ if (fd == -1)\ /\* Handle error \*/; /\* Make a non-blocking request to place a write lock\ on bytes 100-109 of testfile \*/ fl.l\_type = F\_WRLCK;\ fl.l\_whence = SEEK\_SET;\ fl.l\_start = 100;\ fl.l\_len = 10; if (fcntl(fd, F\_SETLK, &fl) == -1) {\ if (errno == EACCES \|\| errno == EAGAIN) {\ printf("Already locked by another process\\n"); /\* We cannot get the lock at the moment \*/ } else {\ /\* Handle unexpected error \*/;\ }\ } else { /\* Lock was granted... \*/ /\* Perform I/O on bytes 100 to 109 of file \*/ /\* Unlock the locked bytes \*/ fl.l\_type = F\_UNLCK;\ fl.l\_whence = SEEK\_SET;\ fl.l\_start = 100;\ fl.l\_len = 10;\ if (fcntl(fd, F\_SETLK, &fl) == -1)\ /\* Handle error \*/;\ }\ exit(EXIT\_SUCCESS); } /\* main \*/ ### Setting the Close-on-Exec Flag The following example demonstrates how to set the close-on-exec flag for the file descriptor *fd*. ``` #include #include ... int flags; ``` flags = fcntl(fd, F\_GETFD);\ if (flags == -1)\ /\* Handle error \*/;\ flags \|= FD\_CLOEXEC;\ if (fcntl(fd, F\_SETFD, flags) == -1)\ /\* Handle error \*/;" ## APPLICATION USAGE The *arg* values to F\_GETFD, F\_SETFD, F\_GETFL, and F\_SETFL all represent flag values to allow for future growth. Applications using these functions should do a read-modify-write operation on them, rather than assuming that only the values defined by this volume of POSIX.1‐2017 are valid. It is a common error to forget this, particularly in the case of F\_SETFD. Some implementations set additional file status flags to advise the application of default behavior, even though the application did not request these flags. On systems which do not perform permission checks at the time of an *fcntl*() call with F\_SETOWN, if the permission checks performed at the time the signal is sent disallow sending the signal to any process, the process that called *fcntl*() has no way of discovering that this has happened. A call to *kill*() with signal 0 can be used as a prior check of permissions, although this is no guarantee that permission will be granted at the time a signal is sent, since the target process(es) could change user IDs or privileges in the meantime. ## RATIONALE The ellipsis in the SYNOPSIS is the syntax specified by the ISO C standard for a variable number of arguments. It is used because System V uses pointers for the implementation of file locking functions. This volume of POSIX.1‐2017 permits concurrent read and write access to file data using the *fcntl*() function; this is a change from the 1984 /usr/group standard and early proposals. Without concurrency controls, this feature may not be fully utilized without occasional loss of data. Data losses occur in several ways. One case occurs when several processes try to update the same record, without sequencing controls; several updates may occur in parallel and the last writer \`\`wins''. Another case is a bit-tree or other internal list-based database that is undergoing reorganization. Without exclusive use to the tree segment by the updating process, other reading processes chance getting lost in the database when the index blocks are split, condensed, inserted, or deleted. While *fcntl*() is useful for many applications, it is not intended to be overly general and does not handle the bit-tree example well. This facility is only required for regular files because it is not appropriate for many devices such as terminals and network connections. Since *fcntl*() works with \`\`any file descriptor associated with that file, however it is obtained'', the file descriptor may have been inherited through a *fork*() or *exec* operation and thus may affect a file that another process also has open. The use of the open file description to identify what to lock requires extra calls and presents problems if several processes are sharing an open file description, but there are too many implementations of the existing mechanism for this volume of POSIX.1‐2017 to use different specifications. Another consequence of this model is that closing any file descriptor for a given file (whether or not it is the same open file description that created the lock) causes the locks on that file to be relinquished for that process. Equivalently, any close for any file/process pair relinquishes the locks owned on that file for that process. But note that while an open file description may be shared through *fork*(), locks are not inherited through *fork*(). Yet locks may be inherited through one of the *exec* functions. The identification of a machine in a network environment is outside the scope of this volume of POSIX.1‐2017. Thus, an *l\_sysid* member, such as found in System V, is not included in the locking structure. Changing of lock types can result in a previously locked region being split into smaller regions. Mandatory locking was a major feature of the 1984 /usr/group standard. For advisory file record locking to be effective, all processes that have access to a file must cooperate and use the advisory mechanism before doing I/O on the file. Enforcement-mode record locking is important when it cannot be assumed that all processes are cooperating. For example, if one user uses an editor to update a file at the same time that a second user executes another process that updates the same file and if only one of the two processes is using advisory locking, the processes are not cooperating. Enforcement-mode record locking would protect against accidental collisions. Secondly, advisory record locking requires a process using locking to bracket each I/O operation with lock (or test) and unlock operations. With enforcement-mode file and record locking, a process can lock the file once and unlock when all I/O operations have been completed. Enforcement-mode record locking provides a base that can be enhanced; for example, with sharable locks. That is, the mechanism could be enhanced to allow a process to lock a file so other processes could read it, but none of them could write it. Mandatory locks were omitted for several reasons: - 1\. Mandatory lock setting was done by multiplexing the set-group-ID bit in most implementations; this was confusing, at best. - 2\. The relationship to file truncation as supported in 4.2 BSD was not well specified. - 3\. Any publicly readable file could be locked by anyone. Many historical implementations keep the password database in a publicly readable file. A malicious user could thus prohibit logins. Another possibility would be to hold open a long-distance telephone line. - 4\. Some demand-paged historical implementations offer memory mapped files, and enforcement cannot be done on that type of file. Since sleeping on a region is interrupted with any signal, *alarm*() may be used to provide a timeout facility in applications requiring it. This is useful in deadlock detection. Since implementation of full deadlock detection is not always feasible, the **\[EDEADLK\]** error was made optional. ## FUTURE DIRECTIONS None. ## SEE ALSO *alarm()*, *close()*, *exec*, *kill()*, *open()*, *sigaction()* The Base Definitions volume of POSIX.1‐2017, ***\***, ***\*** ## COPYRIGHT Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html . Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting\_bugs.html .