'\"macro stdmacro
.if n .pH g7.streamio @(#)streamio	40.19 of 12/21/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} streamio 7 "" "\&"
.if \nX=1 .ds x} streamio 7 ""
.if \nX=2 .ds x} streamio 7 "" "\&"
.if \nX=3 .ds x} streamio "" "" "\&"
.TH \*(x}
.SH NAME
\f4streamio\f1 \- \s-1STREAMS\s0 ioctl commands
.SH SYNOPSIS
\f4#include <sys/types.h>
.br
\f4#include <stropts.h>\fP
.PP
\f4int ioctl (int fildes, int command, ... /* arg */);\fP
.SH DESCRIPTION
\s-1STREAMS\s0 [see \f4intro\fP(2)] \f4ioctl\fP commands are a subset of 
the \f4ioctl\fP(2) system calls which perform a variety of control functions on 
streams.
.PP
\f2fildes\f1 is an open file descriptor that refers to a stream.
\f2command\f1 determines the control function to be performed as described below.
\f2arg\f1 represents additional information that is needed by this command.
The type of \f2arg\f1 depends upon the command, but it is generally an integer
or a pointer to a \f2command\f1-specific data structure.
The \f2command\fP and \f2arg\fP are interpreted by the stream head. 
Certain combinations of these arguments may be passed to a module or driver
in the stream.
.P
Since these \s-1STREAMS\s0 commands are a subset of \f4ioctl\fP, they are subject 
to the errors described there.
In addition to those errors, the call will fail with \f4errno\f1 set to \f4EINVAL\fP,
without processing a control function,
if the stream referenced by \f2fildes\f1 is linked below a multiplexor, 
or if \f2command\f1 is not a valid value for a stream.
.P
Also, as described in \f4ioctl\fP, \s-1STREAMS\s0 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 \f4errno\f1 set to this value.
.SH COMMAND FUNCTIONS
The following \f4ioctl\fP commands, with error values indicated, are applicable to 
all \s-1STREAMS\s0 files:
.TP 13
\f4I_PUSH\fP
Pushes the module whose name is pointed to by \f2arg\f1 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 stream
heads of both ends of the pipe.
It then calls the open routine of the newly-pushed module.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EINVAL\fP
Invalid module name.
.TP
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.TP
\f4ENXIO\fP
Open routine of new module failed.
.TP
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.RE
.TP 13
\f4I_POP\fP
Removes the module just below the stream head of the stream pointed
to by \f2fildes\f1.
To remove a module from a pipe requires that the module was pushed on the side
it is being removed from.
\f2arg\f1 should be 0 in an \f4I_POP\fP request.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EINVAL\fP
No module present in the stream.
.TP
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.RE
.TP 13
\f4I_LOOK\fP
Retrieves the name of the module just below the stream head
of the stream pointed to by \f2fildes\f1,
and places it
in a null terminated character string pointed at by \f2arg\f1.
The buffer pointed to by \f2arg\f1 should be at least \f4FMNAMESZ\fP+1
bytes long.
An \f4(#include <sys/conf.h>)\fP declaration is required.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.TP
\f4EINVAL\fP
No module present in stream.
.RE
.TP 13
\f4I_FLUSH\fP
This request
flushes all input and/or output queues, depending on the value of
\f2arg\f1.
Legal \f2arg\f1 values are:
.RS 13
.TP 13
\f4FLUSHR\fP
Flush read queues.
.TP
\f4FLUSHW\fP
Flush write queues.
.TP
\f4FLUSHRW\fP
Flush read and write queues.
.RE
.IP
If a pipe or \s-1FIFO\s+1 does not have any modules pushed, the read queue of
the stream head on either end is flushed depending on the value of \f2arg\fP.
.IP
If \f4FLUSHR\fP is set and \f2fildes\fP 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 \f2fildes\fP is a \s-1FIFO\s0, both queues are flushed.
.IP
If \f4FLUSHW\fP is set and \f2fildes\f1 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 \f2fildes\fP is a \s-1FIFO\s+1, both queues of the \s-1FIFO\s0 are flushed.
.IP
If \f4FLUSHRW\fP is set, all read queues are flushed, that is, the read queue
for the \s-1FIFO\s+1 and the read queue on both ends of the pipe are flushed. 
.IP
Correct flush handling of a pipe or \s-1FIFO\s0 with modules pushed is
achieved via the \f4pipemod\fP module.
This module should be the first module pushed onto a pipe so that it is at the
midpoint of the pipe itself.
.IP
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4ENOSR\fP
Unable to allocate buffers for flush message due to insufficient \s-1STREAMS\s0 
memory resources.
.TP
\f4EINVAL\fP
Invalid \f2arg\f1 value.
.TP
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.RE
.TP 13
\f4I_FLUSHBAND\fP
Flushes a particular band of messages.
\f2arg\f1 points to a \f4bandinfo\fP structure that has the following members:
.sp .5
.ta .5i 1.75i
.nf
	\f4unsigned char   bi_pri;
	int             bi_flag;\fP
.fi
.sp .5
The \f4bi_flag\f1 field may be one of \f4FLUSHR, FLUSHW\fP, or
\f4FLUSHRW\fP as described earlier.
.TP 13
\f4I_SETSIG\fP
Informs the stream head that the user wishes
the kernel to issue the \f4SIGPOLL\fP signal [see \f4signal\fP(2)]
when a particular event has occurred on the stream associated
with \f2fildes\f1.
\f4I_SETSIG\fP supports an asynchronous processing capability in \s-1STREAMS\s0.
The value of \f2arg\f1 is a bitmask that specifies
the events for which the user should be signaled.
It is the bitwise-\s-1OR\s+1 of any combination of the following constants:
.RS 13
.TP 13 
\f4S_INPUT\fP
Any message other than an \f4M_PCPROTO\fP has arrived on a stream head
read queue.
This event is maintained for compatibility with prior \s-1UNIX\s+1 System \s+1V\s-1 
releases.
This is set even if the message is of zero length.
.TP
\f4S_RDNORM\fP
An ordinary (non-priority) message has arrived on a stream head
read queue.
This is set even if the message is of zero length.
.TP
\f4S_RDBAND\fP
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.
.TP
\f4S_HIPRI\fP
A high priority message is present on the stream head read queue.
This is set even if the message is of zero length.
.TP
\f4S_OUTPUT\fP
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.
.TP
\f4S_WRNORM\fP
This event is the same as \f4S_OUTPUT\fP.
.TP
\f4S_WRBAND\fP
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.
.TP
\f4S_MSG\fP
A \s-1STREAMS\s+1 signal message that contains the \f4SIGPOLL\fP signal has
reached
the front of the stream head read queue.
.TP
\f4S_ERROR\fP
An \f4M_ERROR\fP message has reached the stream head.
.TP
\f4S_HANGUP\fP
An \f4M_HANGUP\fP message has reached the stream head.
.TP
\f4S_BANDURG
When used in conjunction with \f4S_RDBAND, SIGURG\fP is generated instead
of \f4SIGPOLL\fP when a priority message reaches the front of the stream
head read queue.
.RE
.IP
A user process may choose to be signaled only of high priority messages by
setting the \f2arg\f1 bitmask to the value \f4S_HIPRI\fP.
.IP
Processes that wish to receive \f4SIGPOLL\fP signals must explicitly
register to receive them using \f4I_SETSIG\fP.
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.
.IP
If the value of \f2arg\f1 is zero,
the calling process will be unregistered and will not receive
further \f4SIGPOLL\fP signals.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EINVAL\fP
\f2arg\f1 value is invalid or
\f2arg\f1 is zero and process is not registered to receive
the \f4SIGPOLL\fP signal.
.TP
\f4EAGAIN\fP
Allocation of a data structure to store the signal request failed.
.RE
.TP 13
\f4I_GETSIG\fP
Returns the events for which the calling process is
currently registered to be sent a \f4SIGPOLL\fP signal.
The events are returned as a bitmask pointed to by \f2arg\f1,
where the events are those specified in the description of \f4I_SETSIG\fP
above.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EINVAL\fP
Process not registered to receive the \f4SIGPOLL\fP signal.
.TP
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.RE
.TP 13
\f4I_FIND\fP
Compares the names of all modules currently present in
the stream to the name pointed to by \f2arg\f1, and returns 1 if
the named module is present in the stream.
It returns 0 if the named module is not present.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.TP
\f4EINVAL\fP
\f2arg\f1 does not contain a valid module name.
.RE
.TP 13
\f4I_PEEK\fP
Allows a user to retrieve the information in the first
message on the stream head read queue without taking the
message off the queue.
\f4I_PEEK\fP is analogous to \f4getmsg\fP(2) except that it does not remove the
message from the queue.
\f2arg\f1 points to a \f4strpeek\fP structure
which contains the following members:
.sp .5
.ta .5i 1.75i
.nf
	\f4struct strbuf	ctlbuf;
	struct strbuf	databuf;
	long	flags;\fP
.fi
.sp .5
The \f4maxlen\f1 field in the \f4ctlbuf\fP and \f4databuf strbuf\fP structures 
[see \f4getmsg\fP(2)] must be set to
the number of bytes of control information and/or data information,
respectively, to retrieve.
\f4flags\f1 may be set to \f4RS_HIPRI\fP or 0.
If \f4RS_HIPRI\fP is set, \f4I_PEEK\fP will look for a 
high priority message on the stream head read queue.
Otherwise, \f4I_PEEK\fP will look for the first message on the
stream head read queue.
.IP
\f4I_PEEK\fP returns 1 if a message was retrieved,
and returns 0 if no message was found on the stream head read
queue.
It does not wait for a message to arrive.
On return, \f4ctlbuf\fP specifies information in the control buffer,
\f4databuf\fP specifies information in the data buffer, and
\f4flags\f1 contains the value \f4RS_HIPRI\f1 or 0.
On failure, \f4errno\f1 is set to the following value:
.RS 13
.TP 13
\f4EFAULT\fP
\f2arg\f1 points, or the buffer area specified in \f4ctlbuf\fP or \f4databuf\fP is, 
outside the allocated address space.
.TP 13
\f4EBADMSG\fP
Queued message to be read is not valid for \f4I_PEEK\fP
.TP 13
\f4EINVAL\fP
Illegal value for \f4flags\fP.
.RE
.TP 13
\f4I_SRDOPT\fP
Sets the read mode [see \f4read\fP(2)] using the value of the argument \f2arg\f1.
Legal \f2arg\f1 values are:
.RS 13
.TP 13
\f4RNORM\fP
Byte-stream mode, the default.
.TP
\f4RMSGD\fP
Message-discard mode.
.TP
\f4RMSGN\fP
Message-nondiscard mode.
.RE
.IP
In addition, treatment of control messages by the stream head may be
changed by setting the following flags in \f2arg\f1:
.RS 13
.TP 13
\f4RPROTNORM\fP
Fail \f4read\fP() with \f4EBADMSG\fP if a control message is at the front of
the stream head read queue.
This is the default behavior.
.TP
\f4RPROTDAT\fP
Deliver the control portion of a message as data when a user issues \f4read\fP().
.TP
\f4RPROTDIS\fP
Discard the control portion of a message, delivering any data portion, when a user
issues a \f4read\fP().
.RE
.IP
On failure, \f4errno\f1 is set to the following value:
.RS 13
.TP 13
\f4EINVAL\fP
\f2arg\f1 is not one of the above legal values. 
.RE
.TP 13
\f4I_GRDOPT\fP
Returns the current read mode setting in an \f4int\f1
pointed to by the argument \f2arg\f1.
Read modes are described in \f4read\fP(2).
On failure, \f4errno\f1 is set to the following value:
.RS 13
.TP 13
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.RE
.TP 13
\f4I_NREAD\fP
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 \f2arg\f1.
The return value for the command is the number of messages
on the stream head read queue.
For example, if zero is returned in \f2arg\f1, but the \f4ioctl\fP return value is 
greater than zero,
this indicates that a zero-length message is next on the queue.
On failure, \f4errno\f1 is set to the following value:
.RS 13
.TP 13
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.RE
.TP 13
\f4I_FDINSERT\fP
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.
.IP
\f2arg\f1 points to a \f4strfdinsert\fP structure
which contains the following members:
.sp .5
.ta .5i 1.75i
.nf
	\f4struct strbuf	ctlbuf;
	struct strbuf	databuf;
	long	flags;
	int	fildes;
	int	offset;\fP
.fi
.sp .5
The \f4len\f1 field in the \f4ctlbuf strbuf\fP structure [see
\f4putmsg\fP(2)] must be set to the size of a pointer plus 
the number of bytes of control information to be sent with the message.
\f2fildes\f1 in the \f4strfdinsert\fP structure specifies the file descriptor of 
the other stream.
\f4offset\f1, which must be word-aligned, specifies the number of bytes
beyond the beginning of the control buffer where \f4I_FDINSERT\fP will
store a pointer.
This pointer will be the address of the read queue structure of the driver for the 
stream corresponding to \f4fildes\f1 in the \f4strfdinsert\fP structure.
The \f4len\f1 field in the \f4databuf strbuf\fP 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.
.IP
\f4flags\f1 specifies the type of message to be created. 
An ordinary (non-priority) message is created if \f4flags\f1 is set to 0, 
a high priority message is created if \f4flags\f1 is set to \f4RS_HIPRI\fP.
For normal messages, \f4I_FDINSERT\fP will block if the stream write 
queue is full due to internal flow control conditions.
For high priority messages, \f4I_FDINSERT\fP does not block 
on this condition.
For normal messages, \f4I_FDINSERT\fP does not block when the
write queue is full and \f4O_NDELAY\fP or \f4O_NONBLOCK\fP is set.
Instead, it fails and sets \f4errno\f1 to \f4EAGAIN\fP.
.IP
\f4I_FDINSERT\fP also blocks, unless prevented by lack of internal resources,
waiting for the availability of message blocks,
regardless of priority or whether \f4O_NDELAY\fP or \f4O_NONBLOCK\fP has been 
specified.
No partial message is sent.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EAGAIN\fP
A non-priority message was specified, the \f4O_NDELAY\fP or \f4O_NONBLOCK\fP 
flag is set,
and the  stream write queue is full due to internal flow control conditions.
.TP
\f4ENOSR\fP
Buffers could not be allocated for the message that was to be created
due to insufficient \s-1STREAMS\s0 memory resources.
.TP
\f4EFAULT\fP
\f2arg\f1 points, or the buffer area specified in \f4ctlbuf\fP or \f4databuf\fP is, 
outside the allocated address space.
.TP
\f4EINVAL\fP
One of the following:
\f4fildes\f1 in the \f4strfdinsert\fP structure
is not a valid, open stream file descriptor;
the size of a pointer plus \f4offset\f1 is
greater than the \f4len\f1 field for the buffer specified through \f4ctlptr\fP;
\f4offset\f1 does not specify a properly-aligned location in the data buffer;
an undefined value is stored in \f4flags\f1.
.TP
\f4ENXIO\fP
Hangup received on \f4fildes\f1 of the \f4ioctl\fP call or \f4fildes\f1 in the 
\f4strfdinsert\fP structure.
.TP
\f4ERANGE\fP
The \f4len\f1 field for the buffer specified through \f4databuf\fP does
not fall within the range specified by the maximum and minimum packet
sizes of the topmost stream module, or the \f4len\f1 field for
the buffer specified through \f4databuf\fP is larger than the maximum
configured size of the data part of a message, or the \f4len\f1 field
for the buffer specified through \f4ctlbuf\fP is larger than the
maximum configured size of the control part of a message.
.RE
.IP
\f4I_FDINSERT\fP can also fail if an error message was
received by the stream head of the stream corresponding to \f4fildes\f1 
in the \f4strfdinsert\fP structure.
In this case, \f4errno\f1 will be set to the value in the message.
.TP  13
\f4I_STR\fP
Constructs an internal \s-1STREAMS\s0 ioctl message from the data
pointed to by \f2arg\f1, and sends that message downstream.
.IP
This mechanism is provided to send user \f4ioctl\fP requests to downstream
modules and drivers.
It allows information to be sent with the \f4ioctl\fP, and
will return to the user any information sent upstream
by the downstream recipient.
\f4I_STR\fP 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 \f4errno\f1 set to \f4ETIME\fP.
.IP
At most, one \f4I_STR\fP can be active on a stream.
Further \f4I_STR\fP calls will block until the active \f4I_STR\fP completes at 
the stream head.
The default timeout interval for these requests is 15 seconds.
The \f4O_NDELAY\fP and \f4O_NONBLOCK\fP [see \f4open\fP(2)] flags have no effect 
on this call.
.IP
To send requests downstream, \f2arg\f1 must point to a \f4strioctl\fP structure
which contains the following members:
.sp .5
.ta .5i 1i 2i
.nf
	\f4int	ic_cmd;	
	int	ic_timout;
	int	ic_len;
	char	*ic_dp;\fP
.fi
.IP
\f4ic_cmd\f1 is the internal \f4ioctl\fP command intended for a downstream
module or driver and \f4ic_timout\f1 is the number of seconds (-1 =
infinite, 0 = use default, >0 = as specified) an \f4I_STR\fP
request will wait for acknowledgement before timing out.
The default timeout is infinite.
\f4ic_len\f1 is the number of bytes in the data argument and
\f4ic_dp\f1 is a pointer to the data argument.
The \f4ic_len\f1 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 \f4ic_dp\f1 
should be large enough to contain the maximum amount of data that any module or 
the driver in the stream can return).
.IP
The stream head will convert the information pointed to by the
\f4strioctl\fP structure to an internal \f4ioctl\fP command message and send it 
downstream.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4ENOSR\fP
Unable to allocate buffers for the \f4ioctl\fP message
due to insufficient \s-1STREAMS\s0 memory resources.
.TP
\f4EFAULT\fP
\f2arg\f1 points, or the buffer area specified by \f4ic_dp\f1 and \f4ic_len\f1 
(separately for data sent and data returned) is, outside the allocated address space.
.TP
\f4EINVAL\fP
\f4ic_len\f1 is less than 0 or \f4ic_len\f1 is larger than the maximum configured 
size of the data part of a message or \f4ic_timout\f1 is less than -1.
.TP
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.TP
\f4ETIME\fP
A downstream \f4ioctl\fP timed out before acknowledgement was received.
.RE
.IP
An \f4I_STR\fP can also fail while waiting for an acknowledgement if a message 
indicating an error or a hangup is received at the stream head.
In addition, an error code can be returned in the positive or negative 
acknowledgement message, in the event the ioctl command sent downstream fails.
For these cases, \f4I_STR\fP will fail with \f4errno\f1 set to the value in the 
message.
.TP 13
\f4I_SWROPT\fP
Sets the write mode using the value of the argument \f2arg\f1.
Legal bit settings for \f2arg\f1 are:
.RS 13
.TP 13
\f4SNDZERO\fP
Send a zero-length message downstream when a write of 0 bytes occurs.
.PP
To not send a zero-length message when a write of 0 bytes occurs, this bit must not
be set in \f2arg\f1.
.PP
On failure, \f4errno\f1 may be set to the following value:
.TP 13
\f4EINVAL\fP
\f2arg\f1 is the the above legal value.
.RE
.TP 13
\f4I_GWROPT\fP
Returns the current write mode setting, as described above, in the \f4int\f1 that
is pointed to by the argument \f2arg\f1.
.TP 13
\f4I_SENDFD\fP
Requests the stream associated with \f2fildes\f1 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 \f2arg\f1, which must be an open file descriptor.
.IP
\f4I_SENDFD\fP converts \f2arg\f1 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 \f4intro\fP(2)] of the 
stream head at the other end of the stream pipe to which it is connected.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EAGAIN\fP
The sending stream is unable to allocate a message block to contain the file pointer.
.TP
\f4EAGAIN\fP
The read queue of the receiving stream head is full and
cannot accept the message sent by \f4I_SENDFD\fP.
.TP
\f4EBADF\fP
\f2arg\f1 is not a valid, open file descriptor.
.TP
\f4EINVAL\fP
\f2fildes\f1 is not connected to a stream pipe.
.TP
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.RE
.TP 13
\f4I_RECVFD\fP
Retrieves the file descriptor associated with the message sent by an \f4I_SENDFD\fP 
\f4ioctl\fP over a stream pipe.
\f2arg\f1 is a pointer to a data buffer large enough
to hold an \f4strrecvfd\fP data structure containing the following members:
.sp .5
.nf
	\f4int fd;
	uid_t uid;
	gid_t gid;
	char fill[8];\fP
