STREAMIO(M) UNIX System V
Name
streamio - STREAMS ioctl commands
Syntax
#include <stropts.h>
int ioctl (fildes, command, arg)
int fildes, command;
Description
STREAMS [see intro(S)] ioctl commands are a subset of
ioctl(S) system calls which perform a variety of control
functions on streams. The arguments command and arg
are passed to the file designated by fildes and are interpreted
by the stream head. Certain combinations of these arguments
may be passed to a module or driver in the stream.
fildes is an open file descriptor that refers to a stream.
command determines the control function to be performed as
described below. arg represents additional information that
is needed by this command. The type of arg depends upon the
command, but it is generally an integer or a pointer to a
command-specific data structure.
Since these STREAMS commands are a subset of ioctl, they are
subject to the errors described there. In addition to those
errors, the call will fail with errno set to EINVAL, without
processing a control function, if the stream referenced by
fildes is linked below a multiplexer, or if command is not a
valid value for a stream.
Also, as described in ioctl, STREAMS modules and drivers can
detect errors. In this case, the module or driver sends an
error message to the stream head containing an error value.
This causes subsequent system calls to fail with errno set
to this value.
Command Functions
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
routine of the newly-pushed module. On
failure, errno is set to one of the following
values:
[EINVAL] Invalid module name.
[EFAULT] arg points outside the allocated
address space.
[ENXIO] Open routine 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. arg should
be 0 in an I_POP request. On failure, errno is
set to one of the following values:
[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 null terminated character
string pointed at by arg. The buffer pointed
to by arg should be at least FMNameSZ+1 bytes
long. An [#include <sys/conf.h>] declaration
is required. On failure, errno is set to one
of the following values:
[EFAULT] arg points outside the allocated
address space.
[EINVAL] No module present in stream.
I_FLUSH This request flushes all input and/or output
queues, depending on the value of arg. Legal
arg values are:
FLUSHR Flush read queues.
FLUSHW Flush write queues.
FLUSHRW Flush read and write queues.
On failure, errno is set to one of the following values:
[ENOSR] Unable to allocate buffers for
flush message due to insufficient
STREAMS memory resources.
[EINVAL] Invalid arg value.
[ENXIO] Hangup received on fildes.
I_SETSIG Informs the stream head that the user wishes
the kernel to issue the SIGPOLL signal [see
signal(S) and sigset(S)] 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 user should be signaled. It is the
bitwise-OR of any combination of the following
constants:
S_INPUT A non-priority message has arrived
on a stream head read queue, and
no other messages existed on that
queue before this message was
placed there. This is set even if
the message is of zero length.
S_HIPRI A priority message is present on
the stream head read queue. This
is set even if the message is of
zero length.
S_OUTPUT The write queue just below the
stream head is no longer full.
This notifies the user that there
is room on the queue for sending
(or writing) data downstream.
S_MSG A STREAMS signal message that
contains the SIGPOLL signal has
reached the front of the stream
head read queue.
A user process may choose to be signaled only of priority
messages by setting the arg bitmask to the value S_HIPRI.
Processes that wish to receive SIGPOLL signals must
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 will be signaled
when the event occurs.
If the value of arg is zero, the calling process will be
unregistered and will not receive further SIGPOLL signals.
On failure, errno is set to one of the following values:
[EINVAL] arg value is invalid or arg is
zero and process is not registered
to receive the SIGPOLL signal.
[EAGAIN] Allocation of a data structure to
store the signal request failed.
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 pointed to by arg, where the events are
those specified in the description of I_SETSIG
above. On failure, errno is set to one of the
following values:
[EINVAL] Process not registered to receive
the SIGPOLL signal.
[EFAULT] arg points outside the allocated
address space.
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. It returns 0 if the
named module is not present. On failure, errno
is set to one of the following values:
[EFAULT] arg points outside the allocated
address space.
[EINVAL] arg does not contain a valid
module name.
I_PEEK Allows a user to retrieve the information in
the first message on the stream head read queue
without taking the message off the queue. arg
points to a strpeek structure which contains
the following members:
struct strbufctlbuf;
struct strbufdatabuf;
long flags;
The maxlen field in the ctlbuf and databuf
strbuf structures [see getmsg(S)] must be set
to the number of bytes of control information
and/or data information, respectively, to
retrieve. If the user sets flags to RS_HIPRI,
I_PEEK will only look for a 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 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 0 or
RS_HIPRI. On failure, errno is set to one of
the following values:
[EFAULT] arg points, or the buffer area
specified in ctlbuf or databuf is,
outside the allocated address
space.
[EBADMSG] Queued message to be read is not
valid for I_PEEK
I_SRDOPT Sets the read mode using the value of the
argument arg. Legal arg values are:
RNORM Byte-stream mode, the default.
RMSGD Message-discard mode.
RMSGN Message-nondiscard mode.
Read modes are described in read(S). On failure, errno is
set to the following value:
[EINVAL] arg is not one of the above legal
values.
I_GRDOPT Returns the current read mode setting in an int
pointed to by the argument arg. Read modes are
described in read(S). On failure, errno is set
to the following value:
[EFAULT] arg points outside the allocated
address space.
I_NREAD Counts the number of data bytes in data blocks
in the first message on the stream head read
queue, and places this value in the location
pointed to by arg. The return value for the
command is the number of messages on the stream
head read queue. For example, if zero is
returned in arg, but the ioctl return value is
greater than zero, this indicates that a zero-
length message is next on the queue. On
failure, errno is set to the following value:
[EFAULT] arg points outside the allocated
address space.
I_FDINSERT Creates a message from user 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.
arg points to a strfdinsert structure which
contains the following members:
struct strbufctlbuf;
struct strbufdatabuf;
long flags;
int fildes;
int offset;
The len field in the ctlbuf strbuf structure
[see putmsg(S)] must be set to the size of a
pointer plus the number of bytes of control
information to be sent with the message.
fildes in the strfdinsert structure specifies
the file descriptor of the other stream.
offset, which must be word-aligned, specifies
the number of bytes beyond the beginning of the
control buffer where I_FDINSERT will store a
pointer. This pointer will be the address of
the read queue structure of the driver for the
stream corresponding to fildes in the
strfdinsert structure. The len field in the
databuf strbuf structure must be set to the
number of bytes of data information to be sent
with the message or zero if no data part is to
be sent.
flags specifies the type of message to be
created. A non-priority message is created if
flags is set to 0, and a priority message is
created if flags is set to RS_HIPRI. For non-
priority messages, I_FDINSERT will 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_NDELAY
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_NDELAY has
been specified. No partial message is sent.
On failure, errno is set to one of the
following values:
[EAGAIN]
A non-priority message was
specified, the O_NDELAY flag is
set, and the stream write queue
is full due to internal flow
control conditions.
[ENOSR] Buffers could not be allocated for
the message that was to be created
due to insufficient STREAMS memory
resources.
[EFAULT] arg points, or the buffer area
specified in ctlbuf or databuf is,
outside the allocated address
space.
[EINVAL] One of the following: fildes in
the strfdinsert structure is not a
valid, open stream file
descriptor; the size of a pointer
plus offset is greater than the
len field for the buffer specified
through ctlptr; offset does not
specify a properly aligned
location in the data buffer; an
undefined value is stored in
flags.
[ENXIO] Hangup received on fildes of the
ioctl call or fildes in the
strfdinsert structure.
[ERANGE] The len field 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 field for the
buffer specified through databuf
is larger than the maximum
configured size of the data part
of a message, or the len field for
the buffer specified through
ctlbuf is larger than the maximum
configured size of the control
part of a message.
I_FDINSERT can also fail if an error message was received by
the stream head of the stream corresponding to fildes in the
strfdinsert structure. In this case, errno will be set to
the value in the 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 user ioctl
requests to downstream modules and drivers. It
allows information to be sent with the ioctl
and will return to the user any information
sent upstream by the downstream recipient.
I_STR blocks until the system responds with
either a positive or negative acknowledgment
message or until the request "times out" after
some period of time. If the request times out,
it fails with errno set to ETIME.
At most, one I_STR can be active on a stream.
Further I_STR calls will block until the active
I_STR completes at the stream head. The
default timeout interval for these requests is
15 seconds. The O_NDELAY [see open(S)] flag
has no effect on this call.
To send requests downstream, arg must point to
a strioctl structure which contains the
following members:
int ic_cmd; /* downstream command */
int ic_timout;/* ACK/NAK timeout */
int ic_len; /* length of data arg */
char *ic_dp; /* ptr to data arg */
ic_cmd is the internal ioctl command intended
for a downstream module or driver; and
ic_timout is the number of seconds (-1 =
infinite, 0 = use default, >0 = as specified)
an I_STR request will wait for acknowledgment
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 field
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 user (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 will convert the information
pointed to by the strioctl structure to an
internal ioctl command message and send it
downstream. On failure, errno is set to one of
the following values:
[ENOSR] Unable to allocate buffers for the
ioctl message due to insufficient
STREAMS memory resources.
[EFAULT] arg points, or the buffer area
specified by ic_dp and ic_len
(separately for data sent and data
returned) is, outside the
allocated address space.
[EINVAL] ic_len is less than 0 or ic_len is
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 acknowledgment was
received.
An I_STR can also fail while waiting for an acknowledgment
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 acknowledgment message, in the
event the ioctl command sent downstream fails. For these
cases, I_STR will fail with errno set to the value in the
message.
I_SENDFD Requests the stream associated with fildes to
send a message, containing a file pointer, to
the stream head at the other end of a stream
pipe. The file pointer corresponds to arg,
which must be an integer file descriptor.
I_SENDFD converts arg into the corresponding
system file pointer. It allocates a message
block and inserts the file pointer in the
block. The user id and group id associated
with the sending process are also inserted.
This message is placed directly on the read
queue [see intro(S)] of the stream head at the
other end of the stream pipe to which it is
connected. On failure, errno is set to one of
the following values:
[EAGAIN] The sending stream is unable to
allocate a message block to
contain the file pointer.
[EAGAIN] The read queue of the receiving
stream head is full and cannot
accept the message sent by
I_SENDFD.
[EBADF] arg is not a valid, open file
descriptor.
[EINVAL] fildes is not connected to a
stream pipe.
[ENXIO] Hangup received on fildes.
I_RECVFD Retrieves the file descriptor associated with
the message sent by an I_SENDFD ioctl over a
stream pipe. arg is a pointer to a data buffer
large enough to hold an strrecvfd data
structure containing the following members:
int fd;
unsigned short uid;
unsigned short gid;
char fill[8];
fd is an integer file descriptor. uid and gid
are the user id and group id, respectively, of
the sending stream.
If O_NDELAY is not set [see open(S)], I_RECVFD
will block until a message is present at the
stream head. If O_NDELAY is set, I_RECVFD will
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 user file descriptor
is allocated for the file pointer contained in
the message. The new file descriptor is placed
in the fd field of the strrecvfd structure.
The structure is copied into the user data
buffer pointed to by arg. On failure, errno is
set to one of the following values:
[EAGAIN] A message was not present at the
stream head read queue, and the
O_NDELAY flag is set.
[EBADMSG] The message at the stream head
read queue was not a message
containing a passed file
descriptor.
[EFAULT] arg points outside the allocated
address space.
[EMFILE] NOFiles file descriptors are
currently open.
[ENXIO] Hangup received on fildes.
The following two commands are used for connecting and
disconnecting multiplexed STREAMS configurations.
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 gets
connected below the multiplexing driver.
I_LINK requires the multiplexing driver to send
an acknowledgment message to the stream head
regarding the linking operation. This call
returns a multiplexer ID number (an identifier
used to disconnect the multiplexer, see
I_UNLINK) on success, and a -1 on failure. On
failure, errno is set to one of the following
values:
[ENXIO] Hangup received on fildes.
[ETIME] Time out before acknowledgment
message was received at stream
head.
[EAGAIN] Temporarily unable to allocate
storage to perform the I_LINK.
[ENOSR] Unable to allocate storage to
perform the I_LINK due to
insufficient STREAMS memory
resources.
[EBADF] arg is not a valid, open file
descriptor.
[EINVAL] fildes stream does not support
multiplexing.
[EINVAL] arg is not a stream, or is already
linked under a multiplexer.
[EINVAL] The specified link operation would
cause a "cycle" in the resulting
configuration; that is, if a given
stream head is linked into a
multiplexing configuration in more
than one place.
An I_LINK can also fail while waiting for the multiplexing
driver to acknowledge the link 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 acknowledgment message. For
these cases, I_LINK will fail 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.
fildes must correspond to the stream on which
the ioctl I_LINK command was issued to link the
stream below the multiplexing driver. arg is
the multiplexer ID number that was returned by
the I_LINK. If arg is -1, then all Streams
which were linked to fildes are disconnected.
As in I_LINK, this command requires the
multiplexing driver to acknowledge the unlink.
On failure, errno is set to one of the
following values:
[ENXIO] Hangup received on fildes.
[ETIME] Time out before acknowledgment
message was received at stream
head.
[ENOSR] Unable to allocate storage to
perform the I_UNLINK due to
insufficient STREAMS memory
resources.
[EINVAL] arg is an invalid multiplexer ID
number or fildes is not the stream
on which the I_LINK that returned
arg was performed.
An I_UNLINK can also fail while waiting for the multiplexing
driver to acknowledge the link 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 acknowledgment message. For
these cases, I_UNLINK will fail with errno set to the value
in the message.
See Also
close(S), fcntl(S), intro(S), ioctl(S), open(S), read(S),
getmsg(S), poll(S), putmsg(S), signal(S), sigset(S),
write(S)
STREAMS Programmer's Guide
STREAMS Primer
Diagnostics
Unless specified otherwise above, the return value from
ioctl is 0 upon success and -1 upon failure with errno set
as indicated.
(printed 8/23/89) STREAMIO(M)