ioctl(2)                                                              ioctl(2)


NAME
     ioctl - control device

SYNOPSIS
     #include <unistd.h>
     #include <sys/ioctl.h>   /* _SGIAPI FIO* functions */
     #include <stropts.h>     /* STREAMS functions */

     int ioctl (int fildes, int request, ...);

DESCRIPTION
     ioctl performs a variety of control functions on devices and STREAMS.
     For non-STREAMS files, the functions performed by this call are device-
     specific control functions.  request and an optional third argument with
     varying type are passed to the file designated by fildes and are
     interpreted by the device driver.

     For STREAMS files, specific functions are performed by the ioctl call as
     described in streamio(7).  Argument types and other request-specific
     information found in streamio(7) take precedence over information found
     in this manual page.

     fildes is an open file descriptor that refers to a device.  request
     selects the control function to be performed and depends on the device
     being addressed.  Many devices do not require that the device be opened
     in a writable mode in order to successfully perform ioctls that change
     the device parameters, or even the contents of the media for devices with
     permanent storage.  arg represents a third argument that has additional
     information that is needed by this specific device to perform the
     requested function.  The data type of arg depends upon the particular
     control request, but it is generally either an int or a pointer to a
     device-specific data structure.

     In addition to device-specific and STREAMS functions, generic functions
     are provided by more than one device driver, for example, the general
     terminal interface [see termio(7)].

     The following operations are generally available on all descriptors [see
     streamio(7)]:

     FIONBIO        Enables or disables non-blocking I/O on fildes.  arg is a
                    pointer to an int whose value should be 1 to enable non-
                    blocking I/O or 0 to disable non-blocking I/O.  This
                    operation is not currently supported on old-style (non-
                    STREAMS) pipes.

     FIONREAD       Returns the number of bytes of data currently available to
                    be read on fildes.  arg is a pointer to a size_t into
                    which the byte-count will be stored unless the ioctl is
                    called on a socket.  For sockets, the value returned is an
                    int and arg is a pointer to an int.


     ioctl fails for any type of file if one or more of the following are
     true:

     EACCES         The type of access requested on the file designated by
                    fildes is denied.

     EBADF          fildes is not a valid open file descriptor.

     ENOTTY         fildes is not associated with a device driver that accepts
                    control functions.

     EINTR          A signal was caught during the ioctl system call.

     ioctl also fails if the device driver detects an error.  In this case,
     the error is passed through ioctl without change to the caller.  A
     particular driver might not have all of the following error cases.  Under
     the following conditions, requests to device drivers may fail and set
     errno to:

     EFAULT         request requires a data transfer to or from a buffer
                    pointed to by arg, but some part of the buffer is outside
                    the process's allocated space.

     EINVAL         request or arg is not valid for this device.

     EIO            Some physical I/O error has occurred.

     ENXIO          The request and arg are valid for this device driver, but
                    the service requested can not be performed on this
                    particular subdevice.

     ENOLINK        fildes is on a remote machine and the link to that machine
                    is no longer active.

     ETIMEDOUT      fildes is on a remote machine which is not available [see
                    intro(2)].

     STREAMS errors are described in streamio(7).

SEE ALSO
     streamio(7), termio(7)

DIAGNOSTICS
     Upon successful completion, the value returned depends upon the device
     control function, but must be a non-negative integer. Otherwise, a value
     of -1 is returned and errno is set to indicate the error.


                                                                        Page 2