fcntl(2) System Calls Manual fcntl(2) fcntl - C (libc, -lc) #include int fcntl(int fd, int op, ... /* arg */ ); fcntl() performs one of the operations described below on the open file descriptor fd. The operation is determined by op. fcntl() can take an optional third argument. Whether or not this argument is required is determined by op. The required argument type is indicated in parentheses after each op name (in most cases, the required type is int, and we identify the argument using the name arg), or void is specified if the argument is not required. Certain of the operations below are supported only since a particular Linux kernel version. The preferred method of checking whether the host kernel supports a particular operation is to invoke fcntl() with the desired op value and then test whether the call failed with EINVAL, indicating that the kernel does not recognize this value. F_DUPFD (int) fd, , arg. dup2(2) , . , . dup(2). F_DUPFD_CLOEXEC (int; Linux 2.6.24) F_DUPFD, --. fcntl() F_SETFD FD_CLOEXEC. , , O_CLOEXEC open(2). The following operations manipulate the flags associated with a file descriptor. Currently, only one such flag is defined: FD_CLOEXEC, the close-on-exec flag. If the FD_CLOEXEC bit is set, the file descriptor will automatically be closed during a successful execve(2). (If the execve(2) fails, the file descriptor is left open.) If the FD_CLOEXEC bit is not set, the file descriptor will remain open across an execve(2). F_GETFD (void) ( ) ; arg . F_SETFD (int) , arg. fcntl() F_SETFD close-on-exec fork(2) execve(2) , , . O_CLOEXEC open(2) . , open(2) , , fcntl(). ( dup(2), fcntl(F_DUPFD), fork(2) ..), . open(2). F_GETFL (void) ( ) ; arg . F_SETFL (int) Set the file status flags to the value specified by arg. File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this operation can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below. (advisory) Linux (<<>>) UNIX, POSIX. Linux- . F_SETLK, F_SETLKW F_GETLK , ( , ). , lock, , , , ( ): struct flock { ... short l_type; /* : F_RDLCK, F_WRLCK, F_UNLCK */ short l_whence; /* l_start: SEEK_SET, SEEK_CUR, SEEK_END */ off_t l_start; /* */ off_t l_len; /* */ pid_t l_pid; /* PID , ( F_GETLK F_OFD_GETLK) */ ... }; l_whence, l_start l_len , . , . l_start -- , ( l_whence SEEK_SET); ( l_whence SEEK_CUR); ( l_whence SEEK_END). , l_start , , . l_len , . l_len , l_start l_start+l_len-1 . l_len 0, , l_whence l_start , . POSIX.1-2001 allows (but does not require) an implementation to support a negative l_len value; if l_len is negative, the interval described by lock covers bytes l_start+l_len up to and including l_start-1. This is supported since Linux 2.4.21 and Linux 2.5.49. l_type : (F_RDLCK) (F_WRLCK). ( ) , ( ). , . ; , . ( , , , , .) F_SETLK (struct flock *) ( l_type F_RDLCK F_WRLCK) ( l_type F_UNLCK) , l_whence, l_start l_len lock. , -1 errno EACCES EAGAIN (, , , POSIX ). F_SETLKW (struct flock *) F_SETLK, , . , ( ) ( -1 errno EINTR; . signal(7)). F_GETLK (struct flock *) , lock , . , fcntl() , F_UNLCK l_type lock . , fcntl() l_type, l_whence, l_start l_len lock. (), l_pid PID , . , l_pid -1. , . , , fd . , , fd . , . F_SETLKW, (deadlocks), , , . , , 100, 200. , F_SETLKW, . EDEADLK; , , , , . . , ; . F_UNLCK, , . , fork(2), execve(2). stdio(3), ; read(2) write(2). , , ( , ). : o , , , (), . : , , /etc/passwd /etc/mtab, - , . o . . . ( POSIX) , , . Linux 3.15 ( Austin Group POSIX.1). open(2). , , , ( , flock(2). ( ), fork(2) ( clone(2) CLONE_FILES), , . ( ), -- , -- , . , (. ., , fork(2), dup(2), fcntl() F_DUPFD . .), : , ( , , ). , , . , , open(2) . As with traditional advisory locks, the third argument to fcntl(), lock, is a pointer to an flock structure. By contrast with traditional record locks, the l_pid field of that structure must be set to zero when using the operations described below. The operations for working with open file description locks are analogous to those used with traditional locks: F_OFD_SETLK (struct flock *) ( l_type F_RDLCK F_WRLCK) ( l_type F_UNLCK) , l_whence, l_start l_len lock. , -1 errno EAGAIN. F_OFD_SETLKW (struct flock *) F_OFD_SETLK, , . , ( ) ( -1 errno EINTR; . signal(7)). F_OFD_GETLK (struct flock *) lock , . , fcntl() , F_UNLCK l_type lock, . , , lock , F_GETLK. ( , ). (mandatory) Warning: the Linux implementation of mandatory locking is unreliable. See BUGS below. Because of these bugs, and the fact that the feature is believed to be little used, since Linux 4.5, mandatory locking has been made an optional feature, governed by a configuration option (CONFIG_MANDATORY_FILE_LOCKING). This feature is no longer supported at all in Linux 5.15 and above. , ( ) . . . (, read(2) write(2)) , , O_NONBLOCK . O_NONBLOCK , , . O_NONBLOCK , EAGAIN. , , , . <<-o mand>> mount(8) MS_MANDLOCK mount(2). set-group-ID (. chmod(1) chmod(2)). POSIX. , . , NFS, . - (. ., ), , . , , read(2) write(2) EIO. , . Linux 3.12, , , NFSv4 ( ). UNIX (SIGLOST). Linux - . / F_GETOWN, F_SETOWN, F_GETOWN_EX, F_SETOWN_EX, F_GETSIG F_SETSIG: F_GETOWN (void) Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd. Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored. F_SETOWN (int) , SIGIO SIGURG fd. arg. , . , ( arg getpid(2)). As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL operation to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG operation can be used to obtain delivery of a signal other than SIGIO. - (), F_SETOWN -- , kill(2), , F_SETOWN ( ). , . : F_SETOWN fcntl(), . fd , F_SETOWN SIGURG, , . (SIGURG , select(2) , " ".) The following was true in Linux 2.6.x up to and including Linux 2.6.11: F_SETSIG , (, NPTL), , , F_SETOWN, : ID , , ID , . F_SETOWN gettid(2), getpid(2), F_SETSIG. ( Linux ID ID . , , gettid(2) getpid(2), .) , SIGURG, : , , F_SETOWN. Linux 2.6.12, . Linux 2.6.32 F_SETOWN_EX SIGIO SIGURG . F_GETOWN_EX (struct f_owner_ex *) ( Linux 2.6.32) , F_SETOWN_EX. , arg, : struct f_owner_ex { int type; pid_t pid; }; type : F_OWNER_TID, F_OWNER_PID F_OWNER_PGRP. pid , ID , ID ID . F_SETOWN_EX. F_SETOWN_EX (struct f_owner_ex *) ( Linux 2.6.32) , F_SETOWN. - , . arg, f_owner_ex. type , pid: F_OWNER_TID , ID (, clone(2) gettid(2)) pid. F_OWNER_PID , ID pid. F_OWNER_PGRP , ID pid. (, F_SETOWN, ID .) F_GETSIG (void) ( ) , , . 0 SIGIO. ( SIGIO) , , SA_SIGINFO. arg . F_SETSIG (int) , , , arg. 0 SIGIO. ( SIGIO) , , , SA_SIGINFO. F_SETSIG SA_SIGINFO (. sigaction(2)) / siginfo_t. si_code , -- SI_SIGIO, si_fd , . , , (select(2), poll(2), read(2) O_NONBLOCK ..), /. , , si_fd, , F_SETSIG. . (dup(2) ), , - , si_fd . ( >= SIGRTMIN) - ( ). , SA_SIGINFO. , Linux , (. getrlimit(2) signal(7)), , SIGIO, , . , - select(2) poll(2). The use of O_ASYNC is specific to BSD and Linux. The only use of F_GETOWN and F_SETOWN specified in POSIX.1 is in conjunction with the use of the SIGURG signal on sockets. (POSIX does not specify the SIGIO signal.) F_GETOWN_EX, F_SETOWN_EX, F_GETSIG, and F_SETSIG are Linux-specific. POSIX has asynchronous I/O and the aio_sigevent structure to achieve similar things; these are also available in Linux as part of the GNU C Library (glibc). F_SETLEASE F_GETLEASE ( Linux 2.4 ) , fd. , , (<<>>), ( ), (<< >>) open(2) truncate(2) , . F_SETLEASE (int) , , arg: F_RDLCK . , . , . F_WRLCK . , . , . F_UNLCK . (. open(2)). , (, , fork(2) dup(2)) , . , F_UNLCK , . . , UID () UID . CAP_LEASE . F_GETLEASE (void) fd; F_RDLCK, F_WRLCK F_UNLCK, , . arg . When a process (the "lease breaker") performs an open(2) or truncate(2) that conflicts with a lease established via F_SETLEASE, the system call is blocked by the kernel and the kernel notifies the lease holder by sending it a signal (SIGIO by default). The lease holder should respond to receipt of this signal by doing whatever cleanup is required in preparation for the file to be accessed by another process (e.g., flushing cached buffers) and then either remove or downgrade its lease. A lease is removed by performing an F_SETLEASE operation specifying arg as F_UNLCK. If the lease holder currently holds a write lease on the file, and the lease breaker is opening the file for reading, then it is sufficient for the lease holder to downgrade the lease to a read lease. This is done by performing an F_SETLEASE operation specifying arg as F_RDLCK. , /proc/sys/fs/lease-break-time, . , , F_GETLEASE ( F_RDLCK F_UNLCK, ) , . , , , . , open(2) truncate(2), , EINTR, - . open(2) truncate(2), - . O_NONBLOCK open(2), EWOULDBLOCK, - . The default signal used to notify the lease holder is SIGIO, but this can be changed using the F_SETSIG operation to fcntl(). If a F_SETSIG operation is performed (even one specifying SIGIO), and the signal handler is established using SA_SIGINFO, then the handler will receive a siginfo_t structure as its second argument, and the si_fd field of this argument will hold the file descriptor of the leased file that has been accessed by another process. (This is useful if the caller holds leases against multiple files.) (dnotify) F_NOTIFY (int) ( Linux 2.4) , fd , . , , arg, , (OR) : DN_ACCESS (read(2), pread(2), readv(2) ). DN_MODIFY (write(2), pwrite(2), writev(2), truncate(2), ftruncate(2) ). DN_CREATE (open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), rename(2) ). DN_DELETE (unlink(2), rename(2) , rmdir(2)). DN_RENAME (rename(2)). DN_ATTRIB (chown(2), chmod(2), utime(2), utimensat(2) ). ( , _GNU_SOURCE .) , . , arg, DN_MULTISHOT, , . F_NOTIFY arg, . , F_NOTIFY, 0 arg. Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG operation to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories). , DN_MULTISHOT, , . NOTE: New applications should use the inotify interface (available since Linux 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7). F_SETPIPE_SZ (int; Linux 2.6.35) , fd; arg . , , /proc/sys/fs/pipe-max-size ( proc(5)). , . /proc/sys/fs/pipe-max-size EPERM; ( CAP_SYS_RESOURCE) . arg, ( ). ( ) . , EBUSY. , - , , , , . F_GETPIPE_SZ (void; Linux 2.6.35) ( ) , fd. (file sealing) . , , EPERM. , . , memfd_create(2). , memfd_create(2) ( MFD_ALLOW_SEALING). fcntl(), , EINVAL. (seals) -- inode. , inode, . , , . F_ADD_SEALS (int; Linux 3.17) arg inode, fd. . , . F_SEAL_SEAL ( ), EPERM. , F_SEAL_SEAL. fd . F_GET_SEALS (void; Linux 3.17) ( ) inode, fd. , 0. , -1 errno EINVAL. : F_SEAL_SEAL , fcntl() F_ADD_SEALS EPERM. , . F_SEAL_SEAL, . F_SEAL_SHRINK , . open(2) O_TRUNC, truncate(2) ftruncate(2). EPERM, . - . F_SEAL_GROW , . write(2) , truncate(2), ftruncate(2) fallocate(2). EPERM, . - . F_SEAL_WRITE , . , - . , , . write(2) fallocate(2) ( FALLOC_FL_PUNCH_HOLE). EPERM. , , mmap(2) EPERM. F_ADD_SEALS F_SEAL_WRITE EBUSY, . . , , - (io_submit(2)), . F_SEAL_FUTURE_WRITE ( Linux 5.1) The effect of this seal is similar to F_SEAL_WRITE, but the contents of the file can still be modified via shared writable mappings that were created prior to the seal being set. Any attempt to create a new writable mapping on the file via mmap(2) will fail with EPERM. Likewise, an attempt to write to the file via write(2) will fail with EPERM. Using this seal, one process can create a memory buffer that it can continue to modify while sharing that buffer on a "read-only" basis with other processes. / ( open(2)). << >> (write lifetime) , . , , , , - . , - , - , . fd: F_GET_RW_HINT (uint64_t *; Linux 4.13) /, , fd. F_SET_RW_HINT (uint64_t *; Linux 4.13) /, , fd. , . F_GET_FILE_RW_HINT (uint64_t *; Linux 4.13) /, , fd. F_SET_FILE_RW_HINT (uint64_t *; Linux 4.13) /, , fd. /, ( ), . Linux 4.13, /: RWH_WRITE_LIFE_NOT_SET . . RWH_WRITE_LIFE_NONE , , . RWH_WRITE_LIFE_SHORT , , , . RWH_WRITE_LIFE_MEDIUM , , , , , RWH_WRITE_LIFE_SHORT. RWH_WRITE_LIFE_LONG , , , , , RWH_WRITE_LIFE_MEDIUM. RWH_WRITE_LIFE_EXTREME , , , , , RWH_WRITE_LIFE_LONG. . : F_DUPFD . F_GETFD . F_GETFL . F_GETLEASE , . F_GETOWN , . F_GETSIG , SIGIO. F_GETPIPE_SZ F_SETPIPE_SZ . F_GET_SEALS , inode, fd. All other operations . -1, errno . EACCES EAGAIN , . EAGAIN , . EBADF fd . EBADF op is F_SETLK or F_SETLKW and the file descriptor open mode doesn't match with the type of lock requested. EBUSY op is F_SETPIPE_SZ and the new pipe capacity specified in arg is smaller than the amount of buffer space currently used to store data in the pipe. EBUSY op is F_ADD_SEALS, arg includes F_SEAL_WRITE, and there exists a writable, shared mapping on the file referred to by fd. EDEADLK It was detected that the specified F_SETLKW operation would cause a deadlock. EFAULT lock . EINTR op is F_SETLKW or F_OFD_SETLKW and the operation was interrupted by a signal; see signal(7). EINTR op is F_GETLK, F_SETLK, F_OFD_GETLK, or F_OFD_SETLK, and the operation was interrupted by a signal before the lock was checked or acquired. Most likely when locking a remote file (e.g., locking over NFS), but can sometimes happen locally. EINVAL The value specified in op is not recognized by this kernel. EINVAL op is F_ADD_SEALS and arg includes an unrecognized sealing bit. EINVAL op is F_ADD_SEALS or F_GET_SEALS and the filesystem containing the inode referred to by fd does not support sealing. EINVAL op is F_DUPFD and arg is negative or is greater than the maximum allowable value (see the discussion of RLIMIT_NOFILE in getrlimit(2)). EINVAL op is F_SETSIG and arg is not an allowable signal number. EINVAL op is F_OFD_SETLK, F_OFD_SETLKW, or F_OFD_GETLK, and l_pid was not specified as zero. EMFILE op is F_DUPFD and the per-process limit on the number of open file descriptors has been reached. ENOLCK , (, NFS). ENOTDIR F_NOTIFY was specified in op, but fd does not refer to a directory. EPERM op is F_SETPIPE_SZ and the soft or hard user pipe limit has been reached; see pipe(7). EPERM O_APPEND , . EPERM op was F_ADD_SEALS, but fd was not open for writing or the current set of seals on the file already includes F_SEAL_SEAL. POSIX.1-2008. F_GETOWN_EX, F_SETOWN_EX, F_SETPIPE_SZ, F_GETPIPE_SZ, F_GETSIG, F_SETSIG, F_NOTIFY, F_GETLEASE F_SETLEASE Linux. _GNU_SOURCE. F_OFD_SETLK, F_OFD_SETLKW F_OFD_GETLK Linux ( _GNU_SOURCE), POSIX.1. F_ADD_SEALS F_GET_SEALS Linux. SVr4, 4.3BSD, POSIX.1-2001. Only the operations F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK, and F_SETLKW are specified in POSIX.1-2001. F_GETOWN F_SETOWN POSIX.1-2001. , _XOPEN_SOURCE 500 _POSIX_C_SOURCE 200809L . F_DUPFD_CLOEXEC POSIX.1-2008. , _POSIX_C_SOURCE 200809L , _XOPEN_SOURCE 700 . , dup2(2), , F_DUPFD. The original Linux fcntl() system call was not designed to handle large file offsets (in the flock structure). Consequently, an fcntl64() system call was added in Linux 2.4. The newer system call employs a different structure for file locking, flock64, and corresponding operations, F_GETLK64, F_SETLK64, and F_SETLKW64. However, these details can be ignored by applications using glibc, whose fcntl() wrapper function transparently employs the more recent system call where it is available. (Record locks) Since Linux 2.0, there is no interaction between the types of lock placed by flock(2) and fcntl(). struct flock, , l_sysid ( , ). , l_pid , , , ; Linux, (, MIPS32), . The original Linux fcntl() system call was not designed to handle large file offsets (in the flock structure). Consequently, an fcntl64() system call was added in Linux 2.4. The newer system call employs a different structure for file locking, flock64, and corresponding operations, F_GETLK64, F_SETLK64, and F_SETLKW64. However, these details can be ignored by applications using glibc, whose fcntl() wrapper function transparently employs the more recent system call where it is available. NFS Linux 3.12, NFSv4 ( 90 ), ( , NFSv4 (leasetime). Linux NFS /proc/fs/nfsd/nfsv4leasetime, . 90). , -. Linux 3.12, NFSv4 , -, , <<>>, , , . , pre-3.12, nfs.recover_lost_locks 1, - . - , 0 (). F_SETFL F_SETFL O_DSYNC O_SYNC. . F_GETOWN A limitation of the Linux system call conventions on some architectures (notably i386) means that if a (negative) process group ID to be returned by F_GETOWN falls in the range -1 to -4095, then the return value is wrongly interpreted by glibc as an error in the system call; that is, the return value of fcntl() will be -1, and errno will contain the (positive) process group ID. The Linux-specific F_GETOWN_EX operation avoids this problem. Since glibc 2.11, glibc makes the kernel F_GETOWN problem invisible by implementing F_GETOWN using F_GETOWN_EX. F_SETOWN Linux 2.4 , , F_SETOWN () . fcntl() -1 errno EPERM, () . , . (deadlock) F_SETLKW ( ), ( EDEADLK, ). , 10, , , , . , , clone(2) CLONE_FILES, , ( ) . (mandatory) Linux , : write(2), , ; read(2), , , . mmap(2). . dup2(2), flock(2), open(2), socket(2), lockf(3), capabilities(7), feature_test_macros(7), lslocks(8) locks.txt, mandatory-locking.txt dnotify.txt Documentation/filesystems. Linux ( Documentation/, mandatory-locking.txt mandatory.txt). () Azamat Hackimov , Dmitry Bolkhovskikh , Yuri Kozlov ; GNU (GNU General Public License - GPL, 3 ) , - . - , , () () () <>. Linux 6.9.1 2 2024 . fcntl(2)