# ioctl

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           ioctl — control a STREAMS device (**STREAMS**)
    


## SYNOPSIS



           #include <stropts.h>
    
           int ioctl(int _fildes_ , int _request_ , ... /* arg */);
    


## DESCRIPTION



           The _ioctl_() function shall perform a variety of control functions
           on STREAMS devices. For non-STREAMS devices, the functions
           performed by this call are unspecified. The _request_ argument and
           an optional third argument (with varying type) shall be passed to
           and interpreted by the appropriate part of the STREAM associated
           with _fildes_.
    
           The _fildes_ argument is an open file descriptor that refers to a
           device.
    
           The _request_ argument selects the control function to be performed
           and shall depend on the STREAMS device being addressed.
    
           The _arg_ argument represents additional information that is needed
           by this specific STREAMS device to perform the requested function.
           The type of _arg_ depends upon the particular control request, but
           it shall be either an integer or a pointer to a device-specific
           data structure.
    
           The _ioctl_() commands applicable to STREAMS, their arguments, and
           error conditions that apply to each individual command are
           described below.
    
           The following _ioctl_() commands, with error values indicated, are
           applicable to all STREAMS files:
    
           I_PUSH      Pushes the module whose name is pointed to by _arg_ onto
                       the top of the current STREAM, just below the STREAM
                       head. It then calls the _open_() function of the newly-
                       pushed module.
    
                       The _ioctl_() function with the I_PUSH command shall
                       fail if:
    
                       **EINVAL** Invalid module name.
    
                       **ENXIO** Open function of new module failed.
    
                       **ENXIO** Hangup received on _fildes_.
    
           I_POP       Removes the module just below the STREAM head of the
                       STREAM pointed to by _fildes_.  The _arg_ argument should
                       be 0 in an I_POP request.
    
                       The _ioctl_() function with the I_POP command shall fail
                       if:
    
                       **EINVAL** No module present in the STREAM.
    
                       **ENXIO** Hangup received on _fildes_.
    
           I_LOOK      Retrieves the name of the module just below the STREAM
                       head of the STREAM pointed to by _fildes_ , and places it
                       in a character string pointed to by _arg_.  The buffer
                       pointed to by _arg_ should be at least FMNAMESZ+1 bytes
                       long, where FMNAMESZ is defined in _< stropts.h>_.
    
                       The _ioctl_() function with the I_LOOK command shall
                       fail if:
    
                       **EINVAL** No module present in the STREAM.
    
           I_FLUSH     Flushes read and/or write queues, depending on the
                       value of _arg_.  Valid _arg_ values are:
    
                       FLUSHR      Flush all read queues.
    
                       FLUSHW      Flush all write queues.
    
                       FLUSHRW     Flush all read and all write queues.
    
                       The _ioctl_() function with the I_FLUSH command shall
                       fail if:
    
                       **EINVAL** Invalid _arg_ value.
    
                       **EAGAIN** or **ENOSR**
                              Unable to allocate buffers for flush message.
    
                       **ENXIO** Hangup received on _fildes_.
    
           I_FLUSHBAND Flushes a particular band of messages. The _arg_
                       argument points to a **bandinfo** structure. The _bi_flag_
                       member may be one of FLUSHR, FLUSHW, or FLUSHRW as
                       described above. The _bi_pri_ member determines the
                       priority band to be flushed.
    
           I_SETSIG    Requests that the STREAMS implementation send the
                       SIGPOLL signal to the calling process when a
                       particular event has occurred on the STREAM associated
                       with _fildes_.  I_SETSIG supports an asynchronous
                       processing capability in STREAMS. The value of _arg_ is
                       a bitmask that specifies the events for which the
                       process should be signaled. It is the bitwise-
                       inclusive OR of any combination of the following
                       constants:
    
                       S_RDNORM    A normal (priority band set to 0) message
                                   has arrived at the head of a STREAM head
                                   read queue. A signal shall be generated
                                   even if the message is of zero length.
    
                       S_RDBAND    A message with a non-zero priority band
                                   has arrived at the head of a STREAM head
                                   read queue. A signal shall be generated
                                   even if the message is of zero length.
    
                       S_INPUT     A message, other than a high-priority
                                   message, has arrived at the head of a
                                   STREAM head read queue. A signal shall be
                                   generated even if the message is of zero
                                   length.
    
                       S_HIPRI     A high-priority message is present on a
                                   STREAM head read queue. A signal shall be
                                   generated even if the message is of zero
                                   length.
    
                       S_OUTPUT    The write queue for normal data (priority
                                   band 0) just below the STREAM head is no
                                   longer full. This notifies the process
                                   that there is room on the queue for
                                   sending (or writing) normal data
                                   downstream.
    
                       S_WRNORM    Equivalent to S_OUTPUT.
    
                       S_WRBAND    The write queue for a non-zero priority
                                   band just below the STREAM head is no
                                   longer full. This notifies the process
                                   that there is room on the queue for
                                   sending (or writing) priority data
                                   downstream.
    
                       S_MSG       A STREAMS signal message that contains the
                                   SIGPOLL signal has reached the front of
                                   the STREAM head read queue.
    
                       S_ERROR     Notification of an error condition has
                                   reached the STREAM head.
    
                       S_HANGUP    Notification of a hangup has reached the
                                   STREAM head.
    
                       S_BANDURG   When used in conjunction with S_RDBAND,
                                   SIGURG is generated instead of SIGPOLL
                                   when a priority message reaches the front
                                   of the STREAM head read queue.
    
                       If _arg_ is 0, the calling process shall be unregistered
                       and shall not receive further SIGPOLL signals for the
                       stream associated with _fildes_.
    
                       Processes that wish to receive SIGPOLL signals shall
                       ensure that they explicitly register to receive them
                       using I_SETSIG. If several processes register to
                       receive this signal for the same event on the same
                       STREAM, each process shall be signaled when the event
                       occurs.
    
                       The _ioctl_() function with the I_SETSIG command shall
                       fail if:
    
                       **EINVAL** The value of _arg_ is invalid.
    
                       **EINVAL** The value of _arg_ is 0 and the calling process
                              is not registered to receive the SIGPOLL
                              signal.
    
                       **EAGAIN** There were insufficient resources to store the
                              signal request.
    
           I_GETSIG    Returns the events for which the calling process is
                       currently registered to be sent a SIGPOLL signal. The
                       events are returned as a bitmask in an **int** pointed to
                       by _arg_ , where the events are those specified in the
                       description of I_SETSIG above.
    
                       The _ioctl_() function with the I_GETSIG command shall
                       fail if:
    
                       **EINVAL** Process is not registered to receive the
                              SIGPOLL signal.
    
           I_FIND      Compares the names of all modules currently present in
                       the STREAM to the name pointed to by _arg_ , and returns
                       1 if the named module is present in the STREAM, or
                       returns 0 if the named module is not present.
    
                       The _ioctl_() function with the I_FIND command shall
                       fail if:
    
                       **EINVAL** _arg_ does not contain a valid module name.
    
           I_PEEK      Retrieves the information in the first message on the
                       STREAM head read queue without taking the message off
                       the queue. It is analogous to _getmsg_() except that
                       this command does not remove the message from the
                       queue.  The _arg_ argument points to a **strpeek**
                       structure.
    
                       The application shall ensure that the _maxlen_ member in
                       the **ctlbuf** and **databuf strbuf** structures is set to the
                       number of bytes of control information and/or data
                       information, respectively, to retrieve. The _flags_
                       member may be marked RS_HIPRI or 0, as described by
                       _getmsg_().  If the process sets _flags_ to RS_HIPRI, for
                       example, I_PEEK shall only look for a high-priority
                       message on the STREAM head read queue.
    
                       I_PEEK returns 1 if a message was retrieved, and
                       returns 0 if no message was found on the STREAM head
                       read queue, or if the RS_HIPRI flag was set in _flags_
                       and a high-priority message was not present on the
                       STREAM head read queue. It does not wait for a message
                       to arrive. On return, **ctlbuf** specifies information in
                       the control buffer, **databuf** specifies information in
                       the data buffer, and _flags_ contains the value RS_HIPRI
                       or 0.
    
           I_SRDOPT    Sets the read mode using the value of the argument
                       _arg_.  Read modes are described in _read_().  Valid _arg_
                       flags are:
    
                       RNORM       Byte-stream mode, the default.
    
                       RMSGD       Message-discard mode.
    
                       RMSGN       Message-nondiscard mode.
    
                       The bitwise-inclusive OR of RMSGD and RMSGN shall
                       return **[EINVAL]**.  The bitwise-inclusive OR of RNORM
                       and either RMSGD or RMSGN shall result in the other
                       flag overriding RNORM which is the default.
    
                       In addition, treatment of control messages by the
                       STREAM head may be changed by setting any of the
                       following flags in _arg_ :
    
                       RPROTNORM   Fail _read_() with **[EBADMSG]** if a message
                                   containing a control part is at the front
                                   of the STREAM head read queue.
    
                       RPROTDAT    Deliver the control part of a message as
                                   data when a process issues a _read_().
    
                       RPROTDIS    Discard the control part of a message,
                                   delivering any data portion, when a
                                   process issues a _read_().
    
                       The _ioctl_() function with the I_SRDOPT command shall
                       fail if:
    
                       **EINVAL** The _arg_ argument is not valid.
    
           I_GRDOPT    Returns the current read mode setting, as described
                       above, in an **int** pointed to by the argument _arg_.  Read
                       modes are described in _read_().
    
           I_NREAD     Counts the number of data bytes in the data part of
                       the first message on the STREAM head read queue and
                       places this value in the **int** pointed to by _arg_.  The
                       return value for the command shall be the number of
                       messages on the STREAM head read queue. For example,
                       if 0 is returned in _arg_ , but the _ioctl_() return value
                       is greater than 0, this indicates that a zero-length
                       message is next on the queue.
    
           I_FDINSERT  Creates a message from specified buffer(s), adds
                       information about another STREAM, and sends the
                       message downstream. The message contains a control
                       part and an optional data part. The data and control
                       parts to be sent are distinguished by placement in
                       separate buffers, as described below. The _arg_ argument
                       points to a **strfdinsert** structure.
    
                       The application shall ensure that the _len_ member in
                       the **ctlbuf strbuf** structure is set to the size of a
                       **t_uscalar_t** plus the number of bytes of control
                       information to be sent with the message. The _fildes_
                       member specifies the file descriptor of the other
                       STREAM, and the _offset_ member, which must be suitably
                       aligned for use as a **t_uscalar_t** , specifies the offset
                       from the start of the control buffer where I_FDINSERT
                       shall store a **t_uscalar_t** whose interpretation is
                       specific to the STREAM end. The application shall
                       ensure that the _len_ member in the **databuf strbuf**
                       structure is set to the number of bytes of data
                       information to be sent with the message, or to 0 if no
                       data part is to be sent.
    
                       The _flags_ member specifies the type of message to be
                       created. A normal message is created if _flags_ is set
                       to 0, and a high-priority message is created if _flags_
                       is set to RS_HIPRI. For non-priority messages,
                       I_FDINSERT shall block if the STREAM write queue is
                       full due to internal flow control conditions.  For
                       priority messages, I_FDINSERT does not block on this
                       condition. For non-priority messages, I_FDINSERT does
                       not block when the write queue is full and O_NONBLOCK
                       is set. Instead, it fails and sets _errno_ to **[EAGAIN]**.
    
                       I_FDINSERT also blocks, unless prevented by lack of
                       internal resources, waiting for the availability of
                       message blocks in the STREAM, regardless of priority
                       or whether O_NONBLOCK has been specified. No partial
                       message is sent.
    
                       The _ioctl_() function with the I_FDINSERT command shall
                       fail if:
    
                       **EAGAIN** A non-priority message is specified, the
                              O_NONBLOCK flag is set, and the STREAM write
                              queue is full due to internal flow control
                              conditions.
    
                       **EAGAIN** or **ENOSR**
                              Buffers cannot be allocated for the message
                              that is to be created.
    
                       **EINVAL** One of the following:
    
                                   --  The _fildes_ member of the **strfdinsert**
                                       structure is not a valid, open STREAM
                                       file descriptor.
    
                                   --  The size of a **t_uscalar_t** plus _offset_
                                       is greater than the _len_ member for the
                                       buffer specified through **ctlbuf**.
    
                                   --  The _offset_ member does not specify a
                                       properly-aligned location in the data
                                       buffer.
    
                                   --  An undefined value is stored in _flags_.
    
                       **ENXIO** Hangup received on the STREAM identified by
                              either the _fildes_ argument or the _fildes_ member
                              of the **strfdinsert** structure.
    
                       **ERANGE** The _len_ member for the buffer specified through
                              **databuf** does not fall within the range
                              specified by the maximum and minimum packet
                              sizes of the topmost STREAM module; or the _len_
                              member for the buffer specified through **databuf**
                              is larger than the maximum configured size of
                              the data part of a message; or the _len_ member
                              for the buffer specified through **ctlbuf** is
                              larger than the maximum configured size of the
                              control part of a message.
    
           I_STR       Constructs an internal STREAMS _ioctl_() message from
                       the data pointed to by _arg_ , and sends that message
                       downstream.
    
                       This mechanism is provided to send _ioctl_() requests to
                       downstream modules and drivers. It allows information
                       to be sent with _ioctl_(), and returns to the process
                       any information sent upstream by the downstream
                       recipient. I_STR shall block until the system responds
                       with either a positive or negative acknowledgement
                       message, or until the request times out after some
                       period of time. If the request times out, it shall
                       fail with _errno_ set to **[ETIME]**.
    
                       At most, one I_STR can be active on a STREAM. Further
                       I_STR calls shall block until the active I_STR
                       completes at the STREAM head. The default timeout
                       interval for these requests is 15 seconds. The
                       O_NONBLOCK flag has no effect on this call.
    
                       To send requests downstream, the application shall
                       ensure that _arg_ points to a **strioctl** structure.
    
                       The _ic_cmd_ member is the internal _ioctl_() command
                       intended for a downstream module or driver and
                       _ic_timout_ is the number of seconds (-1=infinite, 0=use
                       implementation-defined timeout interval, >0=as
                       specified) an I_STR request shall wait for
                       acknowledgement before timing out.  _ic_len_ is the
                       number of bytes in the data argument, and _ic_dp_ is a
                       pointer to the data argument. The _ic_len_ member has
                       two uses: on input, it contains the length of the data
                       argument passed in, and on return from the command, it
                       contains the number of bytes being returned to the
                       process (the buffer pointed to by _ic_dp_ should be
                       large enough to contain the maximum amount of data
                       that any module or the driver in the STREAM can
                       return).
    
                       The STREAM head shall convert the information pointed
                       to by the **strioctl** structure to an internal _ioctl_()
                       command message and send it downstream.
    
                       The _ioctl_() function with the I_STR command shall fail
                       if:
    
                       **EAGAIN** or **ENOSR**
                              Unable to allocate buffers for the _ioctl_()
                              message.
    
                       **EINVAL** The _ic_len_ member is less than 0 or larger than
                              the maximum configured size of the data part of
                              a message, or _ic_timout_ is less than -1.
    
                       **ENXIO** Hangup received on _fildes_.
    
                       **ETIME** A downstream _ioctl_() timed out before
                              acknowledgement was received.
    
                       An I_STR can also fail while waiting for an
                       acknowledgement if a message indicating an error or a
                       hangup is received at the STREAM head.  In addition,
                       an error code can be returned in the positive or
                       negative acknowledgement message, in the event the
                       _ioctl_() command sent downstream fails. For these
                       cases, I_STR shall fail with _errno_ set to the value in
                       the message.
    
           I_SWROPT    Sets the write mode using the value of the argument
                       _arg_.  Valid bit settings for _arg_ are:
    
                       SNDZERO     Send a zero-length message downstream when
                                   a _write_() of 0 bytes occurs. To not send a
                                   zero-length message when a _write_() of 0
                                   bytes occurs, the application shall ensure
                                   that this bit is not set in _arg_ (for
                                   example, _arg_ would be set to 0).
    
                       The _ioctl_() function with the I_SWROPT command shall
                       fail if:
    
                       **EINVAL** _arg_ is not the above value.
    
           I_GWROPT    Returns the current write mode setting, as described
                       above, in the **int** that is pointed to by the argument
                       _arg_.
    
           I_SENDFD    Creates a new reference to the open file description
                       associated with the file descriptor _arg_ , and writes a
                       message on the STREAMS-based pipe _fildes_ containing
                       this reference, together with the user ID and group ID
                       of the calling process.
    
                       The _ioctl_() function with the I_SENDFD command shall
                       fail if:
    
                       **EAGAIN** The sending STREAM is unable to allocate a
                              message block to contain the file pointer; or
                              the read queue of the receiving STREAM head is
                              full and cannot accept the message sent by
                              I_SENDFD.
    
                       **EBADF** The _arg_ argument is not a valid, open file
                              descriptor.
    
                       **EINVAL** The _fildes_ argument is not connected to a
                              STREAM pipe.
    
                       **ENXIO** Hangup received on _fildes_.
    
                       The _ioctl_() function with the I_SENDFD command may
                       fail if:
    
                       **EINVAL** The _arg_ argument is equal to the _fildes_
                              argument.
    
           I_RECVFD    Retrieves the reference to an open file description
                       from a message written to a STREAMS-based pipe using
                       the I_SENDFD command, and allocates a new file
                       descriptor in the calling process that refers to this
                       open file description. The _arg_ argument is a pointer
                       to a **strrecvfd** data structure as defined in
                       _< stropts.h>_.
    
                       The _fd_ member is a file descriptor. The _uid_ and _gid_
                       members are the effective user ID and effective group
                       ID, respectively, of the sending process.
    
                       If O_NONBLOCK is not set, I_RECVFD shall block until a
                       message is present at the STREAM head. If O_NONBLOCK
                       is set, I_RECVFD shall fail with _errno_ set to **[EAGAIN]**
                       if no message is present at the STREAM head.
    
                       If the message at the STREAM head is a message sent by
                       an I_SENDFD, a new file descriptor shall be allocated
                       for the open file descriptor referenced in the
                       message. The new file descriptor is placed in the _fd_
                       member of the **strrecvfd** structure pointed to by _arg_.
    
                       The _ioctl_() function with the I_RECVFD command shall
                       fail if:
    
                       **EAGAIN** A message is not present at the STREAM head
                              read queue and the O_NONBLOCK flag is set.
    
                       **EBADMSG**
                              The message at the STREAM head read queue is
                              not a message containing a passed file
                              descriptor.
    
                       **EMFILE** All file descriptors available to the process
                              are currently open.
    
                       **ENXIO** Hangup received on _fildes_.
    
           I_LIST      Allows the process to list all the module names on the
                       STREAM, up to and including the topmost driver name.
                       If _arg_ is a null pointer, the return value shall be
                       the number of modules, including the driver, that are
                       on the STREAM pointed to by _fildes_.  This lets the
                       process allocate enough space for the module names.
                       Otherwise, it should point to a **str_list** structure.
    
                       The _sl_nmods_ member indicates the number of entries
                       the process has allocated in the array. Upon return,
                       the _sl_modlist_ member of the **str_list** structure shall
                       contain the list of module names, and the number of
                       entries that have been filled into the _sl_modlist_
                       array is found in the _sl_nmods_ member (the number
                       includes the number of modules including the driver).
                       The return value from _ioctl_() shall be 0. The entries
                       are filled in starting at the top of the STREAM and
                       continuing downstream until either the end of the
                       STREAM is reached, or the number of requested modules
                       (_sl_nmods_) is satisfied.
    
                       The _ioctl_() function with the I_LIST command shall
                       fail if:
    
                       **EINVAL** The _sl_nmods_ member is less than 1.
    
                       **EAGAIN** or **ENOSR**
                              Unable to allocate buffers.
    
           I_ATMARK    Allows the process to see if the message at the head
                       of the STREAM head read queue is marked by some module
                       downstream. The _arg_ argument determines how the
                       checking is done when there may be multiple marked
                       messages on the STREAM head read queue. It may take on
                       the following values:
    
                       ANYMARK     Check if the message is marked.
    
                       LASTMARK    Check if the message is the last one
                                   marked on the queue.
    
                       The bitwise-inclusive OR of the flags ANYMARK and
                       LASTMARK is permitted.
    
                       The return value shall be 1 if the mark condition is
                       satisfied; otherwise, the value shall be 0.
    
                       The _ioctl_() function with the I_ATMARK command shall
                       fail if:
    
                       **EINVAL** Invalid _arg_ value.
    
           I_CKBAND    Checks if the message of a given priority band exists
                       on the STREAM head read queue. This shall return 1 if
                       a message of the given priority exists, 0 if no such
                       message exists, or -1 on error.  _arg_ should be of type
                       **int**.
    
                       The _ioctl_() function with the I_CKBAND command shall
                       fail if:
    
                       **EINVAL** Invalid _arg_ value.
    
           I_GETBAND   Returns the priority band of the first message on the
                       STREAM head read queue in the integer referenced by
                       _arg_.
    
                       The _ioctl_() function with the I_GETBAND command shall
                       fail if:
    
                       **ENODATA**
                              No message on the STREAM head read queue.
    
           I_CANPUT    Checks if a certain band is writable.  _arg_ is set to
                       the priority band in question. The return value shall
                       be 0 if the band is flow-controlled, 1 if the band is
                       writable, or -1 on error.
    
                       The _ioctl_() function with the I_CANPUT command shall
                       fail if:
    
                       **EINVAL** Invalid _arg_ value.
    
           I_SETCLTIME This request allows the process to set the time the
                       STREAM head shall delay when a STREAM is closing and
                       there is data on the write queues.  Before closing
                       each module or driver, if there is data on its write
                       queue, the STREAM head shall delay for the specified
                       amount of time to allow the data to drain. If, after
                       the delay, data is still present, it shall be flushed.
                       The _arg_ argument is a pointer to an integer specifying
                       the number of milliseconds to delay, rounded up to the
                       nearest valid value. If I_SETCLTIME is not performed
                       on a STREAM, an implementation-defined default timeout
                       interval is used.
    
                       The _ioctl_() function with the I_SETCLTIME command
                       shall fail if:
    
                       **EINVAL** Invalid _arg_ value.
    
           I_GETCLTIME Returns the close time delay in the integer pointed to
                       by _arg_.
    
       **Multiplexed STREAMS Configurations**
           The following commands are used for connecting and disconnecting
           multiplexed STREAMS configurations. These commands use an
           implementation-defined default timeout interval.
    
           I_LINK      Connects two STREAMs, where _fildes_ is the file
                       descriptor of the STREAM connected to the multiplexing
                       driver, and _arg_ is the file descriptor of the STREAM
                       connected to another driver. The STREAM designated by
                       _arg_ is connected below the multiplexing driver. I_LINK
                       requires the multiplexing driver to send an
                       acknowledgement message to the STREAM head regarding
                       the connection. This call shall return a multiplexer
                       ID number (an identifier used to disconnect the
                       multiplexer; see I_UNLINK) on success, and -1 on
                       failure.
    
                       The _ioctl_() function with the I_LINK command shall
                       fail if:
    
                       **ENXIO** Hangup received on _fildes_.
    
                       **ETIME** Timeout before acknowledgement message was
                              received at STREAM head.
    
                       **EAGAIN** or **ENOSR**
                              Unable to allocate STREAMS storage to perform
                              the I_LINK.
    
                       **EBADF** The _arg_ argument is not a valid, open file
                              descriptor.
    
                       **EINVAL** The _fildes_ argument does not support
                              multiplexing; or _arg_ is not a STREAM or is
                              already connected downstream from a
                              multiplexer; or the specified I_LINK operation
                              would connect the STREAM head in more than one
                              place in the multiplexed STREAM.
    
                       An I_LINK can also fail while waiting for the
                       multiplexing driver to acknowledge the request, if a
                       message indicating an error or a hangup is received at
                       the STREAM head of _fildes_.  In addition, an error code
                       can be returned in the positive or negative
                       acknowledgement message. For these cases, I_LINK fails
                       with _errno_ set to the value in the message.
    
           I_UNLINK    Disconnects the two STREAMs specified by _fildes_ and
                       _arg_.  _fildes_ is the file descriptor of the STREAM
                       connected to the multiplexing driver. The _arg_ argument
                       is the multiplexer ID number that was returned by the
                       I_LINK _ioctl_() command when a STREAM was connected
                       downstream from the multiplexing driver. If _arg_ is
                       MUXID_ALL, then all STREAMs that were connected to
                       _fildes_ shall be disconnected. As in I_LINK, this
                       command requires acknowledgement.
    
                       The _ioctl_() function with the I_UNLINK command shall
                       fail if:
    
                       **ENXIO** Hangup received on _fildes_.
    
                       **ETIME** Timeout before acknowledgement message was
                              received at STREAM head.
    
                       **EAGAIN** or **ENOSR**
                              Unable to allocate buffers for the
                              acknowledgement message.
    
                       **EINVAL** Invalid multiplexer ID number.
    
                       An I_UNLINK can also fail while waiting for the
                       multiplexing driver to acknowledge the request if a
                       message indicating an error or a hangup is received at
                       the STREAM head of _fildes_.  In addition, an error code
                       can be returned in the positive or negative
                       acknowledgement message. For these cases, I_UNLINK
                       shall fail with _errno_ set to the value in the message.
    
           I_PLINK     Creates a _persistent connection_ between two STREAMs,
                       where _fildes_ is the file descriptor of the STREAM
                       connected to the multiplexing driver, and _arg_ is the
                       file descriptor of the STREAM connected to another
                       driver. This call shall create a persistent connection
                       which can exist even if the file descriptor _fildes_
                       associated with the upper STREAM to the multiplexing
                       driver is closed.  The STREAM designated by _arg_ gets
                       connected via a persistent connection below the
                       multiplexing driver. I_PLINK requires the multiplexing
                       driver to send an acknowledgement message to the
                       STREAM head. This call shall return a multiplexer ID
                       number (an identifier that may be used to disconnect
                       the multiplexer; see I_PUNLINK) on success, and -1 on
                       failure.
    
                       The _ioctl_() function with the I_PLINK command shall
                       fail if:
    
                       **ENXIO** Hangup received on _fildes_.
    
                       **ETIME** Timeout before acknowledgement message was
                              received at STREAM head.
    
                       **EAGAIN** or **ENOSR**
                              Unable to allocate STREAMS storage to perform
                              the I_PLINK.
    
                       **EBADF** The _arg_ argument is not a valid, open file
                              descriptor.
    
                       **EINVAL** The _fildes_ argument does not support
                              multiplexing; or _arg_ is not a STREAM or is
                              already connected downstream from a
                              multiplexer; or the specified I_PLINK operation
                              would connect the STREAM head in more than one
                              place in the multiplexed STREAM.
    
                       An I_PLINK can also fail while waiting for the
                       multiplexing driver to acknowledge the request, if a
                       message indicating an error or a hangup is received at
                       the STREAM head of _fildes_.  In addition, an error code
                       can be returned in the positive or negative
                       acknowledgement message. For these cases, I_PLINK
                       shall fail with _errno_ set to the value in the message.
    
           I_PUNLINK   Disconnects the two STREAMs specified by _fildes_ and
                       _arg_ from a persistent connection. The _fildes_ argument
                       is the file descriptor of the STREAM connected to the
                       multiplexing driver. The _arg_ argument is the
                       multiplexer ID number that was returned by the I_PLINK
                       _ioctl_() command when a STREAM was connected downstream
                       from the multiplexing driver. If _arg_ is MUXID_ALL,
                       then all STREAMs which are persistent connections to
                       _fildes_ shall be disconnected. As in I_PLINK, this
                       command requires the multiplexing driver to
                       acknowledge the request.
    
                       The _ioctl_() function with the I_PUNLINK command shall
                       fail if:
    
                       **ENXIO** Hangup received on _fildes_.
    
                       **ETIME** Timeout before acknowledgement message was
                              received at STREAM head.
    
                       **EAGAIN** or **ENOSR**
                              Unable to allocate buffers for the
                              acknowledgement message.
    
                       **EINVAL** Invalid multiplexer ID number.
    
                       An I_PUNLINK can also fail while waiting for the
                       multiplexing driver to acknowledge the request if a
                       message indicating an error or a hangup is received at
                       the STREAM head of _fildes_.  In addition, an error code
                       can be returned in the positive or negative
                       acknowledgement message. For these cases, I_PUNLINK
                       shall fail with _errno_ set to the value in the message.
    


