streamio(7)streamio(7)NAMEstreamio - STREAMS ioctl commands
SYNOPSIS
fildes, command, arg
DESCRIPTION
STREAMS commands are a subset of the system calls which perform a vari‐
ety of control functions on streams.
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 inte‐
ger or a pointer to a command-specific data structure. The command and
arg are interpreted by the stream head. Certain combinations of these
arguments may be passed to a module or driver in the stream.
Since these STREAMS commands are a subset of they are subject to the
errors described there. In addition to those errors, the call will
fail with set to 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 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 set to this value.
The following commands, with error values indicated, are applicable to
all STREAMS files:
Allows the user to see if the current message on the
stream head read queue is "marked" by some module
downstream. arg determines how the checking is
done when there are multiple marked messages on
the stream head read queue. It may take the fol‐
lowing values:
Checks if the message is marked.
Checks if the message is the last one that is
marked on the queue.
If both and are set, supersedes
The return value is 1 if the mark condition is
satisfied and 0 otherwise.
Checks if a certain band is writable.
arg is set to the priority band in question. The
return value is 0 if the priority band arg is
flow controlled, 1 if the band is writable, or −1
on error.
Check if the message of a given priority band exists on the
stream head read queue. This returns 1 if a mes‐
sage of a given priority exists, or −1 on error.
arg should be an integer containing the value of
the priority band in question.
Creates a message from user specified buffer(s), adds informa‐
tion 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 buf‐
fers, as described below.
arg points to a structure which contains the fol‐
lowing members:
The len field in the 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. fildes in the structure speci‐
fies the file descriptor of the other stream.
offset, which must be word-aligned, specifies the
number of bytes beyond the beginning of the con‐
trol buffer where will store a pointer. This
pointer will be the address of the read queue
structure of the driver for the streams corre‐
sponding to fildes in the structure. The len
field in the 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 cre‐
ated. An ordinary (non-priority) message is cre‐
ated if flags is set to 0, a high priority mes‐
sage is created if flags is set to For normal
messages, will block if the stream write queue is
full due to internal flow control conditions.
For high priority messages, does not block on
this condition. For normal messages, does not
block when the write queue is full and the is
set. Instead, it fails and sets to
also blocks, unless prevented by the lack of
internal resources, waiting for the availability
of message blocks, regardless of priority or
whether has been specified. No partial message
is sent.
can also fail if an error message was received by
the stream head of the stream corresponding to
fildes in the structure. In this case, will be
set to the value in the message.
Compares the names of all modules currently present on the
stream to the name specified in arg. The command
returns a value of 1 if the module is present and
a value of 0 (zero) if the module is not present.
This request flushes all input and/or output queues, depending
on the value of
arg. Valid arg values are:
Flush write and read queues.
Flush write queues.
Flush read queues.
If a pipe or FIFO does not have any modules
pushed, the read queue of the streams head on
either end is flushed depending on the value of
arg.
If is set and fildes is a pipe, the read queue
for that end of the pipe is flushed and the write
queue for the other end is flushed. If fildes is
a FIFO, both queues are flushed.
If is set and fildes is a pipe and the other end
of the pipe exists, the read queue for the other
end of the pipe is flushed and the write queue
for this end is flushed. If fildes is a FIFO,
both queues of the FIFO are flushed.
If is set, all read queues are flushed, that is
the read queue for the FIFO and the read queue of
boths ends of the pipe are flushed.
Correct flushing handling of a pipe or FIFO with
modules pushed is achieved via the module. This
module should be the first module pushed onto a
pipe so that it is at the midpoint of the pipe
itself.
Flushes a particular band of messages.
arg points to a structure that has the following
members:
The value of the bi_flag field can be or as
described for the command.
Returns the priority band of the first message on the
stream head read queue in the integer referenced
by arg.
Returns the close time delay in the long pointed by
arg.
Allows the user to set the time that the
stream head will delay when a stream is closing,
and there is data on the write queues. Before
closing each module and driver, the stream head
will delay for the specified amount of time to
allow the data to drain. If, after the delay,
data is still present, data will be flushed. arg
is a pointer to the number of milliseconds to
delay, rounded up to the nearest valid value on
the system. The default is fifteen seconds.
Returns the events for which the calling process has registered
to receive a
signal. Events are returned as in arg bitmask as
defined for the command.
Returns the current read mode setting in an
int pointed to by the argument arg. Read modes
are described in read(2).
Returns the current write mode setting, as described in
in the int that is pointed to by the argument
arg.
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 con‐
nected to another driver. The stream designated
by arg gets connected below the multiplexing
driver. 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 on suc‐
cess, and −1 on failure.
Allows the user to list all the module names on the
stream, up to and including the topmost driver
name. If arg is the return value is the number
of modules, including the driver, that are on the
stream pointed to by fildes. This allows the
user to allocate enough space for the module
names. If arg is not it should point to a struc‐
ture that has the following members:
The structure has the following member:
indicates the number of entries the user has
allocated in the array. On success, the return
value is 0, contains the list of module names,
and indicates the number of entries that have
been filled in.
Retrieves the name of the module located just below the
streams 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 bytes long. A declara‐
tion is required.
Counts the number of data bytes in data blocks in the first mes‐
sage 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 return value is greater
than zero, this indicates that a zero-length mes‐
sage is next on the queue.
Allows the user process to look (peek) at the contents
of the first message on the stream head read
queue. This is done without taking the message
off the queue. The operates the same way as the
function, except that it does not remove the mes‐
sage. The arg parameter points to a structure
(in the header file) with the following members:
The structure pointed to by and has the following
members:
The maxlen field of the structure must specify
the number of bytes of control or data informa‐
tion to be retrieved. The flags field can be set
to or 0 (zero). If this field is set to the
looks for a high priority message on the queue.
If the field is set to 0, the looks at the first
message on the queue.
The returns a 1 if a message was retrieved, and
returns a value of 0 (zero) if no message was
found; it does not wait for a message. Upon suc‐
cessful completion, specifies control information
in the control buffer, specifies data information
in the data buffer, and flags contains or 0
(zero).
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 con‐
nected to another driver. The stream designated
by arg gets connected via a persistent link below
the multiplexing driver. requires the multiplex‐
ing driver to send an acknowledgement message to
the stream head regarding the linking operation.
This call creates a persistent link which can
exist even if the file descriptor associated with
the upper stream to the multiplexing driver is
closed. This call returns a multiplexor ID num‐
ber (an identifier that may be used to disconnect
the multiplexor, see on success and −1 on fail‐
ure.
The can also fail if it is waiting for the multi‐
plexing driver to acknowledge the link request
and an error message, or hangup message is
received at the stream head for fildes. In addi‐
tion, an error can be returned in an or message.
When these occur, the fails with set to the value
in the message.
Removes the module just below the
stream head of the stream pointed to by fildes.
To remove a module from a pipe requires that the
module was pushed on the side it is being removed
from. arg should be 0 in an request.
Disconnects the two
streams specified by fildes and arg that are con‐
nected with a persistent link. fildes is the
file descriptor of the stream connected to the
multiplexing driver. arg is the multiplexor ID
number that was returned by when a stream was
linked below the multiplexing driver. If arg is
then all streams which are persistent links to
fildes are disconnected. As in this command
requires the multiplexing driver to acknowledge
the unlink.
Pushes the module whose name is pointed by
arg onto the top of the current stream, just
below the stream head. If the stream is a pipe,
the module will be inserted between the streams
heads of both ends of the pipe. It then calls
the open routine of the newly-pushed module.
Retrieves the file descriptor associated with the message sent
by an
over a stream pipe. arg is a pointer to a data
buffer large enough to hold a data structure con‐
taining the following members:
fd is an integer file descriptor. and are the
user ID and group ID, respectively, of the send‐
ing stream.
If is clear, will block until a message is
present at the stream head. If is set, will fail
with set to if no message is present at the
stream head.
If the message at the stream head is a message
sent by a 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 structure. The structure is copied into
the user data buffer pointed to by arg.
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 open file
descriptor.
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 of the stream
head at the other end of the stream pipe to which
it is connected.
Lets the user process set the time that the
stream head delays when the stream is closing and
the write queues contain data. The arg parameter
contains a pointer to the number of milliseconds
to delay, rounded up to the nearest legal value
on the system. The default time is 15 seconds.
Before STREAMS modules and drivers are closed,
the stream head delays for the specified amount
of time. This allows the data on the write
queues to drain. If data is still present on the
writes queues after the delay, the queues are
flushed.
Informs the stream head that the user wants the kernel to
issue the signal (see signal(2)) when a particu‐
lar event has occurred on the stream associated
with fildes. 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, except where noted, of the fol‐
lowing constants:
When used in conjunction with
is generated instead of when
a priority message reaches
the front of the stream head
read queue.
An message has reached the
stream head.
An message has reached the
stream head.
A high priority message is present on the
stream head read queue. This
is set even if the message is
of zero length.
Any message other than an
has arrived on a stream head
read queue. This event is
maintained for compatibility
with prior releases. This is
set even if the message is of
zero length.
A STREAMS signal message that
contains the signal has
reached the front of the
stream head read queue.
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 writ‐
ing) data downstream.
A priority band message (band > 0) has
arrived on a
stream head read queue. This
is set even if the message is
of zero-length.
An ordinary (non-priority) message has
arrived on a
stream head read queue. This
is set even if the message is
of zero-length.
A priority band greater than 0 of a queue
downstream exists and is writable.
This notifies the user that
there is room on the queue
for sending (or writing) pri‐
ority data downstream.
This event is the same as
A user process may choose to be signaled only of
high priority messages by setting arg bitmask to
the value
Processes that want to receive signals must
explicitly register to receive them using If sev‐
eral processes register to receive the 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
signals.
Sets the read mode (see
read(2)) using the value of the argument arg.
Valid arg values are:
Byte-stream mode (default).
Message-discard mode.
Message-nondiscard mode.
Setting both and is an error. and override
In addition, treatment of control messages by the
stream head may be changed by setting the follow‐
ing flags in arg:
Fail with EBADMSG if a control
message is at the front of
the stream head read queue.
This is the default behavior.
Deliver the control portion of a message as
data when a user issues
Discard the control portion of a message,
delivering any data
portion, when a user issues a
Constructs an internal
STREAMS message from the data pointed to by arg,
and sends that message downstream.
This mechanism is provided to send user requests
to downstream modules and drivers. It allows
information to be sent with the and will return
to the user any information sent upstream by the
downstream recipient. 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 set to ETIME.
At most, one can be active on a stream. Further
calls will block until the active completes at
the stream head. The default timeout intervals
for these requests is 15 seconds. The (see
open(2)) flags have no effect on this call.
To send requests downstream, arg must point to a
structure which contains the following members:
is the internal command intended for the down‐
stream module or driver and is the number of sec‐
onds (−1 =infinite, 0 = use default, >0 = as
specified) an request will wait for acknowledge‐
ment before timing out. The default timeout is
infinite. is the number of bytes in the data
argument and is a pointer to the data argument.
The 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 should be large enough to contain
the maximum amount of data that any module or
driver in the stream can return). The stream
head will convert the information pointed to by
structure to an internal command message and send
it downstream.
Sets the write mode using the value of the argument
arg. Legal bit settings for arg are:
Sends a zero-length message downstream when
a write of 0 bytes occurs.
To not send a zero-length
message when a write of 0
bytes occurs, this bit must
not be set in arg.
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 If arg is then
all streams which were linked to fildes are dis‐
connected. As in this command requires the mul‐
tiplexing driver to acknowledge the unlink.
RETURN VALUE
Unless specified differently for a command, the return value for a
STREAMS call is 0 (zero) on success and −1 (minus one) on failure.
ERRORS
A STREAMS command fails without performing the function and with set to
if:
· The stream referred to by fildes is linked below a multiplex‐
ing driver.
· The command parameter is not a valid value for the stream.
In addition, if any of the following conditions occur, the STREAMS com‐
mands return the corresponding value:
[EINVAL] arg has an illegal value.
[EINVAL] arg has an illegal value.
[EINVAL] arg has an illegal value.
[EINVAL] The fildes parameter in the structure is an
invalid open file descriptor.
[EINVAL] The size of the pointer plus offset exceeds the
value of the len field for the buffer specified
through ctlptr.
[EINVAL] offset does not specify a properly aligned loca‐
tion in the data buffer.
[EINVAL] flags contains an undefined value.
[EFAULT] arg points, or or is outside the allocated
address space.
[EAGAIN] The request failed because a non-priority message
was to be created, the option was set, and the
stream's write queue was full because of internal
flow control conditions.
[ENOSR] Buffers could not be allocated for the message
that was to be created due to insufficient
STREAMS memory resources.
[ENXIO] A hangup was received on the stream specified by
fildes in the call or on the stream specified by
fildes in the
[ERANGE] The value of the len field for the buffer speci‐
fied through does not fall within the range for
the minimum and maximum sizes of packets for the
top-most module on the stream.
[ERANGE] The value of the len field for the buffer speci‐
fied through is larger than the maximum allowable
size for the data part of a message.
[ERANGE] The value of the len field for the buffer speci‐
fied through is larger than the maximum allowable
size for the control part of a message.
The can also fail if an error (message was
received by the stream specified by the fildes
field in the structure. In this case, is set to
the error value in the error message.
[EINVAL] arg does not contain a valid module name.
[EFAULT] arg points outside the allocated address space.
[ENOSR] Could not allocate buffers for flush operation
because of a lack of STREAMS memory resources.
[EINVAL] The arg parameter is an invalid value.
[ENXIO] A hangup was received on fildes.
[EINVAL] The bi_pri parameter value exceeds the maximum
band, or the bi_flag parameter is not or
[ENODATA] No message exists on the stream head read queue.
[EINVAL] User process is not registered to receive the
signal.
[EFAULT] arg points outside the allocated address space.
[EFAULT] arg is pointing outside the allocated address
space.
[EAGAIN] Temporarily unable to allocate storage to perform
the linking operation.
[EBADF] The arg parameter not a valid open file descrip‐
tor.
[ENXIO] A hangup was received on fildes.
[EINVAL] The stream referred to by fildes does not support
multiplexing.
[EINVAL] The file referred to by arg is not a stream, or
the stream is already linked under a multiplexor.
[EINVAL] The link operation would cause a "cycle" in the
resulting multiplexing configuration. In other
words, the driver referred to by the arg parame‐
ter is linked into this configuration at multiple
places
[ENOSR] Not enough STREAMS memory resources to allocate
storage for this command.
[ETIME] Acknowledgement message not received at stream
head before timeout.
The can also fail if an or message is received at the stream
head for fildes before receiving the driver acknowledgement. In
addition, an error can be returned in an or message. When these
occur, the fails with set to the value in the message.
[EINVAL] is less than 1.
[EAGAIN] Could not allocate buffers.
[EINVAL] There are no modules in the stream.
[EFAULT] arg points outside the allocated address space.
[EFAULT] arg is pointing outside the allocated address
space.
[EINVAL] The flags parameter is an illegal value.
[EFAULT] arg points, or or is, outside the allocated
address space.
[EBADMSG] Message to be looked at is not valid for the com‐
mand.
[ENXIO] A hangup was received on the stream referred to
by the fildes parameter.
[ETIME] A timeout occurred before an acknowledgement mes‐
sage was received at the stream head.
[EAGAIN] Temporarily unable to allocate storage to perform
the linking operation.
[EBADF] arg is not a valid open file descriptor.
[EINVAL] The stream referred to by fildes does not support
multiplexing.
[EINVAL] The file referred to by arg is not a stream or is
already linked under a multiplexing driver.
[EINVAL] The link operation would cause a "cycle" in the
resulting multiplexing configuration. In other
words, the driver referred to by arg is linked
into the configuration at multiple places.
[EINVAL] There are not modules in the stream.
[ENXIO] Error value returned by the module being popped.
[ENXIO] A hangup was received on fildes.
[ENXIO] A hangup was received on fildes.
[ETIME] A timeout occurred before an acknowledgement mes‐
sage was received at the stream head.
[EAGAIN] Temporarily unable to allocate storage to perform
the linking operation.
[EINVAL] arg is an invalid multiplexor ID number.
[EINVAL] fildes is the file descriptor of a pipe.
An can also fail if it is waiting for the multiplexor to
acknowledge the unlink request and an error (message, or hangup
(is received at the stream head for fildes. In addition, an
error can be returned in an or message. When these occur, the
fails with set to the value in the message.
[EINVAL] An invalid module name was used.
[EFAULT] arg points outside the allocated address space.
[ENXIO] Error value returned by the module being pushed.
The push has failed.
[ENXIO] A hangup was received on fildes.
[EAGAIN] The option was set, and a message was not present
on the stream head read queue.
[EFAULT] The arg parameter points outside the allocated
address space.
[EBADMSG] The message present on the stream head read queue
did not contain a passed file descriptor.
[EMFILE] Too many open files. No more file descriptors
are permitted to be opened.
[ENXIO] A hangup was received on fildes.
[EAGAIN] The sending stream head could not allocate a mes‐
sage block for the file pointer.
[EAGAIN] The read queue of the receiving stream head was
full and could not accept the message.
[EBADF] The arg parameter is not a valid open file
descriptor.
[EINVAL] The fildes parameter does not refer to a stream.
[ENXIO] A hangup was received on fildes.
[EINVAL] arg has an illegal value.
[EINVAL] The user process is not registered to receive the
signal.
[EAGAIN] A data structure to store the signal request
could not be allocated.
[EINVAL] arg contains an illegal value.
[EINVAL] The field is less than 0 (zero) bytes or larger
than the maximum allowable size of the data part
of a message (
[EINVAL] The field is less than −1.
[EFAULT] arg points, or the buffer area specified by or
is, outside the allocated address space.
[ENOSR] Buffers could not be allocated for the request
because of a lack of STREAMS memory resources.
[ENXIO] A hangup was received on the stream referred to
by fildes.
[ETIME] The request timed out before an acknowledgement
was received.
The can also fail if the stream head receives a message indicat‐
ing an error (or a hangup (In addition, an error can be returned
in an or message. In these cases, the fails with set to the
error value in the message.
[EINVAL] The arg parameter is an illegal value.
[ENXIO] A hangup was received on fildes.
[ETIME] A timeout occurred before an acknowledgement mes‐
sage was received at the stream head.
[EINVAL] arg is an invalid multiplexor ID number, or
fildes is already linked under a multiplexing
driver.
An can also fail if it is waiting for the multiplexor to
acknowledge the unlink request and an error (message, or hangup
(is received at the stream head for fildes. In addition, an
error can be returned in or message. When this occurs, the
fails with set to the value in the message.
SEE ALSOclose(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2), putmsg(2),
read(2), write(2), signal(5).
streamio(7)
