streamio(7) CLIX streamio(7)
NAME
streamio - STREAMS ioctl() commands
SYNOPSIS
#include <stropts.h>
int ioctl(
int fildes ,
int command ,
int arg );
DESCRIPTION
STREAMS (see intro(2)) ioctl() commands are a subset of ioctl() function
calls which perform a variety of control functions on streams. The
command and arg parameters are passed to the file designated by fildes and
are interpreted by the stream head. Certain combinations of these
parameters may be passed to a module or driver in the stream.
The fildes parameter is an open file descriptor that refers to a stream.
The command parameter determines the control function to be performed as
described below. The arg parameter 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 fails
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.
2/94 - Intergraph Corporation 1
streamio(7) CLIX streamio(7)
[EFAULT] The arg parameter 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. The arg parameter 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] The arg parameter 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() and sigset()) when a particular
event has occurred on the stream associated with fildes. I_SETSIG
supports an asynchronous processing capability in STREAMS. The
2 Intergraph Corporation - 2/94
streamio(7) CLIX streamio(7)
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 nonpriority 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 length 0.
[S_HIPRI] A priority message is present on the stream head read
queue. This is set even if the message is of length
0.
[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 is signaled when the event occurs.
If the value of arg is 0, 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] The value of arg is invalid or arg is 0 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] The arg parameter points outside the allocated address
space.
2/94 - Intergraph Corporation 3
streamio(7) CLIX streamio(7)
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] The arg parameter points outside the allocated address
space.
[EINVAL] The arg parameter 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. The arg parameter points to a strpeek structure which
contains the following members:
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
The maxlen member in the ctlbuf and databuf strbuf structures (see
getmsg()) 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] The arg parameter 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 arg parameter. Legal arg
values are:
[RNORM] Byte-stream mode, the default.
[RMSGD] Message-discard mode.
[RMSGN] Message-nondiscard mode.
Read modes are described in read(). On failure, errno
4 Intergraph Corporation - 2/94
streamio(7) CLIX streamio(7)
is set to the following value:
[EINVAL] The value of arg is not one of the above legal values.
I_GRDOPT
Returns the current read mode setting in an int pointed to by the
arg parameter. Read modes are described in read(). On failure,
errno is set to the following value:
[EFAULT] The arg parameter 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 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. On failure, errno is set to the following value:
[EFAULT] The arg parameter 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.
The arg parameter points to a strfdinsert structure which contains
the following members:
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
int fildes;
int offset;
The len member in the ctlbuf strbuf structure (see putmsg()) must
be set to the size of a pointer plus the number of bytes of control
information to be sent with the message. The fildes member in the
strfdinsert structure specifies the file descriptor of the other
stream. The offset member, 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
member in the databuf strbuf structure must be set to the number of
bytes of data information to be sent with the message or 0 if no
2/94 - Intergraph Corporation 5
streamio(7) CLIX streamio(7)
data part is to be sent.
The flags member specifies the type of message to be created. A
nonpriority message is created if flags is set to 0, and a priority
message is created if flags is set to RS_HIPRI. For nonpriority
messages, I_FDINSERT blocks 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 nonpriority
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 nonpriority 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] The arg parameter points, or the buffer area specified
in ctlbuf or databuf is, outside the allocated address
space.
[EINVAL] One of the following occurred:
⊕ The fildes member in 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 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 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
6 Intergraph Corporation - 2/94
streamio(7) CLIX streamio(7)
buffer specified through ctlbuf is larger than the
maximum configured size of the control part of a
message.
I_FDINSERT also fails if an error message was received
by the stream head of the stream corresponding to fildes
in the strfdinsert structure. In this case, errno is
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 ioctl(), and returns 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
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()) 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 */
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 default, >0 = as specified) an I_STR
request waits for acknowledgement before timing out. The ic_len
member 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 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
2/94 - Intergraph Corporation 7
streamio(7) CLIX streamio(7)
to insufficient STREAMS memory resources.
[EFAULT] The arg parameter 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] The ic_len member 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 command also fails 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 fails 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(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] The arg parameter is not a valid, open file descriptor.
[EINVAL] The fildes parameter 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. The arg parameter is a
8 Intergraph Corporation - 2/94
streamio(7) CLIX streamio(7)
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];
The fd member is an integer file descriptor. The uid and gid
members are the user ID and group ID, respectively, of the sending
stream.
If O_NDELAY is not set (see open()), I_RECVFD blocks until a
message is present at the stream head. If O_NDELAY is set,
I_RECVFD fails 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 member 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] The arg parameter points outside the allocated address
space.
[EMFILE] NOFILES file descriptors are currently open.
[ENXIO] Hangup received on fildes.
The following 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.
2/94 - Intergraph Corporation 9
streamio(7) CLIX streamio(7)
[ETIME] Time out before acknowledgement 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] The value of arg is not a valid, open file descriptor.
[EINVAL] The fildes stream does not support multiplexing.
[EINVAL] The arg parameter 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 fails with errno
set to the value in the message.
I_UNLINK
Disconnects the two streams specified by fildes and arg. The
fildes parameter is the file descriptor of the stream connected to
the multiplexing driver. The fildes parameter must correspond to
the stream on which the ioctl() I_LINK command was issued to link
the stream below the multiplexing driver. The arg parameter is the
multiplexor ID number that was returned by the I_LINK. If arg is
-1, all streams 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.
[ENOSR] Unable to allocate storage to perform the I_UNLINK due
to insufficient STREAMS memory resources.
[EINVAL] The arg parameter is an invalid multiplexor ID number or
fildes is not the stream on which the I_LINK that
returned arg was performed.
10 Intergraph Corporation - 2/94
streamio(7) CLIX streamio(7)
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
acknowledgement message. For these cases, I_UNLINK fails with
errno set to the value in the message.
DIAGNOSTICS
Unless otherwise specified, the return value from ioctl() is 0 upon
success and -1 upon failure with errno set as indicated.
RELATED INFORMATION
Functions: close(2), fcntl(2), intro(2), ioctl(2), open(2), read(2),
getmsg(2), poll(2), putmsg(2), signal(2), sigset(2), write(2)
AT&T UNIX System V STREAMS Programmer's Guide, AT&T UNIX System V STREAMS
Primer
2/94 - Intergraph Corporation 11