FCNTL(2)

NAME
fcntl - file control

SYNOPSIS
#include <sys/fcntl.h>
int
fcntl(int fd, int cmd, int 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 offset 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 of the returned value is 0, the file will remain open across exec(), otherwise the file will be closed upon execution of exec() (arg is ignored).

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 (arg is ignored).

F_SETFL
    Set descriptor status flags to arg.

F_GETOWN
    Get the process ID or process group currently receiving SIGIO and SIGURG signals; process groups are returned as negative values (arg is ignored).

F_SETOWN
    Set 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.

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

O_NDELAY
    Non-blocking I/O; if no data is available to a read call, or if a write operation would block, the read or write call returns -1 with the error EWOULDBLOCK.

O_APPEND
    Force each write to append at the end of file; corresponds to the O_APPEND flag of open(2).

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

RETURN VALUES
Upon successful completion, the value returned depends on cmd as follows:

F_DUPFD
    A new file descriptor.

F_GETFD
    Value of flag (only the low-order bit is defined).

F_GETFL
    Value of flags.

F_GETOWN
    Value of file descriptor owner.

other
    Value other than -1.

Otherwise, a value of -1 is returned and errno is set to indicate the error.

ERRORS
Fcntl() will fail if:

[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 than the maximum allowable number (see getdtablesize(2)).

[ESRCH]
    Cmd is F_SETOWN and the process ID given as argument is not in use.

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 and socket operations.

HISTORY
The fcntl function call appeared in 4.2BSD.