## RETURN VALUE



           Upon successful completion, _ioctl_() shall return a value other
           than -1 that depends upon the STREAMS device control function.
           Otherwise, it shall return -1 and set _errno_ to indicate the error.
    


## ERRORS



           Under the following general conditions, _ioctl_() shall fail if:
    
           **EBADF** The _fildes_ argument is not a valid open file descriptor.
    
           **EINTR** A signal was caught during the _ioctl_() operation.
    
           **EINVAL** The STREAM or multiplexer referenced by _fildes_ is linked
                  (directly or indirectly) downstream from a multiplexer.
    
           If an underlying device driver detects an error, then _ioctl_()
           shall fail if:
    
           **EINVAL** The _request_ or _arg_ argument is not valid for this device.
    
           **EIO** Some physical I/O error has occurred.
    
           **ENOTTY** The file associated with the _fildes_ argument is not a
                  STREAMS device that accepts control functions.
    
           **ENXIO** The _request_ and _arg_ arguments are valid for this device
                  driver, but the service requested cannot be performed on
                  this particular sub-device.
    
           **ENODEV** The _fildes_ argument refers to a valid STREAMS device, but
                  the corresponding device driver does not support the
                  _ioctl_() function.
    
           If a STREAM is connected downstream from a multiplexer, any
           _ioctl_() command except I_UNLINK and I_PUNLINK shall set _errno_ to
           **[EINVAL]**.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           The implementation-defined timeout interval for STREAMS has
           historically been 15 seconds.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           The _ioctl_() function may be removed in a future version.
    


* * *