fcntl(2) System Calls Manual fcntl(2)
Name
fcntl - file control
Syntax
#include <fcntl.h>
res = fcntl (fd, request, arg)
int res;
int fd, request, arg
Arguments
The following arguments can be used with
fd Descriptor to be operated on. Depending on the function selected by the request argument, the fd argument can be a file descrip-
tor returned by an system call, or a socket descriptor returned by a system call.
request Defines what you want done. The possible values are defined in See the Description section for more information.
arg Varies according to the request argument. See the Description section for more information.
Description
The system call provides for control over descriptors. The descriptors can be either file descriptors returned by the system call or
socket descriptors returned by the system call.
Possible request arguments are the following:
F_DUPFD - Return New Descriptor
The shell provides an 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 command from the file descriptor 1 (standard output) to a new file named The shell issues the
call, using the old file descriptor of 1, to obtain a new file descriptor for the file
F_DUPFD When request is set for F_DUPFD:
The call returns a new descriptor. The new file descriptor returned has the following characteristics:
o The file descriptor returned is the lowest numbered available descriptor that is greater than or equal to the argument arg.
o 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.
o 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.)
o The new descriptor has the same access mode as the old descriptor (read, write, or read/write).
o The new descriptor shares the same file status flags as the old file descriptor. (See the discussion of F_GETFL and
F_SETFL for a description of file status flags.)
o The close-on-exec flag associated with the new file descriptor is set to remain open across system calls. (See the discus-
sion of F_GETFD and F_SETFD 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 that, 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 If cleared, the
file descriptor remains open in the new image loaded by the call to If set, the file descriptor is closed in the new image loaded by the
call to
F_GETFD When request is set to F_GETFD:
The call returns the close-on-exec flag associated with the file descriptor fd. If the low-order bit of the value returned by
is 0, the file remains open across calls to If the low-order bit of the value returned by is 1, the file descriptor is closed
across calls to
F_SETFD When request is set to F_SETFD:
The call sets the close-on-exec flag associated with fd to the low-order bit of arg (0 or 1).
F_GETFL and F_SETFL - Descriptor Status Flags
Each file descriptor points to an entry in an array of file pointers that, 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 so that a user who runs your process in the background, while doing other work in
the foreground, need not see output from the background job displayed on the screen.
These and other status indicators are discussed in the list that follows. Some status indicators do not apply to all types of descriptors.
The O_APPEND status, for example, is meaningless for sockets.
F_GETFL When request is set to F_GETFL:
The call returns the file's descriptor status flags. The following names have been defined in for these status flags:
O_NDELAY Nonblocking I/O. If no data is available to a call, or if a write operation would block, the call returns -1
with the error [EWOULDBLOCK]. The flag FNDELAY is an obsolete synonym for O_NDELAY.
O_FSYNC (O_SYNC) Synchronous write flag. Forces subsequent file writes to be done synchronously. For further informa-
tion, see The flag OFSYNCRON is an obsolete synonym for FSYNCRON.
O_APPEND Force each write to append at the end of file. This corresponds to the action taken with the O_APPEND flag of
The flag FAPPEND is an obsolete synonym for O_APPEND.
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.
O_NONBLOCK POSIX environment, nonblocking I/O flag. See O_NDELAY request for description of operation. The flag FNBLOCK is
an obsolete synonym for O_NONBLOCK.
F_SETFL When request is set to F_SETFL:
The call sets descriptor status flags specified in arg (see F_GETFL). Refer to the F_SETOWN section for more information.
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 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 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 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. See also the F_SETFL request, which sets descriptor status
flags, and the description of the FASYNC flag in the F_GETFL section.
F_GETLK, F_SETLK, and F_SETLKW - Locking File Regions
With these requests, your process can:
o Test a file for a region that might have been read-locked or write-locked by another process.
o Set or clear a file region read or write lock.
o Set a file region read or write lock, sleeping, if necessary, until locks previously set by other processes are unlocked.
When a read lock has been set on a segment of a file, other processes can also set read locks on that file segment or portions thereof.
A read lock prevents any other process from write locking the protected area. More than one read lock can 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 other process from read locking or write locking the protected region. Only one write lock can 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 write access.
Locks can start and extend beyond the current end of a file, but cannot 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 system call.
F_GETLK When request is set to F_GETLK:
The call gets the lock information 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 by a process other than the caller, a description of the exist-
ing 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 is set to F_UNLCK.
The flock structure is defined as follows:
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 the 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 length to be tested extends to the
end of file. If l_len is zero and l_start is zero, the whole file is to be tested. If l_len is negative, the area affected
starts at l_start + l_len and ends at l_start - 1.
The l_pid value has no significance in the data passed.
Data Returned in flock:
The l_type value can be F_RDLCK if 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 that would prevent this lock from being cre-
ated; for example, the region might be locked by the caller.
The l_whence, l_start, and l_len values have similar meanings as discussed under Data Passed, except that they define the
region currently under read or write lock.
The l_pid value is only used with F_GETLK to return the value for a blocking lock. An example of a blocking lock is a write
lock currently set by a process other than the calling process.
F_SETLK When request is set to F_SETLK:
You set or clear a file region lock according to the variable of l_type in the struct flock pointed to by arg. (The flock
structure is shown under the description of F_GETLK, preceding.)
The l_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, will return immediately with an error value of -1.
F_SETLKW When request is set to F_SETLKW:
The call takes the same action as for F_SETLK, except that if a read or write lock is blocked by other locks, the process
sleeps until the segment is free to be locked.
Files and region locking are supported over the Network File System (NFS) services if you have enabled the NFS locking service.
Return Values
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_GETOWNValue 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 fails if under the following conditions:
[EBADF] The fildes argument is not a valid open file descriptor.
[EBADF] The environment defined is POSIX, the request argument is F_SETLK or F_SETLKW, the type of lock, l_type, is a shared lock
(F_RDLCK), and fildes is not a valid file descriptor open for reading, or the type of lock, l_type, is an exclusive lock
(F_WRLCK), and fildes is not a valid file descriptor open for writing.
[EFAULT] The arg is pointing to an address outside the process's allocated space.
[EINVAL] The request argument is F_DUPFD, and arg is negative or greater than the maximum allowable number. For further information,
see
[EINVAL] The request argument is F_SETSYN, to change the write mode of a file to synchronous, and this operation is 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 the data arg points to is not valid.
[EINVAL] The request argument is invalid.
[EINVAL] The fildes argument refers to a file that does not support locking.
[EACCES] 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. Or, the file is remotely mounted and the NFS locking ser-
vice is not enabled.
[EMFILE] The request argument is F_DUPFD, and the maximum allowed number of file descriptors is currently open, or no file descrip-
tors greater than or equal to arg are available.
[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 seg-
ments locked).
[EDEADLK] The request argument is F_SETLKW, and the lock is blocked by some lock from another process that is sleeping (waiting) for
that lock to become free. This detection avoids 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.
[EINTR] The request argument is F_SETLKW and the function was interrupted by a signal.
Environment
The description differs from the POSIX and XPG3 definitions in that ENOLCK is not a possible error condition.
See Also
close(2), execve(2), getdtablesize(2), open(2), sigvec(2), lockd(8c)
fcntl(2)