fcntl(S) 6 January 1993 fcntl(S) Name fcntl - file control Syntax cc . . . -lc #include <fcntl.h> int fcntl (fildes, cmd, arg) int fildes, cmd; Description The fcntl system call provides for control over open files. The fildes argument is an open file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. The data type and value of arg are specific to the type of command specified by cmd. The symbolic names for commands and file status flags are defined by the <fcntl.h> header file. The commands available are: FDUPFD Return a new file descriptor as follows: + Lowest numbered available file descriptor greater than or equal to arg. + Same open file (or pipe) as the original file. + Same file pointer as the original file (that is, both file descriptors share one file pointer). + Same access mode (read, write, or read/write). + Same file status flags (that is, both file descriptors share the same file status flags). + The close-on-exec flag associated with the new file descriptor is set to remain open across exec(S) system calls. FGETFD Get the close-on-exec flag associated with the file descrip- tor fildes. If the low-order bit is 0, the file remains open across exec; otherwise the file is closed upon execution of exec. FGETFL Get file status flags (see open(S)). FSETFD Set the close-on-exec flag associated with fildes to the low-order bit of arg (0 or 1 as above). FSETFL Set file status flags to arg. Only certain flags can be set; see fcntl(M). The following commands are used for file-locking and record-locking. Locks may be placed on an entire file or segments of a file. FGETLK Get the first lock that blocks the lock description given by the variable of type struct flock pointed to by arg. The in- formation retrieved overwrites the information passed to fcntl in the flock structure. If no lock is found that would prevent this lock from being created, then the structure is passed back unchanged except for the lock type which is set to FUNLCK. FSETLK Set or clear a file segment lock. According to the variable of type struct flock pointed to by arg (see fcntl(M)), the cmd FSETLK is used to establish read (FRDLCK) and write (FWRLCK) locks. It also is used to remove either type of lock (FUNLCK). If a read or write lock cannot be set, fcntl returns immediately with an error value of -1. FSETLKW This cmd is the same as FSETLK except that if a read or write lock is blocked by other locks, the process sleeps until the segment is free to be locked. A read lock prevents any process from write locking the protected area. More than one read lock may exist for a given segment of a file at a given time. The file descriptor on which a read lock is being placed must have been opened with read access. A write lock prevents any process from read-locking or write-locking the protected area. Only one write lock may exist for a given segment of a file at a given time. The file descriptor on which a write lock is being placed must have been opened with write access. The structure flock defined in the <fcntl.h> header file describes a lock. It describes the type (ltype), starting offset (lwhence), rela- tive offset (lstart), size (llen), and process-ID (lpid): short l_type; /* F_RDLCK, F_WRLCK, F_UNLCK */ short l_whence; /* flag for starting offset */ long l_start; /* relative offset in bytes */ long l_len; /* if 0 then until EOF */ short l_pid; /* returned with F_GETLK */ The value of lwhence is 0, 1, or 2 to indicate that the relative offset, lstart bytes, is measured from the start of the file, current position, or end of file, respectively. The value of llen is the number of con- secutive bytes to be locked. The process id is used only with the FGETLK cmd to return the values for a blocking lock. Locks may start and extend beyond the current end of a file, but may not be negative relative to the beginning of the file. A lock may be set to always extend to the end of file by setting llen to zero (0). If such a lock also has lwhence and lstart set to zero (0), the whole file is locked. Changing or unlocking a segment from the middle of a larger locked seg- ment leaves two smaller segments for either end. Locking a segment that is already locked by the calling process causes the old lock type to be removed and the new lock type to take effect. All locks associated with a file for a given process are removed when a file descriptor for that file is closed by that process or the process holding that file descrip- tor terminates. Locks are not inherited by a child process in a fork system call. When mandatory file and record locking is active on a file (see chmod(S)), read and write system calls issued on the file are affected by the record locks in effect. The fcntl system call fails if one or more of the following is true: [EACCES] The cmd argument is FSETLK, the type of lock (ltype) is a read (FRDLCK) lock, and the segment of a file to be locked is already write locked by another process or the type is a write (FWRLCK) lock and the segment of a file to be locked is already read or write locked by another process. [EBADF] 1. The fildes argument is not a valid open file descriptor. 2. The cmd argument is FSETLK or FSETLKW, the type of lock (ltype) is a read-lock (FRDLCK), and fildes is not a valid file-descriptor open for reading. 3. The cmd argument is FSETLK or FSETLKW, the type of lock (ltype) is a write-lock (FWRLCK), and fildes is not a valid file-descriptor open for writing. [EDEADLK] The cmd argument is FSETLKW, the lock is blocked by some lock from another process, and putting the calling-process to sleep, waiting for that lock to become free, would cause a deadlock. [EFAULT] The cmd argument is FSETLK, arg points outside the program address space. [EINTR] A signal was caught during the fcntl system call. [EINVAL] 1. The cmd argument is FDUPFD. The arg argument is either negative, or greater than or equal to the configured value for the maximum number of open file descriptors allowed each user. 2. The cmd argument is FGETLK, FSETLK, or SETLKW and arg or the data it points to is not valid. [EMFILE] The cmd argument is FDUPFD and file-descriptors are currently open in the calling-process. [ENOLCK] The cmd argument is FSETLK or FSETLKW, the type of lock is a read or write lock, and there are no more record locks available (too many file segments locked) because the system maximum has been exceeded. [ENOLINK] fildes is on a remote machine and the link to that machine is no longer active. Diagnostics Upon successful completion, the value returned depends on cmd as follows: F_DUPFD A new file descriptor. F_GETFD Value of flag (only the low-order bit is defined). F_GETFL Value of file flags. F_GETLK Value other than -1. F_SETFD Value other than -1. F_SETFL Value other than -1. F_SETLK Value other than -1. F_SETLKW Value other than -1. Otherwise, a value of -1 is returned, and errno is set to indicate the error. Warnings Because in the future the variable errno will be set to EAGAIN rather than EACCES when a section of a file is already locked by another pro- cess, portable application programs should expect and test for either value. See also close(S), creat(S), dup(S), exec(S), fcntl(M), fork(S), open(S), pipe(S) Standards conformance fcntl is conformant with: AT&T SVID Issue 2; X/Open Portability Guide, Issue 3, 1989; IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1); and NIST FIPS 151-1.