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() system call, or socket descriptors returned by the socket() system call.

Possible requests are:

F_DUPFD
Return a new descriptor with the same characteristics as the old, with the exception that the new descriptor is set to remain open across execve() 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(,), 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.

See the description of the request argument for more information on functions. 

File and region locking are supported over the Network File System (NFS) services if you have enable the NFS locking service. 

ARGUMENTS

The following arguments can be used with fcntl:

fdDescriptor 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() system call, or a socket descriptor returned by a socket() system call.

requestDefines what you want done. The possible values are defined in <fcntl.h>.  See the following section for more information. 

argVaries according to the request argument.  See the following section for more information. 

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 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_DUPFDWhen request is set for F_DUPFD: The fcntl call returns a new descriptor. The new file descriptor returned has the following characteristics:

•The file descriptor returned is the lowest numbered available descriptor that is greater than or equal to the argument arg. 

•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. 

•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.) 

•The new descriptor has the same access mode as the old descriptor (read, write or read/write). 

•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.) 

•The close-on-exec flag associated with the new file descriptor is set to remain open across execve() 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(.). If cleared, the file descriptor will remain open in the new image loaded by the call to execve(.). If set, the file descriptor will be closed in the new image loaded by the call to execve(.).

F_GETFDWhen 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(.). If the low-order bit of the value returned by fcntl is 1, the file descriptor is closed across calls to execve(.).

F_SETFDWhen 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_GETFLWhen 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:

FNDELAYNon-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].

FSYNCRONSynchronous write flag.  Forces subsequent file writes to be done synchronously.  For further information, see write(.).

FAPPENDForce each write to append at the end of file.  This corresponds to the action taken with the O_APPEND flag of open(.).

FASYNCEnable 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. 

FNBLOCKPOSIX mode, non-blocking I/O flag.  See FNDELAY request for description of operation. 

F_SETFLWhen request is set to F_SETFL: The fcntl 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 sigvec(,), SIGIO is a signal indicating that I/O is possible on a descriptor. SIGURG indicates an urgent condition present on a socket.

F_GETOWNWhen 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_SETOWNWhen 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. Refer to the F_SETFL section for more information. 

F_GETLK, F_SETLK, and F_SETLKW − Locking File Regions

With these requests, your process can:

•Test a file for a region that may have been read-locked or write-locked by another process

•Set or clear a file region read or write lock. 

•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 may 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 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 other 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 write 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() system call.

F_GETLKWhen request is set to F_GETLK: The fcntl 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 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 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.  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 created; 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", above, 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_SETLKWhen 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, fcntl will return immediately with an error value of −1.

F_SETLKWWhen 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.

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 nonblocking 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. 

[EFAULT] The arg is pointing to an address outside the process’s allocated space. 

[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 than the maximum allowable number.  For further information, see getdtablesize(.).

[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. 

[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.  Or, the file is remotely mounted and the NFS locking service is not enabled. 

[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_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. 

SEE ALSO

close(2), execve(2), getdtablesize(2), open(2), sigvec(2), lockd(8c)

System Calls