.fi
.IP
\f4fd\f1 is an integer file descriptor.
\f4uid\f1 and \f4gid\f1 are the user id and group id, respectively, 
of the sending stream.
.IP
If \f4O_NDELAY\fP and \f4O_NONBLOCK\fP are clear [see \f4open\fP(2)], \f4I_RECVFD\fP 
will block until a message is present at the stream head.
If \f4O_NDELAY\fP or \f4O_NONBLOCK\fP is set, \f4I_RECVFD\fP will fail with 
\f4errno\f1 set to \f4EAGAIN\fP if no message is present at the stream head.
.IP
If the message at the stream head is a message sent by an \f4I_SENDFD\fP,
a new user file descriptor is allocated for the file pointer contained in the message.
The new file descriptor is placed in the \f4fd\f1 field of the \f4strrecvfd\fP 
structure.
The structure is copied into the user data buffer pointed to by \f2arg\f1.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EAGAIN\fP
A message is not present at the stream head
read queue, and the \f4O_NDELAY\fP or \f4O_NONBLOCK\fP flag is set. 
.TP
\f4EBADMSG\fP
The message at the stream head read queue is not
a message containing a passed file descriptor.
.TP
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.TP 
\f4EMFILE\fP
\f4NOFILES\fP file descriptors are currently open.
.TP 
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.TP
\f4EOVERFLOW\fP
\f2uid\f1 or \f2gid\f1 is too large to be stored in the structure
pointed to by \f2arg\f1.
.RE
.TP 13
\f4I_LIST\fP
Allows the user to list all the module names on the stream, up to and 
including the topmost driver name.
If \f2arg\f1 is \f4NULL\fP, the return value is the number of modules, including
the driver, that are on the stream pointed to by \f2fildes\f1.
This allows the user to allocate enough space for the module names.
If \f2arg\f1 is non-\f4NULL\fP, it should point to an \f4str_list\fP structure
that has the following members:
.sp .5
.nf
	\f4int sl_nmods;
	struct str_mlist   *sl_modlist;\fP
