streamio(7) Miscellaneous Information Manual streamio(7)
NAME
streamio - STREAMS ioctl commands
SYNOPSIS
fildes, command, arg
DESCRIPTION
STREAMS commands are a subset of the system calls which perform a variety 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
integer 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 following 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 message 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 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 structure which contains the following 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 con-
trol information to be sent with the message. fildes in the structure specifies the file descriptor of the other
stream. offset, which must be word-aligned, specifies the number of bytes beyond the beginning of the control buffer
where will store a pointer. This pointer will be the address of the read queue structure of the driver for the
streams corresponding 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 created. An ordinary (non-priority) message is created if flags is set to
0, a high priority message 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 struc-
ture. 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 connected to another driver. The stream designated by arg gets connected below the multi-
plexing 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 success, 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 mod-
ule names. If arg is not it should point to a structure 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 declaration is required.
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 return value
is greater than zero, this indicates that a zero-length message 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 message. 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 information 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 successful 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 connected to another driver. The stream designated by arg gets connected via a persistent
link below the multiplexing driver. requires the multiplexing 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
number (an identifier that may be used to disconnect the multiplexor, see on success and -1 on failure.
The can also fail if it is waiting for the multiplexing driver to acknowledge the link request and an error message,
or hangup message 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.
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 connected 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 discon-
nected. 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 mod-
ule.
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 containing the following
members:
fd is an integer file descriptor. and are the user ID and group ID, respectively, of the sending 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 mes-
sage 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 particular 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 combina-
tion, except where noted, of the following 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 send-
ing (or writing) 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) priority 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 several 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 following 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 downstream module or driver and is the number of seconds (-1 =infinite, 0 =
use default, >0 = as specified) an request will wait for acknowledgement 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 maxi-
mum 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 disconnected. As in this command requires the multiplexing 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:
o The stream referred to by fildes is linked below a multiplexing driver.
o The command parameter is not a valid value for the stream.
In addition, if any of the following conditions occur, the STREAMS commands 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 location 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 specified through does not fall within the range for the minimum and maxi-
mum sizes of packets for the top-most module on the stream.
[ERANGE] The value of the len field for the buffer specified 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 specified 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 descriptor.
[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 parameter 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 addi-
tion, 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 command.
[ENXIO] A hangup was received on the stream referred to by the fildes parameter.
[ETIME] A timeout occurred before an acknowledgement message 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 message 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 message 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 indicating 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 message 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 ALSO
close(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2), putmsg(2), read(2), write(2), signal(5).
streamio(7)