fcntl(2)
NAME
fcntl − file control
SYNTAX
#include <fcntl.h>
int fcntl(fildes, cmd, arg)
int fildes, cmd, arg;
DESCRIPTION
The fcntl system call provides for control over open files. The specified fildes is an open file descriptor obtained from a creat, dup, fcntl, open, or pipe system call.
The cmd can be:
F_DUPFD 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 calls.
F_GETFD Get the “close-on-exec” flag associated with fildes. If the low-order bit is 0, the file will remain open across exec calls. Otherwise, the file will be closed upon execution of an exec call.
F_SETFD Set the “close-on-exec” flag associated with fildes to the low-order bit of arg ( 0 or 1).
F_GETFL Get file status flags.
F_SETFL Set file status flags to arg. Only certain flags can be set. For further information, see fcntl(5).
F_GETLK Get the first lock which blocks the lock description given by the variable of type struct flock pointed to by arg. The information 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 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. For further information, see fcntl(5). The cmd F_SETLK is used to establish read (F_RDLCK) and write (F_WRLCK) locks, as well as remove either type of lock (F_UNLCK). If a read or write lock cannot be set, the fcntl call will return immediately with an error value of −1.
F_SETLKW
This cmd is 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.
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 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 process ID field is only used with the F_GETLK cmd to return the value for a block in 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 l_len to zero (0). If such a lock also has l_start set to zero (0), the whole file will be locked. Changing or unlocking a 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 removed either 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 in a fork call.
RETURN VALUE
If successful, the value returned depends on cmd:
F_DUPFD Returns a new file descriptor.
F_GETFD Returns the value of flag (only the low-order bit is defined).
F_SETFD Returns a value other than −1.
F_GETFL Returns the value of file flags.
F_SETFL Returns a value other than −1.
F_GETLK Returns a value other that −1.
F_SETLK Returns a value other than −1.
F_SETLKW
Returns a value other than −1.
If unsuccessful, returns a −1, and the global variable errno indicates the error code.
DIAGNOSTICS
The fcntl call will fail if:
[EBADF] The specified fildes is not a valid open file descriptor.
[EMFILE] The cmd is F_DUPFD, and 20 file descriptors are currently open.
[EINFILE] The cmd is F_DUPFD, and arg is negative or greater than 20.
[EINVAL] The cmd is either F_GETLK, F_SETLK, or SETLKW, and arg or the data it points to is not valid.
[ENOSPC] The cmd is either F_SETLK or F_SETLKW, the type of lock is a read or write lock, and there are either no more file locking headers available (too many files have segments locked) or no more record locks available (too many file segments locked).
[EAGAIN] The cmd is F_SETLK. The type of lock (l_type) is either a read (F_RDLCK) or write (F_WRLCK) lock, and either 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 or write locked by another process.
[ENOLCK] The cmd is F_SETLK or F_SETLKW, the type of lock is a read or write lock, and there are no more file locks available (too many segments are locked).
[EDEADLK] The cmd is F_SETLK, the lock is blocked by some lock from another process and sleeping (waiting) for that lock to become free, this causes a deadlock situation.