Manual page for STREAMIO(4)
streamio - STREAMS ioctl commands
SYNOPSIS
#include <stropts.h>
int ioctl (fd, command, arg)
int fd, command;
DESCRIPTION
STREAMS
(see
intro.2
ioctl commands are a subset of
ioctl.2
commands that
perform a variety of control functions on
STREAMS.
The arguments
command
and
arg
are passed to the file designated by
fd
and are interpreted by the
streamhead.
Certain combinations of these arguments may be passed to a module or driver
in the stream.
fd
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
fd
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.
Subsequent system calls will fail with
errno
set to this value.
IOCTLS
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
streamhead.
It then calls the open routine of the newly-pushed module.
I_PUSH
will fail if one of the following occurs:
-
- EINVAL
-
The module name is invalid.
- EFAULT
-
arg
points outside the allocated address
space.
- ENXIO
-
The open routine of the new module failed.
- ENXIO
-
A hangup is received on the
stream
referred to by
fd.
- I_POP
-
Removes the module just below the
stream head
of the
stream
pointed to by
fd.
arg
should be 0 in an
I_POP
request.
I_POP
will fail if one of the following occurs:
-
- EINVAL
-
No module is present on
stream.
- ENXIO
-
A hangup is received on the
stream
referred to by
fd.
- I_LOOK
-
Retrieves the name of the module just below the
stream head
of the
stream pointed to by
fd,
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.
I_LOOK
will fail if one of the following occurs:
-
- EFAULT
-
arg
points outside the allocated address space of the
process.
- EINVAL
-
No module is present on
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.
I_FLUSH
will fail if one of the following occurs:
-
- EAGAIN
-
No buffers could be allocated for the flush message.
- EINVAL
-
The value of
arg
is invalid.
- ENXIO
-
A hangup is received on the
stream
referred to by
fd.
- I_SETSIG
-
Informs the
stream head
that the user wishes
the kernel to issue the
SIGPOLL
signal (see
sigvec.2
when a particular event has occurred on the
stream associated with
fd.
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.
I_SETSIG
will fail if one of the following occurs:
-
- EINVAL
-
The value of
arg
is invalid or
arg
is zero and the process is not registered to receive the
SIGPOLL
signal.
- EAGAIN
-
A data structure could not be allocated to store the signal request.
- 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.
I_GETSIG
will fail if one of the following occurs:
-
- EINVAL
-
The process is not registered to receive the
SIGPOLL
signal.
- EFAULT
-
arg
points outside the allocated address space of the
process.
- 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.
I_FIND
will fail if one of the following occurs:
-
- EFAULT
-
arg
points outside the allocated address space of the
process.
- EINVAL
-
arg
does not point to 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.
I_PEEK
will fail if one of the following occurs:
-
- EFAULT
-
arg
points, or the buffer area specified in
ctlbuf
or
databuf
is, outside the allocated address space of the
process.
- 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.2v
I_SRDOPT
will fail if one of the following occurs:
-
- 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.2v
I_GRDOPT
will fail if one of the following occurs:
-
- EFAULT
-
arg
points outside the allocated address space of the
process.
- 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.
I_NREAD
will fail if one of the following occurs:
-
- EFAULT
-
arg
points outside the allocated address space of the
process.
- 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;
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.
I_FDINSERT
will fail if one of the following occurs:
-
- 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 of the
process.
- EINVAL
-
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 pointed to by
flags.
- ENXIO
-
A hangup is received on the
stream
referred to by
fd.
- 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 permit a process to specify timeouts
and variable-sized amounts of data when sending an
ioctl
request 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 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.2v
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 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.
I_STR
will fail if one of the following occurs:
-
- EAGAIN
-
Buffers could not be allocated 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 of the process.
- 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
-
A hangup is received on the
stream referred to by
fd.
- 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
streamhead.
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
fd
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.
I_SENDFD
will fail if one of the following occurs:
-
- 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
-
fd
is not connected to a
stream
pipe.
- ENXIO
-
A hangup is received on the
stream referred to by
fd.
- 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.2v
I_RECVFD
will block
until a message is present at the
streamhead.
If
O_NDELAY
is set,
I_RECVFD
will fail with
errno
set to
EAGAIN
if no message is present at the
streamhead.
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.
I_RECVFD
will fail if one of the following occurs:
-
- 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 of the
process.
- EMFILE
-
Too many descriptors are active.
- ENXIO
-
A hangup is received on the
stream
referred to by
fd.
The following four commands are used for connecting and disconnecting
multiplexed
STREAMS
configurations.
- I_LINK
-
Connects two streams, where
fd
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
causes 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.
I_LINK
will fail if one of the following occurs:
-
- ENXIO
-
A hangup is received on the
stream referred to by
fd.
- ETIME
-
The
ioctl
timed out before an acknowledgement was received.
- EAGAIN
-
Storage could not be allocated to perform the
I_LINK.
- EBADF
-
arg
is not a valid, open file
descriptor.
- EINVAL
-
The
stream referred to by
fd
does not support multiplexing.
- 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 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
fd.
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
fd
and
arg.
fd
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
fd
are disconnected.
As in
I_LINK,
this command requires the multiplexing driver to
acknowledge the unlink.
I_UNLINK
will fail if one of the following occurs:
-
- ENXIO
-
A hangup is received on the
stream referred to by
fd.
- ETIME
-
The
ioctl
timed out before an acknowledgement was received.
- EAGAIN
-
Buffers could not be allocated for the acknowledgement message.
- EINVAL
-
The multiplexor
ID
number was invalid.
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
fd.
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.2v
fcntl.2v
getmsg.2
intro.2
ioctl.2
open.2v
poll.2
putmsg.2
read.2v
sigvec.2
write.2v
STREAMS Programmer's Guide
STREAMS Primer
Created by unroff & hp-tools.
© somebody (See intro for details). All Rights Reserved.
Last modified 11/5/97