streamio(7) DG/UX 4.30 streamio(7)
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.
[ENXIO] Open routine of new module failed.
Licensed material--property of copyright holder(s) Page 1
streamio(7) DG/UX 4.30 streamio(7)
[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. You must include the <sys/conf.h> header
file. 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 signal (see
signal(2) and sigset(2)) 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
Licensed material--property of copyright holder(s) Page 2
streamio(7) DG/UX 4.30 streamio(7)
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:
Licensed material--property of copyright holder(s) Page 3
streamio(7) DG/UX 4.30 streamio(7)
[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 following
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 taking the message off
the queue. arg points to a strpeek structure
which contains the following members:
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
The maxlen field in the ctlbuf and databuf
strbuf structures (see getmsg(2)) 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 the
following value:
[EFAULT] arg points, or the buffer area specified in
ctlbuf or databuf is, outside the allocated
address space.
Licensed material--property of copyright holder(s) Page 4
streamio(7) DG/UX 4.30 streamio(7)
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 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 strbuf ctlbuf;
struct strbuf databuf;
long flags;
int fd;
int offset;
Licensed material--property of copyright holder(s) Page 5
streamio(7) DG/UX 4.30 streamio(7)
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 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.
[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
Licensed material--property of copyright holder(s) Page 6
streamio(7) DG/UX 4.30 streamio(7)
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 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 user ioctl
requests to downstream modules and drivers. It
allows information to be sent with the ioctl
call 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
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.
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(2)) 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
Licensed material--property of copyright holder(s) Page 7
streamio(7) DG/UX 4.30 streamio(7)
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 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:
[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
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 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.
Licensed material--property of copyright holder(s) Page 8
streamio(7) DG/UX 4.30 streamio(7)
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(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 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 call 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(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.
The structure is copied into the user data
Licensed material--property of copyright holder(s) Page 9
streamio(7) DG/UX 4.30 streamio(7)
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
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 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 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 descriptor.
[EINVAL]
fildes stream does not support
multiplexing.
[EINVAL]
Licensed material--property of copyright holder(s) Page 10
streamio(7) DG/UX 4.30 streamio(7)
arg is not a stream, or is already linked
under a multiplexor.
[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 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
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 acknowledgement
message was received at stream
head.
[EAGAIN] Unable to allocate buffers for the
acknowledgement message.
[EINVAL] Invalid multiplexor ID number.
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
Licensed material--property of copyright holder(s) Page 11
streamio(7) DG/UX 4.30 streamio(7)
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 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 for the DG/UXTM
System.
STREAMS Programmer's Guide for the DG/UXTM System.
STREAMS Primer for the DG/UXTM System.
DIAGNOSTICS
Unless specified otherwise above, the return value from
ioctl is 0 upon success and -1 upon failure with errno set
as indicated.
Licensed material--property of copyright holder(s) Page 12