IOCTL(3)                   POSIX Programmer's Manual                  IOCTL(3)



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

NNAAMMEE
       ioctl -- control a STREAMS device (SSTTRREEAAMMSS)

SSYYNNOOPPSSIISS
       #include <stropts.h>

       int ioctl(int _f_i_l_d_e_s, int _r_e_q_u_e_s_t, ... /* arg */);

DDEESSCCRRIIPPTTIIOONN
       The _i_o_c_t_l() function shall perform a variety of control functions on
       STREAMS devices. For non-STREAMS devices, the functions performed by
       this call are unspecified. The _r_e_q_u_e_s_t argument and an optional third
       argument (with varying type) shall be passed to and interpreted by the
       appropriate part of the STREAM associated with _f_i_l_d_e_s.

       The _f_i_l_d_e_s argument is an open file descriptor that refers to a device.

       The _r_e_q_u_e_s_t argument selects the control function to be performed and
       shall depend on the STREAMS device being addressed.

       The _a_r_g argument represents additional information that is needed by
       this specific STREAMS device to perform the requested function. The
       type of _a_r_g depends upon the particular control request, but it shall
       be either an integer or a pointer to a device-specific data structure.

       The _i_o_c_t_l() commands applicable to STREAMS, their arguments, and error
       conditions that apply to each individual command are described below.

       The following _i_o_c_t_l() commands, with error values indicated, are
       applicable to all STREAMS files:

       I_PUSH      Pushes the module whose name is pointed to by _a_r_g onto the
                   top of the current STREAM, just below the STREAM head. It
                   then calls the _o_p_e_n() function of the newly-pushed module.

                   The _i_o_c_t_l() function with the I_PUSH command shall fail if:

                   EEIINNVVAALL Invalid module name.

                   EENNXXIIOO  Open function of new module failed.

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

       I_POP       Removes the module just below the STREAM head of the STREAM
                   pointed to by _f_i_l_d_e_s.  The _a_r_g argument should be 0 in an
                   I_POP request.

                   The _i_o_c_t_l() function with the I_POP command shall fail if:

                   EEIINNVVAALL No module present in the STREAM.

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

       I_LOOK      Retrieves the name of the module just below the STREAM head
                   of the STREAM pointed to by _f_i_l_d_e_s, and places it in a
                   character string pointed to by _a_r_g.  The buffer pointed to
                   by _a_r_g should be at least FMNAMESZ+1 bytes long, where
                   FMNAMESZ is defined in _<_s_t_r_o_p_t_s_._h_>.

                   The _i_o_c_t_l() function with the I_LOOK command shall fail if:

                   EEIINNVVAALL No module present in the STREAM.

       I_FLUSH     Flushes read and/or write queues, depending on the value of
                   _a_r_g.  Valid _a_r_g values are:

                   FLUSHR      Flush all read queues.

                   FLUSHW      Flush all write queues.

                   FLUSHRW     Flush all read and all write queues.

                   The _i_o_c_t_l() function with the I_FLUSH command shall fail
                   if:

                   EEIINNVVAALL Invalid _a_r_g value.

                   EEAAGGAAIINN or EENNOOSSRR
                          Unable to allocate buffers for flush message.

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

       I_FLUSHBAND Flushes a particular band of messages. The _a_r_g argument
                   points to a bbaannddiinnffoo structure. The _b_i___f_l_a_g member may be
                   one of FLUSHR, FLUSHW, or FLUSHRW as described above. The
                   _b_i___p_r_i 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 _f_i_l_d_e_s.  I_SETSIG
                   supports an asynchronous processing capability in STREAMS.
                   The value of _a_r_g 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 _a_r_g is 0, the calling process shall be unregistered and
                   shall not receive further SIGPOLL signals for the stream
                   associated with _f_i_l_d_e_s.

                   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 _i_o_c_t_l() function with the I_SETSIG command shall fail
                   if:

                   EEIINNVVAALL The value of _a_r_g is invalid.

                   EEIINNVVAALL The value of _a_r_g is 0 and the calling process is not
                          registered to receive the SIGPOLL signal.

                   EEAAGGAAIINN 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 iinntt pointed to by
                   _a_r_g, where the events are those specified in the
                   description of I_SETSIG above.

                   The _i_o_c_t_l() function with the I_GETSIG command shall fail
                   if:

                   EEIINNVVAALL 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 _a_r_g, and returns 1 if the
                   named module is present in the STREAM, or returns 0 if the
                   named module is not present.

                   The _i_o_c_t_l() function with the I_FIND command shall fail if:

                   EEIINNVVAALL _a_r_g 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 _g_e_t_m_s_g() except that this command
                   does not remove the message from the queue.  The _a_r_g
                   argument points to a ssttrrppeeeekk structure.

                   The application shall ensure that the _m_a_x_l_e_n member in the
                   ccttllbbuuff and ddaattaabbuuff ssttrrbbuuff structures is set to the number
                   of bytes of control information and/or data information,
                   respectively, to retrieve. The _f_l_a_g_s member may be marked
                   RS_HIPRI or 0, as described by _g_e_t_m_s_g().  If the process
                   sets _f_l_a_g_s 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 _f_l_a_g_s 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, ccttllbbuuff
                   specifies information in the control buffer, ddaattaabbuuff
                   specifies information in the data buffer, and _f_l_a_g_s
                   contains the value RS_HIPRI or 0.

       I_SRDOPT    Sets the read mode using the value of the argument _a_r_g.
                   Read modes are described in _r_e_a_d().  Valid _a_r_g 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
                   [[EEIINNVVAALL]].  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 _a_r_g:

                   RPROTNORM   Fail _r_e_a_d() with [[EEBBAADDMMSSGG]] 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 _r_e_a_d().

                   RPROTDIS    Discard the control part of a message,
                               delivering any data portion, when a process
                               issues a _r_e_a_d().

                   The _i_o_c_t_l() function with the I_SRDOPT command shall fail
                   if:

                   EEIINNVVAALL The _a_r_g argument is not valid.

       I_GRDOPT    Returns the current read mode setting, as described above,
                   in an iinntt pointed to by the argument _a_r_g.  Read modes are
                   described in _r_e_a_d().

       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 iinntt pointed to by _a_r_g.  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 _a_r_g, but
                   the _i_o_c_t_l() 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 _a_r_g argument points to a ssttrrffddiinnsseerrtt
                   structure.

                   The application shall ensure that the _l_e_n member in the
                   ccttllbbuuff ssttrrbbuuff structure is set to the size of a tt__uussccaallaarr__tt
                   plus the number of bytes of control information to be sent
                   with the message. The _f_i_l_d_e_s member specifies the file
                   descriptor of the other STREAM, and the _o_f_f_s_e_t member,
                   which must be suitably aligned for use as a tt__uussccaallaarr__tt,
                   specifies the offset from the start of the control buffer
                   where I_FDINSERT shall store a tt__uussccaallaarr__tt whose
                   interpretation is specific to the STREAM end. The
                   application shall ensure that the _l_e_n member in the ddaattaabbuuff
                   ssttrrbbuuff 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 _f_l_a_g_s member specifies the type of message to be
                   created. A normal message is created if _f_l_a_g_s is set to 0,
                   and a high-priority message is created if _f_l_a_g_s 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 _e_r_r_n_o to
                   [[EEAAGGAAIINN]].

                   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 _i_o_c_t_l() function with the I_FDINSERT command shall fail
                   if:

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

                   EEAAGGAAIINN or EENNOOSSRR
                          Buffers cannot be allocated for the message that is
                          to be created.

                   EEIINNVVAALL One of the following:

                               --  The _f_i_l_d_e_s member of the ssttrrffddiinnsseerrtt
                                   structure is not a valid, open STREAM file
                                   descriptor.

                               --  The size of a tt__uussccaallaarr__tt plus _o_f_f_s_e_t is
                                   greater than the _l_e_n member for the buffer
                                   specified through ccttllbbuuff.

                               --  The _o_f_f_s_e_t member does not specify a
                                   properly-aligned location in the data
                                   buffer.

                               --  An undefined value is stored in _f_l_a_g_s.

                   EENNXXIIOO  Hangup received on the STREAM identified by either
                          the _f_i_l_d_e_s argument or the _f_i_l_d_e_s member of the
                          ssttrrffddiinnsseerrtt structure.

                   EERRAANNGGEE The _l_e_n member for the buffer specified through
                          ddaattaabbuuff does not fall within the range specified by
                          the maximum and minimum packet sizes of the topmost
                          STREAM module; or the _l_e_n member for the buffer
                          specified through ddaattaabbuuff is larger than the maximum
                          configured size of the data part of a message; or
                          the _l_e_n member for the buffer specified through
                          ccttllbbuuff is larger than the maximum configured size of
                          the control part of a message.

       I_STR       Constructs an internal STREAMS _i_o_c_t_l() message from the
                   data pointed to by _a_r_g, and sends that message downstream.

                   This mechanism is provided to send _i_o_c_t_l() requests to
                   downstream modules and drivers. It allows information to be
                   sent with _i_o_c_t_l(), 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 _e_r_r_n_o set to [[EETTIIMMEE]].

                   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 _a_r_g points to a ssttrriiooccttll structure.

                   The _i_c___c_m_d member is the internal _i_o_c_t_l() command intended
                   for a downstream module or driver and _i_c___t_i_m_o_u_t 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.  _i_c___l_e_n
                   is the number of bytes in the data argument, and _i_c___d_p is a
                   pointer to the data argument. The _i_c___l_e_n 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 _i_c___d_p 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 ssttrriiooccttll structure to an internal _i_o_c_t_l() command
                   message and send it downstream.

                   The _i_o_c_t_l() function with the I_STR command shall fail if:

                   EEAAGGAAIINN or EENNOOSSRR
                          Unable to allocate buffers for the _i_o_c_t_l() message.

                   EEIINNVVAALL The _i_c___l_e_n member is less than 0 or larger than the
                          maximum configured size of the data part of a
                          message, or _i_c___t_i_m_o_u_t is less than -1.

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

                   EETTIIMMEE  A downstream _i_o_c_t_l() 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 _i_o_c_t_l() command sent downstream
                   fails. For these cases, I_STR shall fail with _e_r_r_n_o set to
                   the value in the message.

       I_SWROPT    Sets the write mode using the value of the argument _a_r_g.
                   Valid bit settings for _a_r_g are:

                   SNDZERO     Send a zero-length message downstream when a
                               _w_r_i_t_e() of 0 bytes occurs. To not send a zero-
                               length message when a _w_r_i_t_e() of 0 bytes
                               occurs, the application shall ensure that this
                               bit is not set in _a_r_g (for example, _a_r_g would
                               be set to 0).

                   The _i_o_c_t_l() function with the I_SWROPT command shall fail
                   if:

                   EEIINNVVAALL _a_r_g is not the above value.

       I_GWROPT    Returns the current write mode setting, as described above,
                   in the iinntt that is pointed to by the argument _a_r_g.

       I_SENDFD    Creates a new reference to the open file description
                   associated with the file descriptor _a_r_g, and writes a
                   message on the STREAMS-based pipe _f_i_l_d_e_s containing this
                   reference, together with the user ID and group ID of the
                   calling process.

                   The _i_o_c_t_l() function with the I_SENDFD command shall fail
                   if:

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

                   EEBBAADDFF  The _a_r_g argument is not a valid, open file
                          descriptor.

                   EEIINNVVAALL The _f_i_l_d_e_s argument is not connected to a STREAM
                          pipe.

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

                   The _i_o_c_t_l() function with the I_SENDFD command may fail if:

                   EEIINNVVAALL The _a_r_g argument is equal to the _f_i_l_d_e_s 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 _a_r_g
                   argument is a pointer to a ssttrrrreeccvvffdd data structure as
                   defined in _<_s_t_r_o_p_t_s_._h_>.

                   The _f_d member is a file descriptor. The _u_i_d and _g_i_d 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 _e_r_r_n_o set to [[EEAAGGAAIINN]] 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 _f_d member of the ssttrrrreeccvvffdd
                   structure pointed to by _a_r_g.

                   The _i_o_c_t_l() function with the I_RECVFD command shall fail
                   if:

                   EEAAGGAAIINN A message is not present at the STREAM head read
                          queue and the O_NONBLOCK flag is set.

                   EEBBAADDMMSSGG
                          The message at the STREAM head read queue is not a
                          message containing a passed file descriptor.

                   EEMMFFIILLEE All file descriptors available to the process are
                          currently open.

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

       I_LIST      Allows the process to list all the module names on the
                   STREAM, up to and including the topmost driver name. If _a_r_g
                   is a null pointer, the return value shall be the number of
                   modules, including the driver, that are on the STREAM
                   pointed to by _f_i_l_d_e_s.  This lets the process allocate
                   enough space for the module names.  Otherwise, it should
                   point to a ssttrr__lliisstt structure.

                   The _s_l___n_m_o_d_s member indicates the number of entries the
                   process has allocated in the array. Upon return, the
                   _s_l___m_o_d_l_i_s_t member of the ssttrr__lliisstt structure shall contain
                   the list of module names, and the number of entries that
                   have been filled into the _s_l___m_o_d_l_i_s_t array is found in the
                   _s_l___n_m_o_d_s member (the number includes the number of modules
                   including the driver). The return value from _i_o_c_t_l() 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
                   (_s_l___n_m_o_d_s) is satisfied.

                   The _i_o_c_t_l() function with the I_LIST command shall fail if:

                   EEIINNVVAALL The _s_l___n_m_o_d_s member is less than 1.

                   EEAAGGAAIINN or EENNOOSSRR
                          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 _a_r_g 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 _i_o_c_t_l() function with the I_ATMARK command shall fail
                   if:

                   EEIINNVVAALL Invalid _a_r_g 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.  _a_r_g should be of type iinntt.

                   The _i_o_c_t_l() function with the I_CKBAND command shall fail
                   if:

                   EEIINNVVAALL Invalid _a_r_g value.

       I_GETBAND   Returns the priority band of the first message on the
                   STREAM head read queue in the integer referenced by _a_r_g.

                   The _i_o_c_t_l() function with the I_GETBAND command shall fail
                   if:

                   EENNOODDAATTAA
                          No message on the STREAM head read queue.

       I_CANPUT    Checks if a certain band is writable.  _a_r_g 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 _i_o_c_t_l() function with the I_CANPUT command shall fail
                   if:

                   EEIINNVVAALL Invalid _a_r_g 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 _a_r_g 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 _i_o_c_t_l() function with the I_SETCLTIME command shall
                   fail if:

                   EEIINNVVAALL Invalid _a_r_g value.

       I_GETCLTIME Returns the close time delay in the integer pointed to by
                   _a_r_g.

   MMuullttiipplleexxeedd SSTTRREEAAMMSS CCoonnffiigguurraattiioonnss
       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 _f_i_l_d_e_s is the file descriptor
                   of the STREAM connected to the multiplexing driver, and _a_r_g
                   is the file descriptor of the STREAM connected to another
                   driver. The STREAM designated by _a_r_g 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 _i_o_c_t_l() function with the I_LINK command shall fail if:

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

                   EETTIIMMEE  Timeout before acknowledgement message was received
                          at STREAM head.

                   EEAAGGAAIINN or EENNOOSSRR
                          Unable to allocate STREAMS storage to perform the
                          I_LINK.

                   EEBBAADDFF  The _a_r_g argument is not a valid, open file
                          descriptor.

                   EEIINNVVAALL The _f_i_l_d_e_s argument does not support multiplexing;
                          or _a_r_g 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
                   _f_i_l_d_e_s.  In addition, an error code can be returned in the
                   positive or negative acknowledgement message. For these
                   cases, I_LINK fails with _e_r_r_n_o set to the value in the
                   message.

       I_UNLINK    Disconnects the two STREAMs specified by _f_i_l_d_e_s and _a_r_g.
                   _f_i_l_d_e_s is the file descriptor of the STREAM connected to
                   the multiplexing driver. The _a_r_g argument is the
                   multiplexer ID number that was returned by the I_LINK
                   _i_o_c_t_l() command when a STREAM was connected downstream from
                   the multiplexing driver. If _a_r_g is MUXID_ALL, then all
                   STREAMs that were connected to _f_i_l_d_e_s shall be
                   disconnected. As in I_LINK, this command requires
                   acknowledgement.

                   The _i_o_c_t_l() function with the I_UNLINK command shall fail
                   if:

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

                   EETTIIMMEE  Timeout before acknowledgement message was received
                          at STREAM head.

                   EEAAGGAAIINN or EENNOOSSRR
                          Unable to allocate buffers for the acknowledgement
                          message.

                   EEIINNVVAALL 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 _f_i_l_d_e_s.  In addition, an error code can be returned
                   in the positive or negative acknowledgement message. For
                   these cases, I_UNLINK shall fail with _e_r_r_n_o set to the
                   value in the message.

       I_PLINK     Creates a _p_e_r_s_i_s_t_e_n_t _c_o_n_n_e_c_t_i_o_n between two STREAMs, where
                   _f_i_l_d_e_s is the file descriptor of the STREAM connected to
                   the multiplexing driver, and _a_r_g 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 _f_i_l_d_e_s associated with the upper STREAM to
                   the multiplexing driver is closed.  The STREAM designated
                   by _a_r_g 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 _i_o_c_t_l() function with the I_PLINK command shall fail
                   if:

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

                   EETTIIMMEE  Timeout before acknowledgement message was received
                          at STREAM head.

                   EEAAGGAAIINN or EENNOOSSRR
                          Unable to allocate STREAMS storage to perform the
                          I_PLINK.

                   EEBBAADDFF  The _a_r_g argument is not a valid, open file
                          descriptor.

                   EEIINNVVAALL The _f_i_l_d_e_s argument does not support multiplexing;
                          or _a_r_g 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
                   _f_i_l_d_e_s.  In addition, an error code can be returned in the
                   positive or negative acknowledgement message. For these
                   cases, I_PLINK shall fail with _e_r_r_n_o set to the value in
                   the message.

       I_PUNLINK   Disconnects the two STREAMs specified by _f_i_l_d_e_s and _a_r_g
                   from a persistent connection. The _f_i_l_d_e_s argument is the
                   file descriptor of the STREAM connected to the multiplexing
                   driver. The _a_r_g argument is the multiplexer ID number that
                   was returned by the I_PLINK _i_o_c_t_l() command when a STREAM
                   was connected downstream from the multiplexing driver. If
                   _a_r_g is MUXID_ALL, then all STREAMs which are persistent
                   connections to _f_i_l_d_e_s shall be disconnected. As in I_PLINK,
                   this command requires the multiplexing driver to
                   acknowledge the request.

                   The _i_o_c_t_l() function with the I_PUNLINK command shall fail
                   if:

                   EENNXXIIOO  Hangup received on _f_i_l_d_e_s.

                   EETTIIMMEE  Timeout before acknowledgement message was received
                          at STREAM head.

                   EEAAGGAAIINN or EENNOOSSRR
                          Unable to allocate buffers for the acknowledgement
                          message.

                   EEIINNVVAALL 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 _f_i_l_d_e_s.  In addition, an error code can be returned
                   in the positive or negative acknowledgement message. For
                   these cases, I_PUNLINK shall fail with _e_r_r_n_o set to the
                   value in the message.

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

