Provided by: manpages-posix-dev_2017a-2_all 
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.
SEE ALSO
Section 2.6, STREAMS, close(), fcntl(), getmsg(), open(), pipe(), poll(), putmsg(),
read(), sigaction(), write()
The Base Definitions volume of POSIX.1‐2017, <stropts.h>
COPYRIGHT
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 .