.fi
.sp .5
The \f4str_mlist\fP structure has the following member:
.sp .5
.nf
	\f4char l_name[FMNAMESZ+1];\fP
.fi
.IP
\f4sl_nmods\f1 indicates the number of entries the user has allocated in the
array and on return, \f4sl_modlist\f1 contains the list of module names.
The return value indicates the number of entries that have been filled in.
On failure, \f4errno\f1 may be set to one of the following values:
.RS 13
.TP 13 
\f4EINVAL\fP
The \f4sl_nmods\f1 member is less than 1.
.TP
\f4EAGAIN\fP
Unable to allocate buffers
.RE
.TP 13
\f4I_ATMARK\fP
Allows the user to see if the current message on the stream head read queue
is "marked" by some module downstream.
\f2arg\f1 determines how the checking is done when there may be multiple marked
messages on the stream head read queue.
It may take the following values:
.RS 13
.TP 13 
\f4ANYMARK\fP
Check if the message is marked.
.TP
\f4LASTMARK\fP
Check if the message is the last one marked on the queue.
.PP
The return value is 1 if the mark condition is satisfied and 0 otherwise.
On failure, \f4errno\f1 may be set to the following value:
.TP 13
\f4EINVAL\fP
Invalid \f2arg\f1 value.
.RE
.TP 13
\f4I_CKBAND\fP
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.
\f2arg\f1 should be an integer containing the value of the priority
band in question.
On failure, \f4errno\f1 may be set to the following value:
.RS 13
.TP 13 
\f4EINVAL\fP
Invalid \f2arg\f1 value.
.RE
.TP 13
\f4I_GETBAND\fP
Returns the priority band of the first message on the stream head
read queue in the integer referenced by \f2arg\f1.
On failure, \f4errno\f1 may be set to the following value:
.RS 13
.TP 13 
\f4ENODATA\fP
No message on the stream head read queue.
.RE
.TP 13
\f4I_CANPUT\fP
Check if a certain band is writable.
\f2arg\f1 is set to the priority band in question.
The return value is 0 if the priority band \f2arg\f1 is flow controlled, 1 if the
band is writable, or -1 on error.
On failure, \f4errno\f1 may be set to the following value:
.RS 13
.TP 13 
\f4EINVAL\fP
Invalid \f2arg\f1 value.
.RE
.TP 13
\f4I_SETCLTIME\fP
Allows the user to set the time the stream head will delay when a stream
is closing and there are 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 are still present, data will be flushed.
\f2arg\f1 is a pointer to the number of milliseconds to delay, rounded up to the 
nearest legal value on the system.
The default is fifteen seconds.
On failure, \f4errno\f1 may be set to the following value:
.RS 13
.TP 13
\f4EINVAL\fP
Invalid \f2arg\f1 value.
.RE
.TP 13
\f4I_GETCLTIME\fP
Returns the close time delay in the long pointed by \f2arg\f1.
.PP
.PP
The following four commands are used for connecting and disconnecting
multiplexed \s-1STREAMS\s0 configurations.
.TP 13
\f4I_LINK\fP
Connects two streams, where \f2fildes\f1 is the file descriptor of the 
stream connected to the multiplexing driver, and \f2arg\f1 is the file 
descriptor of the stream connected to another driver.
The stream designated by \f2arg\f1 gets connected below the multiplexing driver.
\f4I_LINK\fP
requires the multiplexing driver to send an acknowledgement message to the stream 
head regarding the linking operation.
This call returns a multiplexor \s-1ID\s+1 number (an identifier used to disconnect 
the multiplexor, see \f4I_UNLINK\fP) on success, and a -1 on failure.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.TP
\f4ETIME\fP
Time out before acknowledgement message was received at stream head.
.TP
\f4EAGAIN\fP
Temporarily unable to allocate storage to perform the \f4I_LINK\fP.
.TP
\f4ENOSR\fP
Unable to allocate storage to perform the \f4I_LINK\fP
due to insufficient \s-1STREAMS\s0 memory resources.
.TP
\f4EBADF\fP
\f2arg\f1 is not a valid, open file descriptor.
.TP
\f4EINVAL\fP
\f2fildes\f1 stream does not support multiplexing.
.TP
\f4EINVAL\fP
\f2arg\f1 is not a stream, or is already linked under a multiplexor.
.TP
\f4EINVAL\fP
The specified link operation
would cause a "cycle" in the resulting configuration;
that is, if a given driver is linked into a multiplexing
configuration in more than one place.
.TP
\f4EINVAL\fP
\f2fildes\f1 is the file descriptor of a pipe or \s-1FIFO\s0.
.RE
.IP
An \f4I_LINK\fP 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 \f2fildes\f1.
In addition, an error code can be returned in the positive or negative 
acknowledgement message.
For these cases, \f4I_LINK\fP will fail with \f4errno\f1 set to the value in the 
message.
.TP 13
\f4I_UNLINK\fP
Disconnects the two streams specified by \f2fildes\f1 and \f2arg\f1.
\f2fildes\f1 is the file descriptor of the stream connected to the
multiplexing driver.
\f2arg\f1 is the multiplexor \s-1ID\s+1 number that was returned by the
\f4I_LINK\fP.
If \f2arg\f1 is -1, then all Streams which were linked to \f2fildes\f1
are disconnected.
As in \f4I_LINK\fP, this command requires the multiplexing driver to
acknowledge the unlink.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.TP
\f4ETIME\fP
Time out before acknowledgement message was received at stream head.
.TP
\f4ENOSR\fP
Unable to allocate storage to perform the \f4I_UNLINK\fP
due to insufficient \s-1STREAMS\s0 memory resources.
.TP
\f4EINVAL\fP
\f2arg\f1 is an invalid multiplexor \s-1ID\s+1 number or \f2fildes\f1 is not the 
stream on which the \f4\I_LINK\fP that returned \f2arg\f1 was performed.
.TP
\f4EINVAL\fP
\f2fildes\f1 is the file descriptor of a pipe or \s-1FIFO\fP.
.RE
.IP
An \f4I_UNLINK\fP 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 \f2fildes\f1.
In addition, an error code can be returned in the positive or negative
acknowledgement message.
For these cases, \f4I_UNLINK\fP will fail with \f4errno\f1 set to the
value in the message.
.TP 13
\f4I_PLINK\fP
Connects two streams, where \f2fildes\f1 is the file descriptor of the
stream connected to the multiplexing driver, and \f2arg\f1 is the file
descriptor of the stream connected to another driver.
The stream designated by \f2arg\f1 gets connected via a persistent link
below the multiplexing driver.
\f4I_PLINK\fP 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
\f2fildes\f1 associated with the upper stream to the multiplexing driver
is closed.
This call returns a multiplexor \s-1ID\s+1 number (an identifier that may be used to
disconnect the multiplexor, see \f4I_PUNLINK\fP) on success, and a -1 on
failure.
On failure, \f4errno\f1 may be set to one of the following values:
.RS 13
.TP 13
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.TP
\f4ETIME\fP
Time out before acknowledgement message was received at the stream head.
.TP
\f4EAGAIN\fP
Unable to allocate \s-1STREAMS\s+1 storage to perform the \f4I_PLINK\fP.
.TP
\f4EBADF\fP
\f2arg\f1 is not a valid, open file descriptor.
.TP
\f4EINVAL\fP
\f2fildes\f1 does not support multiplexing.
.TP
\f4EINVAL\fP
\f2arg\f1 is not a stream or is already linked under a multiplexor.
.TP
\f4EINVAL\fP
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.
.TP
\f4EINVAL\fP
\f2fildes\fP is the file descriptor of a pipe or \s-1FIFO\fP.
.RE
.IP
An \f4I_PLINK\fP can also fail while waiting for the multiplexing driver to 
acknowledge the link request, if a message indicating an error on a hangup is 
received at the stream head of \f2fildes\f1.
In addition, an error code can be returned in the positive or negative
acknowledgement message.
For these cases, \f4I_PLINK\fP will fail with \f4errno\f1 set to the value
in the message.
.TP 13
\f4I_PUNLINK\fP
Disconnects the two streams specified by \f2fildes\f1 and \f2arg\f1
that are connected with a persistent link.
\f2fildes\f1 is the file descriptor of the stream connected to the
multiplexing driver.
\f2arg\f1 is the multiplexor \s-1ID\s+1 number that was returned by \f4I_PLINK\fP 
when a stream was linked below the multiplexing driver.
If \f2arg\f1 is \f4MUXID_ALL\fP then all streams which are persistent
links to \f2fildes\f1 are disconnected.
As in \f4I_PLINK\fP, this command requires the multiplexing driver to
acknowledge the unlink.
On failure, \f4errno\f1 may be set to one of the following values:
.RS 13
.TP 13
\f4ENXIO\fP
Hangup received on \f2fildes\f1.
.TP
\f4ETIME\fP
Time out before acknowledgement message was received at the stream head.
.TP
\f4EAGAIN\fP
Unable to allocate buffers for the acknowledgement message.
.TP
\f4EINVAL\fP
Invalid multiplexor \s-1ID\s+1 number.
.TP
\f4EINVAL\fP
\f2fildes\fP is the file descriptor of a pipe or \s-1FIFO\s0.
.RE
.IP
An \f4I_PUNLINK\fP 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 \f2fildes\f1.
In addition, an error code can be returned in the positive or negative
acknowledgement message.
For these cases, \f4I_PUNLINK\fP will fail with \f4errno\f1 set to the value
in the message.
.SH "SEE ALSO"
\f4close\fP(2), \f4fcntl\fP(2), \f4getmsg\fP(2), \f4intro\fP(2), \f4ioctl\fP(2), 
\f4open\fP(2), \f4poll\fP(2), \f4putmsg\fP(2), \f4read\fP(2), \f4signal\fP(2), 
\f4write\fP(2), \f4signal\fP(5).
.br
\f2Programmer's Guide: \s-1STREAMS\s0\f1.
.SH DIAGNOSTICS
Unless specified otherwise above, the return value from \f4ioctl\fP is
0 upon success and -1 upon failure with \f4errno\f1 set as indicated.
.Ee
