ioctl(3p) — Linux manual page

PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

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

PROLOG         top

       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         top

       ioctl — control a STREAMS device (STREAMS)

SYNOPSIS         top

       #include <stropts.h>

       int ioctl(int fildes, int request, ... /* arg */);

DESCRIPTION         top

       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         top

       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         top

       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         top

       None.

APPLICATION USAGE         top

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

RATIONALE         top

       None.

FUTURE DIRECTIONS         top

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

SEE ALSO         top

       Section 2.6, STREAMS, close(3p), fcntl(3p), getmsg(3p), open(3p),
       pipe(3p), poll(3p), putmsg(3p), read(3p), sigaction(3p),
       write(3p)

       The Base Definitions volume of POSIX.1‐2017, stropts.h(0p)

COPYRIGHT         top

       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(3P)

Pages that refer to this page: signal.h(0p)stropts.h(0p)close(3p)read(3p)