FCNTL(2)                             BSD                              FCNTL(2)



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 (that is, 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.

     The flags for the F_GETFL and F_SETFL flags 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, for example, upon availability of data to be
                read.

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

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

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

NOTES
     Presently, Domain/OS BSD does not implement the following cmds:

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

     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 following error is not used:

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

BUGS
     The asynchronous I/O facilities of FNDELAY and FASYNC are currently
     available only for tty and socket operations.