fcntl(2)
NAME
fcntl − file control
SYNTAX
#include <fcntl.h>
res = fcntl(fd, request, arg)
int res;
int fd, request, arg
DESCRIPTION
The fcntl system call provides for control over descriptors. The descriptors can be either file descriptors returned by the open(2) system call, or socket descriptors returned by the socket(2) system call.
Possible requests are:
F_DUPFD
Return a new descriptor with the same characteristics as the old, except that the new descriptor is set to remain open across execve(2) system calls.
F_GETFD and F_SETFD
Get or set the close-on-exec flag associated with the descriptor.
F_GETFL and F_SETFL
Get or set descriptor status flags.
F_GETOWN and F_SETOWN
Get or set some interrupt signals (SIGIO or SIGURG as described in sigvec(2) for the process ID or process group associated with the descriptor.
F_GETLK, F_SETLK, and F_SETLKW
Lock or unlock regions of a file.
F_SETSYN and F_CLRSYN
Set or clear synchronous write flag.
The discussion of the request argument gives more detail on the functions you can select.
ARGUMENTS
The fd argurment is the descriptor to be operated on. Depending on the function selected by the request argument, the fd argument can be a file descriptor returned by an open(2) system call, or a socket descriptor returned by a socket(2) system call.
The request argument defines what you want done. The possible values, which are defined in <fcntl.h>, are organized in following subsections according to general function.
The arg argument meaning varies according to the request argument, as discussed in following subsections.
F_DUPFD − Return New Descriptor
The shell provides one example of when a new descriptor is useful. Suppose the shell receives a command such as:
cat > myfile
The shell needs to redirect the output of the cat command from the file descriptor 1 (standard output) to a new file named myfile. The shell issues the fcntl call, using the old file descriptor of 1, to obtain a new file descriptor for the file myfile.
F_DUPFD. When request is set fo F_DUPFD:
The fcntl call returns a new descriptor. The new file descriptor returned has the following characteristics:
1.The file descriptor returned is the lowest numbered available descriptor that is greater than or equal to the argument arg.
2.The descriptor has the same object references as the original descriptor. That is, if the original file descriptor referred to a file, the new file descriptor refers to a file. If the original descriptor referred to a socket, the new file descriptor refers to a socket.
3.The new descriptor shares the same file pointer if the object was a file. (A file pointer points to an inode, which in turn points to a file. Thus, the new descriptor refers to the same file as the old descriptor.)
4.The new descriptor has the same access mode as the old descriptor (read, write or read/write).
5.The new descriptor shares the same file status flags as the old file descriptor. (See the discussion of F_GETFL and F_SETFL, below, for a description of file status flags.
6.The close-on-exec flag associated with the new file descriptor is set to remain open across execve(2) system calls. (See the discussion of F_GETFD and F_SETFD, below, for a description of the close-on-exec flag.
F_GETFD and F_SETFD − Close-on-exec Flag
Each file descriptor points to an entry in an array of file pointers which, among other things, define certain characteristics for the file. One such characteristic is the close-on-exec flag. This flag defines whether or not a file remains open across calls to execve(2). If cleared, the file descriptor will remain open in the new image loaded by the call to execve(2). If set, the file descriptor will be closed in the new image loaded by the call to execve(2).
F_GETFD. When request is set to F_GETFD:
The fcntl call returns the close-on-exec flag associated with the file descriptor fd. If the low-order bit of the value returned by fcntl is 0, the file will remain open across calls to execve(2). If the low-order bit of the value returned by fcntl is 1, the file descriptor is closed across calls to execve(2).
F_SETFD. When request is set to F_SETFD:
The fcntl call sets the close-on-exec flag associated with fd to the low-order bit of arg (0 or 1 as above).
F_GETFL and F_SETFL − Descriptor Status Flags
Each file descriptor points to an entry in an array of file pointers which, among other things, define the file’s current status. One such item of status, for example, is whether or not input/output operations to a file are currently blocked.
You might want to program your process to allow blocking, for example, if a user was running your process in the background while doing other work in the foreground, and did not want output from the background jobs to be displayed on his screen.
These and other status indicators are discussed below. Note that some status indicators do not apply to all types of descriptors. The FAPPEND status, for example, is meaningless for sockets.
F_GETFL. When request is set to F_GETFL:
The fcntl call returns the file’s descriptor status flags. The following names have been defined in <fcntl.h> for these status flags:
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. This corresponds to the action taken with the O_APPEND flag of open(2).
FASYNC
Enable the SIGIO signal to be sent to the process group when I/O is possible. For example, send SIGIO when data is available to be read.
F_SETFL. When request is set to F_SETFL:
The fcntl call sets descriptor status flags (see F_GETFL, above).
F_GETOWN and F_SETOWN − Get or Set Owner
With these requests, your process can recognize the software interrupts SIGIO or SIGURG. As described in sigvec(2), SIGIO is a signal indicating that I/O is possible on a descriptor. SIGURG indicates an urgent condition present on a socket.
F_GETOWN. When request is set to F_GETOWN:
The fcntl call returns the process ID or process group currently receiving SIGIO and SIGURG signals. Process groups are returned as negative values.
F_SETOWN. When request is set to F_SETOWN:
The fcntl call sets the process or process group to receive SIGIO and SIGURG signals; process groups are specified by supplying arg as negative. Otherwise, arg is interpreted as a process ID.
F_GETLK, F_SETLK, and F_SETLKW − Locking File Regions
With these requests, your process can:
1.Test a file for a region that may have been read-locked or write-locked by another process
2.Set or clear a file region read or write lock.
3.Set a file region read or write lock, sleeping if necessary until locks previously set by other processes are unlocked.
A read lock prevents any process from write locking the protected area. More than one read lock may exist for a given region 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 region. Only one write lock may exist for a given region of a file at a given time. The file descriptor on which a write lock is being placed must have been opened with read access.
Locks may start and extend beyond the current end of a file, but may not be negative relative to the beginning of the file.
Changing or unlocking a region from the middle of a larger locked region leaves two smaller regions with the old setting at either end. Locking a region that is already locked by the calling process causes the old lock 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 descriptor terminates. Locks are not inherited by a child process in a fork(2) system call.
F_GETLK. When request is set to F_GETLK:
The fcntl call tests a file for a read or write locked region. In the call, you pass a lock description in a variable of type struct flock pointed to by arg.
If the region defined in the flock structure is already locked, a description of the existing lock is returned 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.
The flock structure is defined below:
struct flock {
short l_type;
short l_whence;
long l_start;
long l_len;
int l_pid;
};
Data Passed in flock
In the data you pass in flock, the l_type value defines the lock type to be tested for: F_RDLCK for a read lock and F_WRLCK for a write lock.
The l_whence value defines point from which the starting byte of the region is to be measured. If l_whence is 0, the value in l_start is taken as the starting byte of the region. If l_whence is 1, the current file offset plus the value of l_start is taken as the starting point. If l_whence is 2, the file size plus the value of l_start is taken as the starting point.
The l_len value is the length of the region to be tested, in bytes. If l_len is zero, the to be tested for extends to the end of file. If l_len is zero and l_start is zero, the whole file is to be tested.
The l_pid value has no significance in the data passed.
Data Returned in flock
The l_type value can be F_RDLCK is the region passed is under a read lock. F_WRLCK means that the region passed is under a write lock. F_UNLCK means that the region is not currently locked by any process.
The l_whence, l_start, and l_len values have similar meanings as discussed under "Data Passed", above, except that they define the region currently under read or write lock.
The l_pid value is the process ID of the process that currently has the region locked, if any.
F_SETLK When request is set to F_SETLK:
You set or clear a file region lock according to the variable of f_type in the struct flock pointed to by arg. (The flock structure is shown under the description of F_GETLK, preceding.)
The f_type value 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, fcntl will return immediately with an error value of −1.
F_SETLKW When request is set to F_SETLKW:
The fcntl call takes the same action as for 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_SETSYN and F_CLRSYN − Synchronous Write Flag
F_SETSYN forces subsequent file writes to be done synchronously. For further information, see write(2). That is, the system call will not return until the write is complete.
F_CLRSYN resets file writes to be asynchronous, the default. In this case, the write(2) system call returns after the data is written to the buffer cache.
RESTRICTIONS
The asynchronous I/O facilities of FNDELAY and FASYNC are available only for terminal operations. No SIGIO signal is sent upon draining of output sufficiently for non-blocking writes to occur.
RETURN VALUE
Upon successful completion, the value returned depends upon the request argument as follows:
F_DUPFDA new file descriptor.
F_GETFDValue of flag (only the low-order bit is defined).
F_GETFLValue of flags.
F_GETOWN Value of file descriptor owner.
otherValue other than −1.
Otherwise, a value of −1 is returned and errno is set to indicate the error.
DIAGNOSTICS
The fcntl fails if one or more of the following are true:
[EBADF] The fildes argument is not a valid open file descriptor.
[EMFILE] The request argument is F_DUPFD and the maximum allowed number of file descriptors are currently open.
[EINVAL] The request argument is F_DUPFD and arg is negative or greater the maximum allowable number. For further information, see getdtablesize(2).
[EINVAL] The request argument is F_SETSYN, to change the write mode of a file to synchronous, and this operation was not valid for the file descriptor. For example, the file was opened for read-only operations.
[EINVAL] The request argument is F_GETLK, F_SETLK, or SETLKW and arg or the data it points to is not valid.
[EACCESS] The request argument is F_SETLK, the type of lock ( l_type ) is a read (F_RDLCK) or write (F_WRLCK) lock, and the region of the file to be locked is already write locked by another process. Or, the type is a write lock and the region of the file to be locked is already read or write locked by another process.
[EMFILE] The request argument is F_SETLK or F_SETLKW, the type of lock is a read or write lock, and there are no more file locking headers available (too many files have segments locked).
[ENOSPC] The request argument is F_SETLK or F_SETLKW, the type of lock is a read or write lock, and there are no more file locking headers available (too many files have segments locked). Or, there are no more record locks available (too many file segments locked).
[EDEADLK] The request argument is F_SETLK, and the lock is blocked by some lock from another process that is sleeping (waiting) for that lock to become free. This causes a deadlock situation.
[EOPNOTSUPP]
Attempting an operation that is not valid for the file descriptor. This can occur if the file descriptor argument, fd, points to a socket address, and the request argument is only valid for files.