ioctl(2) ioctl(2)
NAME
ioctl - control devices and STREAMS
SYNOPSIS
#include <unistd.h>
int ioctl(int fildes, int request, ... /* arg */);
DESCRIPTION
The ioctl() function performs 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) are 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 de-
vice.
The request argument selects the control function to be performed and
will 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 is
either an integer or a pointer to a device-specific data structure.
The ioctl() commands applicable to STREAMS, their arguments, and error
statuses that apply to each individual command are described below.
The following ioctl() commands, with error values indicated, are
applicable to all STREAMS files:
IPUSH 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 IPUSH command will fail if:
EINVAL Invalid module name.
ENXIO Open function of new module failed.
ENXIO Hangup received on fildes.
IPOP Removes the module just below the stream head of the
stream pointed to by fildes. The arg argument should be 0
in an IPOP request.
The ioctl() function with the IPOP command will fail if:
EINVAL No module present in the stream.
Page 1 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
ENXIO Hangup received on fildes.
ILOOK 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 ILOOK command will fail if:
EINVAL No module present in the stream.
IFLUSH This request 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 IFLUSH command will fail
if:
EINVAL Invalid arg value.
EAGAIN or ENOSR
Unable to allocate buffers for flush message.
ENXIO Hangup received on fildes.
IFLUSHBAND Flushes a particular band of messages. The arg argument
points to a bandinfo structure. The biflag member may be
one of FLUSHR, FLUSHW, or FLUSHRW as described above. The
bipri member determines the priority band to be flushed.
ISETSIG 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. ISETSIG
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-OR of any combination of the following constants:
SRDNORM A normal (priority band set to 0) message has
arrived at the head of a stream head read queue.
A signal will be generated even if the message
is of zero length.
Page 2 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
SRDBAND A message with a non-zero priority band has
arrived at the head of a stream head read queue.
A signal will be generated even if the message
is of zero length.
SINPUT A message, other than a high-priority message,
has arrived at the head of a stream head read
queue. A signal will be generated even if the
message is of zero length.
SHIPRI A high-priority message is present on a stream
head read queue. A signal will be generated even
if the message is of zero length.
SOUTPUT 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.
SWRNORM Same as SOUTPUT.
SWRBAND 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.
SMSG A STREAMS signal message that contains the
SIGPOLL signal has reached the front of the
stream head read queue.
SERROR Notification of an error condition has reached
the stream head.
SHANGUP Notification of a hangup has reached the stream
head.
SBANDURG When used in conjunction with SRDBAND, 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 will be unregistered and
will not receive further SIGPOLL signals for the stream
associated with fildes.
Processes that wish to receive SIGPOLL signals must expli-
citly register to receive them using ISETSIG. If several
processes register to receive this signal for the same
event on the same stream, each process will be signaled
when the event occurs.
Page 3 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
The ioctl() function with the ISETSIG command will 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.
IGETSIG 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 descrip-
tion of ISETSIG above.
The ioctl() function with the IGETSIG command will fail
if:
EINVAL Process is not registered to receive the SIGPOLL
signal.
IFIND This request 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 IFIND command will fail if:
EINVAL arg does not contain a valid module name.
IPEEK This request allows a process to retrieve 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 mes-
sage from the queue. The arg argument points to a strpeek
structure.
The maxlen member in the ctlbuf and databuf strbuf struc-
tures must be set to the number of bytes of control infor-
mation and/or data information, respectively, to retrieve.
The flags member may be marked RSHIPRI or 0, as described
by getmsg(2). If the process sets flags to RSHIPRI, for
example, IPEEK will only look for a high-priority message
on the stream head read queue.
Page 4 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
IPEEK returns 1 if a message was retrieved, and returns 0
if no message was found on the stream head read queue, or
if the RSHIPRI 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 con-
tains the value RSHIPRI or 0.
ISRDOPT Sets the read mode using the value of the argument arg.
Read modes are described in read(2). 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 will return
EINVAL. The bitwise inclusive OR of RNORM and either RMSGD
or RMSGN will 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, deliver-
ing any data portion, when a process issues a
read().
The ioctl() function with the ISRDOPT command will fail
if:
EINVAL The arg argument is not valid.
IGRDOPT Returns the current read mode setting as, described above,
in an int pointed to by the argument arg. Read modes are
described in read(2).
Page 5 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
INREAD 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 is 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.
IFDINSERT Creates a message from specified buffer(s), adds informa-
tion about another stream, and sends the message down-
stream. 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 len member in the ctlbuf strbuf structure must be set
to the size of a pointer plus the number of bytes of con-
trol 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 pointer, specifies the offset from the start of
the control buffer where IFDINSERT will store a pointer
whose interpretation is specific to the stream end. The
len member in the databuf strbuf structure must be 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
RSHIPRI. For non-priority messages, IFDINSERT will block
if the stream write queue is full due to internal flow
control conditions. For priority messages, IFDINSERT does
not block on this condition. For non-priority messages,
IFDINSERT does not block when the write queue is full and
ONONBLOCK is set. Instead, it fails and sets errno to
EAGAIN.
IFDINSERT also blocks, unless prevented by lack of inter-
nal resources, waiting for the availability of message
blocks in the stream, regardless of priority or whether
ONONBLOCK has been specified. No partial message is sent.
Page 6 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
The ioctl() function with the IFDINSERT command will fail
if:
EAGAIN A non-priority message is specified, the
ONONBLOCK flag is set, and the stream write
queue is full due to internal flow control con-
ditions.
EAGAIN or ENOSR
Buffers can not be allocated for the message
that is to be created.
EINVAL One of the following:
- The fd member of the strfdinsert structure is
not a valid, open stream file descriptor.
- The size of a pointer plus offset is greater
than the len member for the buffer specified
through ctlptr.
- The offset member does not specify a prop-
erly-aligned location in the data buffer.
- An undefined value is stored in flags.
ENXIO Hangup received on fd or fildes.
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 max-
imum configured size of the control part of a
message.
ISTR 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.
ISTR blocks until the system responds with either a posi-
tive or negative acknowledgement message, or until the
request "times out" after some period of time. If the
request times out, it fails with errno set to ETIME.
Page 7 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
At most, one ISTR can be active on a stream. Further
ISTR calls will block until the active ISTR completes at
the stream head. The default timeout interval for these
requests is 15 seconds. The ONONBLOCK flag has no effect
on this call.
To send requests downstream, arg must point to a strioctl
structure.
The iccmd member is the internal ioctl() command intended
for a downstream module or driver and ictimout is the
number of seconds (-1 = infinite, 0 = use implementation-
dependent timeout interval, >0 = as specified) an ISTR
request will wait for acknowledgement before timing out.
iclen is the number of bytes in the data argument, and
icdp is a pointer to the data argument. The iclen 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 icdp 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 will convert the information pointed to by
the strioctl structure to an internal ioctl() command mes-
sage and send it downstream.
The ioctl() function with the ISTR command will fail if:
EAGAIN or ENOSR
Unable to allocate buffers for the ioctl() mes-
sage.
EINVAL The iclen member is less than 0 or larger than
the maximum configured size of the data part of
a message, or ictimout is less than -1.
ENXIO Hangup received on fildes.
ETIME A downstream ioctl() timed out before ack-
nowledgement was received.
An ISTR can also fail while waiting for an acknowledge-
ment 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 acknowledge-
ment message, in the event the ioctl() command sent down-
stream fails. For these cases, ISTR fails with errno set
to the value in the message.
ISWROPT Sets the write mode using the value of the argument arg.
Valid bit settings for arg are:
Page 8 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
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,
this bit must not be set in arg (for example,
arg would be set to 0).
The ioctl() function with the ISWROPT command will fail
if:
EINVAL arg is not the above value.
IGWROPT Returns the current write mode setting, as described
above, in the int that is pointed to by the argument arg.
ISENDFD ISENDFD creates a new reference to the open file descrip-
tion 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 ISENDFD command will fail
if:
EAGAIN The sending stream is unable to allocate a mes-
sage block to contain the file pointer; or the
read queue of the receiving stream head is full
and cannot accept the message sent by ISENDFD.
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.
IRECVFD Retrieves the reference to an open file description from a
message written to a STREAMS-based pipe using the ISENDFD
command, and allocates a new file descriptor in the cal-
ling process that refers to this open file description.
The arg argument is a pointer to an strrecvfd data struc-
ture 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 ONONBLOCK is not set IRECVFD blocks until a message
is present at the stream head. If ONONBLOCK is set,
IRECVFD fails with errno set to EAGAIN if no message is
present at the stream head.
Page 9 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
If the message at the stream head is a message sent by an
ISENDFD, a new file descriptor is 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 IRECVFD command will fail
if:
EAGAIN A message is not present at the stream head read
queue and the ONONBLOCK flag is set.
EBADMSG The message at the stream head read queue is not
a message containing a passed file descriptor.
EMFILE The process has the maximum number of file
descriptors currently open that it is allowed.
ENXIO Hangup received on fildes.
ILIST This request 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 is
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 an strlist structure.
The slnmods member indicates the number of entries the
process has allocated in the array. Upon return, the
slmodlist member of the strlist structure contains the
list of module names, and the number of entries that have
been filled into the slmodlist array is found in the
slnmods member (the number includes the number of modules
including the driver). The return value from ioctl() is 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
(slnmods) is satisfied.
The ioctl() function with the ILIST command will fail if:
EINVAL The slnmods member is less than 1.
EAGAIN or ENOSR
Unable to allocate buffers.
Page 10 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
IATMARK This request 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 mes-
sages 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 is 1 if the mark condition is satisfied
and 0 otherwise.
The ioctl() function with the IATMARK command will fail
if:
EINVAL Invalid arg value.
ICKBAND Check if the message of a given priority band exists on
the stream head read queue. This returns 1 if a message of
the given priority exists, 0 if no message exists, or -1
on error. arg should be of type int.
The ioctl() function with the ICKBAND command will fail
if:
EINVAL Invalid arg value.
IGETBAND Return the priority band of the first message on the
stream head read queue in the integer referenced by arg.
The ioctl() function with the IGETBAND command will fail
if:
ENODATA No message on the stream head read queue.
ICANPUT Check if a certain band is writable. arg is set to the
priority band in question. The return value is 0 if the
band is flow-controlled, 1 if the band is writable, or -1
on error.
The ioctl() function with the ICANPUT command will fail
if:
EINVAL Invalid arg value.
Page 11 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
ISETCLTIME This request allows the process to set the time the stream
head will 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 will
delay for the specified amount of time to allow the data
to drain. If, after the delay, data is still present, they
will 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 ISETCLTIME is
not performed on a stream, an implementation-dependent
default timeout interval is used.
The ioctl() function with the ISETCLTIME command will
fail if:
EINVAL Invalid arg value.
IGETCLTIME This request returns the close time delay in the integer
pointed to by arg.
Multiplexed STREAMS Configurations
The following four commands are used for connecting and disconnecting
multiplexed STREAMS configurations. These commands use an implemen-
tation-dependent default timeout interval.
ILINK 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 gets con-
nected below the multiplexing driver. ILINK requires the
multiplexing driver to send an acknowledgement message to
the stream head regarding the connection. This call
returns a multiplexer ID number (an identifier used to
disconnect the multiplexer; see IUNLINK) on success, and
-1 on failure.
The ioctl() function with the ILINK command will fail if:
ENXIO Hangup received on fildes.
ETIME Time out before acknowledgement message was
received at stream head.
EAGAIN or ENOSR
Unable to allocate STREAMS storage to perform
the ILINK.
EBADF The arg argument is not a valid, open file
descriptor.
Page 12 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
EINVAL The fildes argument does not support multiplex-
ing; or arg is not a stream or is already con-
nected downstream from a multiplexer; or the
specified ILINK operation would connect the
stream head in more than one place in the multi-
plexed stream.
An ILINK 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, ILINK fails with errno set to the value in the
message.
IUNLINK 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 multi-
plexer ID number that was returned by the ILINK ioctl()
command when a stream was connected downstream from the
multiplexing driver. If arg is MUXIDALL, then all streams
that were connected to fildes are disconnected. As in
ILINK, this command requires acknowledgement.
The ioctl() function with the IUNLINK command will fail
if:
ENXIO Hangup received on fildes.
ETIME Time out before acknowledgement message was
received at stream head.
EAGAIN or ENOSR
Unable to allocate buffers for the acknowledge-
ment message.
EINVAL Invalid multiplexer ID number.
An IUNLINK can also fail while waiting for the multiplex-
ing driver to acknowledge the request if a message indi-
cating 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, IUNLINK fails with errno set to the value in
the message.
Page 13 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
IPLINK 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 creates
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. IPLINK requires the multiplexing
driver to send an acknowledgement message to the stream
head. This call returns a multiplexer ID number (an iden-
tifier that may be used to disconnect the multiplexer, see
IPUNLINK) on success, and -1 on failure.
The ioctl() function with the IPLINK command will fail
if:
ENXIO Hangup received on fildes.
ETIME Time out before acknowledgement message was
received at stream head.
EAGAIN or ENOSR
Unable to allocate STREAMS storage to perform
the IPLINK.
EBADF The arg argument is not a valid, open file
descriptor.
EINVAL The fildes argument does not support multiplex-
ing; or arg is not a stream or is already con-
nected downstream from a multiplexer; or the
specified IPLINK operation would connect the
stream head in more than one place in the multi-
plexed stream.
An IPLINK can also fail while waiting for the multiplex-
ing driver to acknowledge the request, if a message indi-
cating 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, IPLINK fails with errno set to the value in
the message.
Page 14 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
IPUNLINK 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 multiplex-
ing driver. The arg argument is the multiplexer ID number
that was returned by the IPLINK ioctl() command when a
stream was connected downstream from the multiplexing
driver. If arg is MUXIDALL then all streams which are
persistent connections to fildes are disconnected. As in
IPLINK, this command requires the multiplexing driver to
acknowledge the request.
The ioctl() function with the IPUNLINK command will fail
if:
ENXIO Hangup received on fildes.
ETIME Time out before acknowledgement message was
received at stream head.
EAGAIN or ENOSR
Unable to allocate buffers for the acknowledge-
ment message.
EINVAL Invalid multiplexer ID number.
An IPUNLINK can also fail while waiting for the multi-
plexing 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, IPUNLINK fails with errno set to the value
in the message.
RETURN VALUE
Upon successful completion, ioctl() returns a value other than -1 that
depends upon the STREAMS device control function. Otherwise, it
returns -1 and sets errno to indicate the error.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
Under the following general conditions, ioctl() will 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.
Page 15 Reliant UNIX 5.44 Printed 11/98
ioctl(2) ioctl(2)
If an underlying device driver detects an error, then ioctl() will
fail if:
EINVAL The request or arg argument is not valid for this device.
EIO Some physical I/O error has occurred.
ENOTTY The fildes argument is not associated with a STREAMS device
that accepts control functions.
ENXIO The request and arg arguments are valid for this device
driver, but the service requested can not 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 IUNLINK and IPUNLINK will set errno to EINVAL.
APPLICATION USAGE
The implementation-defined timeout interval for STREAMS has histori-
cally been 15 seconds.
SEE ALSO
close(2), fcntl(2), getmsg(2), open(2), pipe(2), poll(2), putmsg(2),
read(2), sigaction(2), write(2), unistd(4), stropts(5), streamio(7),
termio(7).
Page 16 Reliant UNIX 5.44 Printed 11/98