NAME

fcntl − file control

SYNOPSIS

#include <fcntl.h>

res = fcntl(fd, cmd, arg)
int res;
int fd, cmd, arg;

DESCRIPTION

Fcntl provides for control over descriptors.  The argument fd is a descriptor to be operated on by cmd as follows:

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 execv(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 will remain open across exec, otherwise the file will be closed upon execution of exec. 

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, as described below. 

F_SETFL Set descriptor status flags. 

F_GETOWN Get the process group currently receiving SIGIO and SIGURG signals. 

F_SETOWN Set the process group to receive SIGIO and SIGURG signals; if arg is negative, the absolute value of arg is used as the process group; if arg is positive, it is interpreted as a process ID, and the process group of that process is used. 

F_GETLK Get the first lock which blocks the lock description given by the variable of type struct flock pointed to by arg (see below).  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 (see below).  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, fcntl returns 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. 

The flags for the F_GETFL and F_SETFL commands are as follows:

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. 

FSYNC Make all write I/O operations synchronous for regular and block special files; corresponds to the O_SYNC flag of open(2).

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 (defined in /usr/include/fcntl.h) describes the type, starting offset, size, and process ID of the segment of the file to be affected. The starting offset may be 0, 1, or 2, to indicate that the relative offset will be measured from the start of the file, the current position, or the end of the file, respectively. The process ID field is only used with the F_GETLK cmd to return the value for a blocking lock. 

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 the size to zero.  If such a lock also has the starting offset set to zero, 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 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.

RETURN VALUE

Upon successful completion, the value returned depends on cmd 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. 

ERRORS

Fcntl will fail if one or more of the following are true:

[EBADF] Fildes is not a valid open file descriptor. 

[EMFILE] Cmd is F_DUPFD and the maximum allowed number of file descriptors are currently open. 

[EINVAL] Cmd is F_DUPFD and arg is negative or greater the maximum allowable number (see getdtablesize(2)).

[EINVAL] Cmd is F_GETLK, F_SETLK, or F_SETLKW, and arg or the data it points to is not valid. 

[EACCES] Cmd is F_SETLK, the type of lock is a read (F_RDLCK) or write (F_WRLCK) lock, and the segment of the file to be locked is already write locked by another process, or the type is a write lock and the segment of the file to be locked is already read or write locked by another process. 

[ENOSPC] 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).  (See NOTES later about configuring the number of system-wide file locks.) 

[EDEADLK] Cmd is F_SETLKW, the lock is blocked by some lock from another process, and putting the calling process to sleep, waiting for that lock to become free, would cause a deadlock. 

SEE ALSO

close(2), execve(2), getdtablesize(2), open(2), sigvec(2)

BUGS

The asynchronous I/O facilities of FNDELAY and FASYNC are currently available only for tty operations.  No SIGIO signal is sent upon draining of output sufficiently for non-blocking writes to occur. 

NOTES

Binary configuration of the number of record locks is provided via two defines in /sys/conf/param.c: NFILCK and NFILNO. NFILNO is the (systemwide) maximum number of files that can have record locks asserted on them at one time. NFILCK is the (systemwide) maximum number of record locks that will be asserted at one time.

4BSD/DYNIX