STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
NAME
streamio - STREAMS ioctl commands
SYNOPSIS
#include <stropts.h>
int ioctl (fildes, command, arg)
int fildes, command;
DESCRIPTION
STREAMS [see intro(2)] ioctl commands are a subset of
ioctl(2) 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 multiplexor, 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.
Printed 1/28/91 Page 1
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
[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 fol-
lowing 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:
[EAGAIN] Unable to allocate buffers for flush
message.
[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
Page 2 Printed 1/28/91
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
signal [see signal(2) and sigset(2)]
when a particular event has occurred on
the stream associated with fildes.
I_SETSIG supports an asynchronous pro-
cessing 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 down-
stream.
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 sig-
nal 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 fol-
lowing values:
[EINVAL] arg value is invalid or arg is zero and
process is not registered to receive the
SIGPOLL signal.
Printed 1/28/91 Page 3
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
[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 fol-
lowing values:
[EINVAL] Process not registered to receive the
SIGPOLL signal.
[EFAULT] arg points outside the allocated address
space.
I_FIND 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. It returns 0 if the
named module is not present. On
failure, errno is set to one of the fol-
lowing values:
[EFAULT] arg points outside the allocated address
space.
[EINVAL] arg does not contain a valid module
name.
I_PEEK This request allows a user to retrieve
the information in the first message on
the stream head read queue without tak-
ing the message off the queue. arg
points to a strpeek structure which con-
tains the following members:
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
The maxlen field in the ctlbuf and data-
buf strbuf structures [see getmsg(2)]
must be set to the number of bytes of
control information and/or data informa-
tion, respectively, to retrieve. If the
user sets flags to RS_HIPRI, I_PEEK will
only look for a priority message on the
Page 4 Printed 1/28/91
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
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 the follow-
ing value:
[EFAULT] arg points, or the buffer area specified
in ctlbuf or databuf is, outside the
allocated address space.
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(2). 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(2). 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
Printed 1/28/91 Page 5
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
value is greater than zero, this indi-
cates 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 con-
trol 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 strbuf ctlbuf;
struct strbuf databuf;
long flags;
int fd;
int offset;
The len field in the ctlbuf strbuf
structure [see putmsg(2)] must be set to
the size of a pointer plus the number of
bytes of control information to be sent
with the message. fd specifies the file
descriptor of the other stream and
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 to the
fd stream's driver read queue 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 mes-
sages, I_FDINSERT will block if the
stream write queue is full due to inter-
nal flow control conditions. For
Page 6 Printed 1/28/91
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
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 inter-
nal flow control conditions.
[EAGAIN] Buffers could not be allocated for the
message that was to be created.
[EFAULT] arg points, or the buffer area specified
in ctlbuf or databuf is, outside the
allocated address space.
[EINVAL] One of the following: fd 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.
[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 max-
imum configured size of the control part
of a message.
Printed 1/28/91 Page 7
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
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 ack-
nowledgement 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 inter-
val for these requests is 15 seconds.
The O_NDELAY [see open(2)] flag has no
effect on this call.
To send requests downstream, arg must
point to a strioctl structure which con-
tains 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 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 field
has two uses: on input, it contains the
length of the data argument passed in,
and on return from the command, it con-
tains 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
Page 8 Printed 1/28/91
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
return).
The stream head will convert the infor-
mation pointed to by the strioctl struc-
ture to an internal ioctl command mes-
sage and send it downstream. On
failure, errno is set to one of the fol-
lowing values:
[EAGAIN] Unable to allocate buffers for the ioctl
message.
[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 ack-
nowledgement was received.
An I_STR can also fail while waiting for
an acknowledgement if a message indicat-
ing 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 will fail
with errno set to the value in the mes-
sage.
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
Printed 1/28/91 Page 9
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
queue [see intro(2)] 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 mes-
sage sent by I_SENDFD.
[EBADF] arg is not a valid, open file descrip-
tor.
[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 con-
taining 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(2)],
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.
Page 10 Printed 1/28/91
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
The structure is copied into the user
data buffer pointed to by arg. On
failure, errno is set to one of the fol-
lowing 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 con-
nected 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 acknowledgement message to the stream
head regarding the linking operation.
This call returns a multiplexor ID
number (an identifier used to disconnect
the multiplexor, see I_UNLINK) on suc-
cess, 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 acknowledgement message
was received at stream head.
[EAGAIN] Unable to allocate STREAMS storage to
perform the I_LINK.
[EBADF] arg is not a valid, open file descrip-
tor.
Printed 1/28/91 Page 11
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
[EINVAL] fildes stream does not support multi-
plexing.
[EINVAL] arg is not a stream, or is already
linked under a multiplexor.
[EINVAL] The specified link operation would cause
a "cycle" in the resulting configura-
tion; 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 ack-
nowledge 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
acknowledgement 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. arg is the
multiplexor ID number that was returned
by the ioctl I_LINK command when a
stream was linked below the multiplexing
driver. If arg is -1, then all Streams
which were linked to fildes are discon-
nected. As in I_LINK, this command
requires the multiplexing driver to ack-
nowledge the unlink. On failure, errno
is set to one of the following values:
[ENXIO] Hangup received on fildes.
[ETIME] Time out before acknowledgement message
was received at stream head.
[EAGAIN] Unable to allocate buffers for the ack-
nowledgement message.
[EINVAL] Invalid multiplexor ID number.
An I_UNLINK can also fail while waiting
for the multiplexing driver to ack-
nowledge the link request, if a message
indicating an error or a hangup is
received at the stream head of fildes.
Page 12 Printed 1/28/91
STREAMIO(7-SysV) RISC/os Reference Manual STREAMIO(7-SysV)
In addition, an error code can be
returned in the positive or negative
acknowledgement message. For these
cases, I_UNLINK will fail with errno set
to the value in the message.
SEE ALSO
close(2), fcntl(2), intro(2), ioctl(2), open(2), read(2),
getmsg(2), poll(2), putmsg(2), signal(2), sigset(2),
write(2) in the Programmer's Reference Manual.
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 1/28/91 Page 13