FCNTL(2) COMMAND REFERENCE FCNTL(2) NAME fcntl - file control SYNOPSIS #include <fcntl.h> result = fcntl(fd, cmd, arg) int result; int fd, cmd, arg; DESCRIPTION The program fcntl performs a variety of functions on open descriptors (the argument fd is an open descriptor operated on by cmd as follows): The value of result and arg depends on cmd; cmd is one of the following, defined in <fcntl.h>: F_DUPFD Return a new descriptor as follows: Lowest numbered available descriptor greater than or equal to arg. Same object references as the original descriptor. New descriptor shares the same file pointer if the object was a file. Same access mode (read, write or read/write). Same file status flags (i.e., 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 execve(2) system calls. F_GETFD Get the close-on-exec flag associated with the file descriptor fd. If the low-order bit is 0, the file remains open across execve calls, otherwise the file is closed upon execution of execve calls. F_SETFD Set the close-on-exec flag associated with fd to the low order bit of arg (0 or 1 as above). F_GETFL Get descriptor status flags. F_SETFL Set descriptor status flags to arg. (Arg is created by or'ing FNDELAY, FAPPEND, and FASYNC. F_GETLK Get a description of the first lock which would block the lock specified in the flock structure pointed to by arg. The information retrieved Printed 5/12/88 1
FCNTL(2) COMMAND REFERENCE FCNTL(2) overwrites the information 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 will be set to F_UNLCK. F_SETLK Set or clear an advisory record lock according to the flock structure pointed to by arg. F_SETLK establishes shared (F_RDLCK) and exclusive (F_WRLCK) locks, or it can be used to remove either type of lock (F_UNLCK). If the specified lock cannot be applied, fcntl returns with an error value of -1. F_SETLKW This cmd is the same as F_SETLK except that if a shared or exclusive lock is blocked by other locks, the requesting process sleeps until the lock may be applied. F_GETOWN Get the process group currently receiving SIGIO and SIGURG signals; process groups are returned as negative values. F_SETOWN Set the process group to receive SIGIO and SIGURG signals. If arg is negative, it is interpreted as a process group number. If arg is positive, it is interpreted as a process ID and the associated process group is used. The SIGIO facilities are enabled by setting the FASYNC flag with F_SETFL. The flags for the F_GETFL and F_SETFL are as follows, defined in <sys/file.h>: FNDELAY Non-blocking I/O; if no data is available to a read call, or if a write operation would block, the call returns -1 with the error EWOULDBLOCK. FAPPEND Force each write to append at the end-of-file; corresponds to the O_APPEND flag of open(2). FASYNC Enable the SIGIO signal to be sent to the process group when I/O is possible (e.g., upon availability of data to be read) and enable the SIGURG signal to be sent when an exception occurs. Notes Advisory locks allow cooperating processes to perform consistent operations on files, but do not guarantee exclusive access (i.e., processes may still access files Printed 5/12/88 2
FCNTL(2) COMMAND REFERENCE FCNTL(2) without using advisory locks, possibly resulting in inconsistencies). The record locking mechanism allows two types of locks: shared locks (F_RDLCK) and exclusive locks (F_WRLCK). More than one process may hold a shared lock for a particular segment of a file at any given time, but multiple exclusive, or both shared and exclusive locks may not exist simultaneously on any segment. In order to claim a shared lock, the descriptor must have been opened with read access. The descriptor on which an exclusive lock is being placed must have been opened with write access. A shared lock may be upgraded to an exclusive lock, and vice versa, simply by specifying the appropriate lock type with a cmd of F_SETLK or F_SETLKW; the previous lock will be released and the new lock applied (possibly after other processes have gained and released the lock). If the cmd is F_SETLKW and the requested lock cannot be claimed immediately (e.g., another process holds an exclusive lock that partially or completely overlaps the current request) the calling process blocks until the lock may be acquired. Processes blocked awaiting a lock may be awakened by signals. Care should be taken to avoid deadlock situations in applications in which multiple processes perform blocking locks on a set of common records. The record that is to be locked or unlocked is described by the flock structure, defined in <fcntl.h>: struct flock { short l_type; /* F_RDLCK, F_WRLCK, or F_UNLCK */ short l_whence; /* flag to choose starting offset */ long l_start; /* relative offset in bytes */ long l_len; /* length in bytes; 0 means lock to EOF */ short l_pid; /* returned with F_GETLK */ }; The flock structure describes the type (l_type), starting offset (l_whence), relative offset (l_start), and size (l_len) of the segment of the file affected; l_whence must be set to 0, 1, or 2, indicating that the relative offset will be measured from the start of the file, current position, or end-of-file, respectively. The process id file Printed 5/12/88 3
FCNTL(2) COMMAND REFERENCE FCNTL(2) (l_pid) is only used with the F_GETLK cmd to return the description of a lock held by another process. Locks may start and extend beyond the current end-of-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 l_len to zero (0). If such a lock also has l_whence and l_start set to zero (0), the entire file is locked. Changing or unlocking a segment from the middle of a larger locked segment leaves two smaller segments at 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 removed when the file is closed or the process terminates. Locks are not inherited by the child process in a fork(2) system call. In order to maintain consistency in the network case, data must not be cached on client machines. For this reason, file buffering for an NFS file is turned off when the first lock is attempted on the file. Buffering will remain off as long as the file is open. Programs that do I/O buffering in the user address space, however, may have inconsistent results (the standard I/O package, for instance, is a common source of unexpected buffering). The advisory record locking capabilities of fcntl are implemented throughout the network by the network lock daemon; see lockd(8c). If the file server crashes and is rebooted, the lock daemon will attempt to recover all locks that were associated with that server. If a lock cannot be reclaimed, the process that held the lock will be issued a SIGLOST signal. DIAGNOSTICS The program fcntl fails if one or more of the following are true: [EBADF] Fd is not a valid open file descriptor. [EINVAL] Cmd or arg is an invalid value. [EMFILE] Cmd is F_DUPFD and NOFILE (defined in <sys/max.h>) file descriptors are currently open. [EINVAL] Cmd is F_DUPFD and arg is negative or greater than NOFILE (defined in <sys/max.h>). (See getdtablesize(2)). [EINVAL] Cmd is F_SETOWN and arg is not a valid process ID. [EFAULT] Cmd is F_GETLK, F_SETLK, or F_SETLKW and arg Printed 5/12/88 4
FCNTL(2) COMMAND REFERENCE FCNTL(2) points to an invalid address. [EINVAL] Cmd is F_GETLK, F_SETLK, or F_SETLKW and the data arg points to is not valid. [EBADF] Cmd is F_SETLK or F_SETLKW and the process does not have the appropriate read or write permissions on the file. [EAGAIN] Cmd is F_SETLK, the lock type (l_type) is F_RDLCK (shared lock), and the segment of the file to be locked already has an exclusive lock held by another process. This error will also be returned if the lock type is F_WRLCK (exclusive lock) and another process already has the segment locked with either a shared or exclusive lock. [EINTR] Cmd is F_SETLKW and a signal interrupted the process while it was waiting for the lock to be granted. [ENOLCK] Cmd is F_SETLK or F_SETLKW and there are no more file lock entires available. [ENOTTY] Cmd is not a valid request for the type of object associated with fd. [ENXIO] Cmd was attempted on a special device which does not exist, or beyond the limits of the device. [EIO] An I/O error occurred while accessing the file system. [ENODEV] Fd is a device, and cmd is an inappropriate request for that device. RETURN VALUE 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 flags, or'd together. F_GETOWN Value of file descriptor owner. other Value other than -1. Otherwise, a value of -1 is returned and errno is set to indicate the error. CAVEATS The asynchronous I/O facilities of FNDELAY and FASYNC are currently available only for tty operations. No SIGIO Printed 5/12/88 5
FCNTL(2) COMMAND REFERENCE FCNTL(2) signal is sent upon draining of output sufficiently for non-blocking writes to occur. File locks obtained through the fcntl mechanism do not interact in any way with those acquired via flock(2); they do, however, work correctly with the exclusive locks claimed by by lockf(3). F_GETLK returns F_UNLCK if the requesting process holds the specified lock. Thus, there is no way for a process to determine if it is still holding a specific lock after catching a SIGLOST signal. SEE ALSO close(2), execve(2), getdtablesize(2), open(2), sigvec(2), execl(3c), lockf(3), and lockd(8c). Printed 5/12/88 6
%%index%% na:264,72; sy:336,839; de:1175,2004;3515,2489;6340,2373;9049,1893; di:10942,868;12146,1484; rv:13630,575; ca:14205,201;14742,602; se:15344,338; %%index%%000000000177