fcntl(2) fcntl(2)NAME fcntl - file control SYNOPSIS #include <sys/types.h> #include <fcntl.h> int fcntl(fildes, cmd, arg) int fildes, cmd, arg; DESCRIPTION fcntl provides for control over open files. The file descriptor fildes is an open file descriptor obtained from a creat, open, dup, fcntl, socket, or pipe system call. The cmd values are: F_DUPFD Return a new file descriptor as follows: Lowest-numbered file descriptor available, 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(2) system calls. F_GETFD Get the file descriptor flags that are associated with the file descriptor fildes. F_SETFD Set the file descriptor flags associated with fildes to arg, which is interpreted as type int. F_GETFL Get file status flags and file-access modes of fildes file. F_SETFL Set file status flags to arg for fildes file. Only certain flags can be set (see fcntl(5)). F_GETLK Get the first lock that blocks the lock descrip- tion given by the variable of type struct flock pointed to by arg. The information retrieved overwrites the information passed to fcntl in the April, 1990 1
fcntl(2) fcntl(2)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 will be set to F_UNLCK. F_SETLK Set or clear a file segment lock according to the variable of type struct flock pointed to by arg (see fcntl(5)). The cmd F_SETLK is used to estab- lish read (F_RDLCK) and write (F_WRLCK) locks as well as to remove either type of lock (F_UNLCK). If a read or write lock cannot be set, fcntl will return immediately with an error value of -1. F_SETLKW Does the same as F_SETLK except that if a read or write lock is blocked by other locks, the process will sleep until the segment is free to be locked. F_GETOWN Get the process ID or process group currently re- ceiving SIGIO and SIGURG signals. Process groups are returned as negative values. F_SETOWN Set the process or process group to receive SIGIO and SIGURG signals. Process groups are specified by supplying arg as a negative value; otherwise, arg is interpreted as a process ID. File descriptor flags, file status flags, and file-access modes are associated with one file descriptor and do not af- fect other file descriptors that refer to the same file. A read lock prevents any process from write-locking the pro- tected 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 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 af- fected. The process ID field is only used with the cmd F_GETLK to return the value for a block that is locked. 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 extend always to the end of a file by setting l_len to 0. If such a lock also has l_start set to 0, the whole file is locked. Changing or unlocking a 2 April, 1990
fcntl(2) fcntl(2)segment from the middle of a larger locked segment 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 affect. All locks associated with a file for a given process are re- moved when a file descriptor for that file is closed by that process or the process holding that file descriptor ter- minates. Locks are not inherited by a child process in a fork(2) system call. RETURN VALUE On 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 de- fined). F_SETFD Value other than -1. F_GETFL Value of file flags. 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 other than -1. F_SETOWN Value other than -1. Otherwise, a value of -1 is returned and errno is set to in- dicate the error. ERRORS fcntl will fail if one or more of the following are true: [EBADF] fildes is not a valid open file descriptor. [EMFILE] cmd is F_DUPFD, and the maximum number of file descriptors are currently open. [ENFILE] cmd is F_DUPFD, and arg is negative or greater than the maximum number of file descriptors currently open. [EINVAL] cmd is F_GETLK, F_SETLK, or SETLKW, and arg, or the data it points to is not valid. April, 1990 3
fcntl(2) fcntl(2)[EACCESS] cmd is F_SETLK, and the type of lock (l_type) is a read (F_RDLCK) or write (F_WRLCK) lock. Also the segment of a file to be locked is already write-locked by another process, or the type is a write lock and the segment of a file to be locked is already read-locked or write-locked by another process. [ENOLCK] cmd is F_SETLK or F_SETLKW, and the type of lock is a read or write lock. Also, no more file- locking headers are available (too many files have segments locked), or no more record locks are available (too many files have segments locked). [EDEADLK] cmd is F_SETLK. When the lock is blocked by some lock from another process and sleeping (waiting) until that lock becomes free, this causes a deadlock situation. [ENOTSOCK] cmd is F_GETOWN or F_SETOWN, and fildes is not a file descriptor for a socket. [EINVAL] The value of l-whence in the flock structure is invalid. SEE ALSO close(2), creat(2), dup(2), exec(2), ioctl(2), open(2), pipe(2), socket(2N), lockf(3C), fcntl(5). 4 April, 1990