EERRRROORRSS
       Under the following general conditions, _i_o_c_t_l() shall fail if:

       EEBBAADDFF  The _f_i_l_d_e_s argument is not a valid open file descriptor.

       EEIINNTTRR  A signal was caught during the _i_o_c_t_l() operation.

       EEIINNVVAALL The STREAM or multiplexer referenced by _f_i_l_d_e_s is linked
              (directly or indirectly) downstream from a multiplexer.

       If an underlying device driver detects an error, then _i_o_c_t_l() shall
       fail if:

       EEIINNVVAALL The _r_e_q_u_e_s_t or _a_r_g argument is not valid for this device.

       EEIIOO    Some physical I/O error has occurred.

       EENNOOTTTTYY The file associated with the _f_i_l_d_e_s argument is not a STREAMS
              device that accepts control functions.

       EENNXXIIOO  The _r_e_q_u_e_s_t and _a_r_g arguments are valid for this device driver,
              but the service requested cannot be performed on this particular
              sub-device.

       EENNOODDEEVV The _f_i_l_d_e_s argument refers to a valid STREAMS device, but the
              corresponding device driver does not support the _i_o_c_t_l()
              function.

       If a STREAM is connected downstream from a multiplexer, any _i_o_c_t_l()
       command except I_UNLINK and I_PUNLINK shall set _e_r_r_n_o to [[EEIINNVVAALL]].

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

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

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       The _i_o_c_t_l() function may be removed in a future version.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._6, _S_T_R_E_A_M_S, _c_l_o_s_e(), _f_c_n_t_l(), _g_e_t_m_s_g(), _o_p_e_n(), _p_i_p_e(),
       _p_o_l_l(), _p_u_t_m_s_g(), _r_e_a_d(), _s_i_g_a_c_t_i_o_n(), _w_r_i_t_e()

       The Base Definitions volume of POSIX.1-2017, <<ssttrrooppttss..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                             IOCTL(3)
