.\" Copyright (c) 2017, Joyent, Inc.
.\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.Dd March 13, 2022
.Dt STREAMIO 4I
.Os
.Sh NAME
.Nm streamio
.Nd STREAMS ioctl commands
.Sh SYNOPSIS
.In sys/types.h
.In stropts.h
.In sys/conf.h
.Ft int
.Fo ioctl
.Fa "int fildes"
.Fa "int command"
.Fa "\&... /*arg*/"
.Fc
.Sh DESCRIPTION
STREAMS (see
.Xr Intro 3 )
.Fn ioctl
commands are a subset of the
.Xr ioctl 2
commands and perform a variety of control functions on streams.
.Pp
The
.Fa fildes
argument is an open file descriptor that refers to a stream.
The
.Fa command
argument determines the control function to be performed as
described below.
The
.Fa arg
argument represents additional information that
is needed by this command.
The type of
.Fa arg
depends upon the command, but
it is generally an integer or a pointer to a command-specific data structure.
The
.Fa command
and
.Fa arg
arguments are interpreted by the STREAM head.
Certain combinations of these arguments may be passed to a module or driver in
the stream.
.Pp
Since these STREAMS commands are
.Sy ioctls ,
they are subject to the errors described in
.Xr ioctl 2 .
In addition to those errors, the call will fail
with
.Va errno
set to
.Er EINVAL ,
without processing a control function, if the STREAM referenced by
.Fa fildes
is linked below a multiplexor, or if
.Fa command
is not a valid value for a stream.
.Pp
Also, as described in
.Xr ioctl 2 ,
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 calls to fail with
.Va errno
set to this value.
.Sh IOCTLS
The following
.Fn ioctl
commands, with error values indicated, are applicable to all STREAMS files:
.Bl -tag -width I_SETCLTIME
.It Dv I_PUSH
Pushes the module whose name is pointed to by
.Va 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 stream heads of both ends of the pipe.
It then calls the open routine of the newly-pushed module.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width ENOTSUP
.It Er EINVAL
Invalid module name.
.It Er EFAULT
.Va arg
points outside the allocated address space.
.It Er ENXIO
Open routine of new module failed.
.It Er ENXIO
Hangup received on
.Va fildes .
.It Er ENOTSUP
Pushing a module is not supported on this stream.
.El
.It Dv I_POP
Removes the module just below the STREAM head of the STREAM pointed to by
.Fa fildes .
To remove a module from a pipe requires that the module was
pushed on the side it is being removed from.
.Fa arg
should be
.Sy 0
in an
.Dv I_POP
request.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width ENOTSUP
.It Er EINVAL
No module present in the stream.
.It Er ENXIO
Hangup received on
.Fa fildes .
.It Er EPERM
Attempt to pop through an anchor by an unprivileged process.
.It Er ENOTSUP
Removal is not supported.
.El
.It Dv I_ANCHOR
Positions the stream anchor to be at the stream's module directly below the
stream head.
Once this has been done, only a privileged process may pop modules
below the anchor on the stream.
.Va arg
must be
.Sy 0
in an
.Dv I_ANCHOR
request.
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EINVAL
.It Er EINVAL
Request to put an anchor on a pipe.
.El
.It Dv I_LOOK
Retrieves the name of the module just below the stream head of the stream
pointed to by
.Fa fildes ,
and places it in a null terminated character string
pointed at by
.Fa arg .
The buffer pointed to by
.Fa arg
should be at least
.Dv FMNAMESZ Ns +1
bytes long.
This requires the declaration
.Ql "#include <sys/conf.h>" .
On failure,
.Dv errno
is set to one of the following values:
.Bl -tag -width EFAULT
.It Er EFAULT
.Fa arg
points outside the allocated address space.
.It Er EINVAL
No module present in stream.
.El
.It Dv I_FLUSH
This request flushes all input and/or output queues, depending on the value of
.Fa arg .
Legal
.Fa arg
values are:
.Bl -tag -width FLUSHRW
.It Dv FLUSHR
Flush read queues.
.It Dv FLUSHW
Flush write queues.
.It Dv FLUSHRW
Flush read and write queues.
.El
.Pp
If a pipe or FIFO does not have any modules pushed, the read queue of the
stream head on either end is flushed depending on the value of
.Fa arg .
.Pp
If
.Dv FLUSHR
is set and
.Fa 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
.Fa fildes
is a FIFO, both queues are flushed.
.Pp
If
.Dv FLUSHW
is set and
.Fa 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
.Fa fildes
is a FIFO, both queues of the
FIFO are flushed.
.Pp
If
.Dv FLUSHRW
is set, all read queues are flushed, that is, the read queue
for the FIFO and the read queue on both ends of the pipe are flushed.
.Pp
Correct flush handling of a pipe or FIFO with modules pushed is achieved via
the
.Sy pipemod
module.
This module should be the first module pushed onto a
pipe so that it is at the midpoint of the pipe itself.
.Pp
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EINVAL
.It Er ENOSR
Unable to allocate buffers for flush message due to insufficient stream memory
resources.
.It Er EINVAL
Invalid
.Va arg
value.
.It Er ENXIO
Hangup received on
.Fa fildes .
.El
.It Dv I_FLUSHBAND
Flushes a particular band of messages.
.Fa arg
points to a
.Vt bandinfo
structure that has the following members:
.Bd -literal -offset 2n
unsigned char bi_pri;
int bi_flag;
.Ed
.Pp
The
.Fa bi_flag
field may be one of
.Dv FLUSHR ,
.Dv FLUSHW ,
or
.Dv FLUSHRW
as described earlier.
.It Dv I_SETSIG
Informs the stream head that the user wishes the kernel to issue the
.Dv SIGPOLL
signal (see
.Xr signal 3C )
when a particular event has occurred on the stream associated with
.Fa fildes .
.Dv I_SETSIG
supports an asynchronous processing capability in streams.
The value of
.Fa 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:
.Bl -tag -width S_BANDURG
.It Dv S_INPUT
Any message other than an
.Dv M_PCPROTO
has arrived on a stream head read queue.
This event is maintained for compatibility with previous releases.
This event is triggered even if the message is of zero length.
.It Dv S_RDNORM
An ordinary (non-priority) message has arrived on a stream head read queue.
This event is triggered even if the message is of zero length.
.It Dv S_RDBAND
A priority band message (band > 0) has arrived on a stream head read queue.
This event is triggered even if the message is of zero length.
.It Dv S_HIPRI
A high priority message is present on the stream head read queue.
This event is triggered even if the message is of zero length.
.It Dv 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.
.It Dv S_WRNORM
This event is the same as
.Dv S_OUTPUT .
.It Dv S_WRBAND
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.
.It Dv S_MSG
A STREAMS signal message that contains the
.Dv SIGPOLL
signal has reached the
front of the stream head read queue.
.It Dv S_ERROR
An
.Dv M_ERROR
message has reached the stream head.
.It Dv S_HANGUP
An
.Dv M_HANGUP
message has reached the stream head.
.It Dv S_BANDURG
When used in conjunction with
.Dv S_RDBAND ,
.Dv SIGURG
is generated instead of
.Dv SIGPOLL
when a priority message reaches the front of the stream head
read queue.
.El
.Pp
A user process may choose to be signaled only of high priority messages by
setting the
.Fa arg
bitmask to the value
.Dv S_HIPRI .
.Pp
Processes that wish to receive
.Dv SIGPOLL
signals must explicitly register
to receive them using
.Dv 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.
.Pp
If the value of
.Fa arg
is zero, the calling process will be unregistered and
will not receive further
.Dv SIGPOLL
signals.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EINVAL
.It Er EINVAL
.Fa arg
value is invalid or
.Fa arg
is zero and process is not registered to receive the
.Dv SIGPOLL
signal.
.It Er EAGAIN
Allocation of a data structure to store the signal request failed.
.El
.It Dv I_GETSIG
Returns the events for which the calling process is currently registered to be
sent a
.Dv SIGPOLL
signal.
The events are returned as a bitmask pointed to by
.Va arg ,
where the events are those specified in the description of
.Dv I_SETSIG
above.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EINVAL
.It Er EINVAL
Process not registered to receive the
.Dv SIGPOLL
signal.
.It Er EFAULT
.Fa arg
points outside the allocated address space.
.El
.It Dv I_FIND
Compares the names of all modules currently present in the stream to the name
pointed to by
.Fa arg ,
and returns 1 if the named module is present in the stream.
It returns 0 if the named module is not present.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EINVAL
.It Er EFAULT
.Fa arg
points outside the allocated address space.
.It Er EINVAL
.Fa arg
does not contain a valid module name.
.El
.It Dv I_PEEK
Allows a user to retrieve the information in the first message on the stream
head read queue without taking the message off the queue.
.Dv I_PEEK
is analogous to
.Xr getmsg 2
except that it does not remove the message from the queue.
.Fa arg
points to a
.Vt strpeek
structure, which contains the following members:
.Bd -literal -offset 2n
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
.Ed
.Pp
The
.Ft maxlen
field in the
.Vt ctlbuf
and
.Vt databuf
.Vt strbuf
structures (see
.Xr getmsg 2 )
must be set to the number of bytes of control
information and/or data information, respectively, to retrieve.
.Fa flags
may be set to
.Dv RS_HIPRI
or
.Sy 0 .
If
.Dv RS_HIPRI
is set,
.Dv I_PEEK
will look for a high priority message on the stream head read queue.
Otherwise,
.Dv I_PEEK
will look for the first message on the stream head read queue.
.Pp
.Dv I_PEEK
returns
.Sy 1
if a message was retrieved, and returns
.Sy 0
if no message was found on the stream head read queue.
It does not wait for a message to arrive.
On return,
.Vt ctlbuf
specifies information in the control buffer,
.Vt databuf
specifies information in the data buffer, and
.Fa flags
contains the value
.Dv RS_HIPRI
or
.Sy 0 .
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EBADMSG
.It Er EFAULT
.Fa arg
points, or the buffer area specified in
.Vt ctlbuf
or
.Vt databuf
is, outside the allocated address space.
.It Er EBADMSG
Queued message to be read is not valid for
.Dv I_PEEK .
.It Er EINVAL
Illegal value for
.Vt flags .
.It Er ENOSR
Unable to allocate buffers to perform the
.Dv I_PEEK
due to insufficient STREAMS memory resources.
.El
.It Dv I_SRDOPT
Sets the read mode (see
.Xr read 2 )
using the value of the argument
.Va arg .
Legal
.Va arg
values are:
.Bl -tag -width RNORM
.It Dv RNORM
Byte-stream mode, the default.
.It Dv RMSGD
Message-discard mode.
.It Dv RMSGN
Message-nondiscard mode.
.El
.Pp
In addition, the stream head's treatment of control messages may be changed by
setting the following flags in
.Va arg :
.Bl -tag -width RPROTNORM
.It Dv RPROTNORM
Reject
.Xr read 2
with
.Er EBADMSG
if a control message is at the front of the stream head read queue.
.It Dv RPROTDAT
Deliver the control portion of a message as data when a user issues
.Xr read 2 .
This is the default behavior.
.It Dv RPROTDIS
Discard the control portion of a message, delivering any data portion, when a
user issues a
.Xr read 2 .
.El
.Pp
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EINVAL
.It Er EINVAL
.Va arg
is not one of the above legal values, or
.Va arg
is the bitwise
inclusive
.Sy OR
of
.Dv RMSGD
and
.Dv RMSGN .
.El
.It Dv I_GRDOPT
Returns the current read mode setting in an
.Vt int
pointed to by the argument
.Fa arg .
Read modes are described in
.Xr read 2 .
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EFAULT
.It Er EFAULT
.Fa arg
points outside the allocated address space.
.El
.It Dv 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
.Fa 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
.Fa arg ,
but the
.Fn ioctl
return value is greater than zero, this indicates that a
zero-length message is next on the queue.
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EFAULT
.It Er EFAULT
.Fa arg
points outside the allocated address space.
.El
.It Dv I_FDINSERT
Creates a message from 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.
.Pp
The
.Fa arg
argument points to a
.Vt strfdinsert
structure, which contains
the following members:
.Bd -literal -offset 2n
struct  strbuf  ctlbuf;
struct  strbuf	databuf;
t_uscalar_t	flags;
int		fildes;
int		offset;
.Ed
.Pp
The
.Fa len
member in the
.Vt ctlbuf
.Vt strbuf
structure (see
.Xr putmsg 2 )
must be set to the size of a
.Vt t_uscalar_t
plus the number of bytes of
control information to be sent with the message.
The
.Fa fildes
member specifies the file descriptor of the other stream, and the
.Fa offset
member, which must be suitably aligned for use as a
.Vt t_uscalar_t ,
specifies the offset from the start of the control buffer where
.Dv I_FDINSERT
will store a
.Vt t_uscalar_t
whose interpretation is specific to the stream end.
The
.Fa len
member in the
.Vt databuf
.Vt strbuf
structure must be set to the number of bytes of data information to be sent with
the message, or to 0 if no data part is to be sent.
.Pp
The
.Fa flags
member specifies the type of message to be created.
A normal message is created if
.Fa flags
is set to 0, and a high-priority message is created if
.Fa flags
is set to
.Dv RS_HIPRI .
For non-priority messages,
.Dv I_FDINSERT
will block if the stream write queue is full due to internal
flow control conditions.
For priority messages,
.Dv I_FDINSERT
does not block on this condition.
or non-priority messages,
.Dv I_FDINSERT
does not
block when the write queue is full and
.Dv O_NDELAY
or
.Dv O_NONBLOCK
is set.
Instead, it fails and sets
.Va errno
to
.Er EAGAIN .
.Pp
.Dv 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
.Dv O_NDELAY
or
.Dv O_NONBLOCK
has been specified.
No partial message is sent.
.Pp
The
.Fn ioctl
function with the
.Dv I_FDINSERT
command will fail if:
.Bl -tag -width EAGAIN
.It Er EAGAIN
A non-priority message is specified, the
.Dv O_NDELAY
or
.Dv O_NONBLOCK
flag is set, and the stream write queue is full due to internal flow control
conditions.
.It Er ENOSR
Buffers can not be allocated for the message that is to be created.
.It Er EFAULT
The
.Fa arg
argument points, or the buffer area specified in
.Vt ctlbuf
or
.Vt databuf
is, outside the allocated address space.
.It Er EINVAL
One of the following: The
.Fa fildes
member of the
.Vt strfdinsert
structure is not a valid, open stream file descriptor; the size of a
.Vt t_uscalar_t
plus
.Fa offset
is greater than the
.Fa len
member for the buffer specified through
.Fa ctlptr ;
the
.Fa offset
member does not specify a properly-aligned location in the data buffer; or an
undefined value is stored in
.Fa flags .
.It Er ENXIO
Hangup received on the
.Fa fildes
argument of the
.Fn ioctl
call or the
.Fa fildes
member of the
.Vt strfdinsert
structure.
.It Er ERANGE
The
.Fa len
field for the buffer specified through
.Vt databuf
does not fall within the range specified by the maximum and minimum packet
sizes of the topmost stream module; or the
.Fa len
member for the buffer specified through
.Vt databuf
is larger than the maximum configured size of the data part of a message; or the
.Fa len
member for the buffer specified through
.Vt ctlbuf
is larger than the maximum configured size of the control part of a message.
.El
.Pp
.Dv I_FDINSERT
can also fail if an error message was received by the stream
head of the stream corresponding to the
.Fa fildes
member of the
.Vt strfdinsert
structure.
In this case,
.Va errno
will be set to the value in the message.
.It Dv I_STR
Constructs an internal
.Sy STREAMS
ioctl message from the data pointed to by
.Fa arg ,
and sends that message downstream.
.Pp
This mechanism is provided to send user
.Fn ioctl
requests to downstream modules and drivers.
It allows information to be sent with the
.Fn ioctl ,
and will return to the user any information sent upstream by the downstream
recipient.
.Dv 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
.Va errno
set to
.Er ETIME .
.Pp
To send requests downstream,
.Fa arg
must point to a
.Vt strioctl
structure which contains the following members:
.Bd -literal -offset 2n
int  ic_cmd;
int  ic_timout;
int  ic_len;
char  *ic_dp;
.Ed
.Pp
.Fa ic_cmd
is the internal
.Fn ioctl
command intended for a downstream module or driver and
.Fa ic_timout
is the number of seconds (-1 = infinite, 0 = use default, >0 = as specified) an
.Dv I_STR
request will wait for acknowledgement before timing out.
.Fa ic_len
is the number of bytes in the data argument and
.Fa ic_dp
is a pointer to the data argument.
The
.Fa 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
.Fa ic_dp
should be large enough to contain the maximum amount of data that any module or
the driver in the stream can return).
.Pp
At most one
.Dv I_STR
can be active on a stream.
Further
.Dv I_STR
calls
will block until the active
.Dv I_STR
completes via a positive or negative
acknowledgement, a timeout, or an error condition at the stream head.
By setting the
.Fa ic_timout
field to 0, the user is requesting STREAMS to provide
the
.Sy DEFAULT
timeout.
The default timeout is specific to the STREAMS
implementation and may vary depending on which release of Solaris you are
using.
For Solaris 8 (and earlier versions), the default timeout is fifteen
seconds.
The
.Dv O_NDELAY
and
.Dv O_NONBLOCK
(see
.Xr open 2 )
flags have no effect on this call.
.Pp
The stream head will convert the information pointed to by the
.Vt strioctl
structure to an internal
.Fn ioctl
command message and send it downstream.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EFAULT
.It Er ENOSR
Unable to allocate buffers for the
.Fn ioctl
message due to insufficient STREAMS memory resources.
.It Er EFAULT
Either
.Fa arg
points outside the allocated address space, or the buffer area
specified by
.Fa ic_dp
and
.Fa ic_len
(separately for data sent and data returned) is outside the allocated address
space.
.It Er EINVAL
.Fa ic_len
is less than 0 or
.Fa ic_len
is larger than the maximum configured size of the data part of a message or
.Fa ic_timout
is less than \(mi1.
.It Er ENXIO
Hangup received on
.Fa fildes .
.It Er ETIME
A downstream
.Fn ioctl
timed out before acknowledgement was received.
.El
.Pp
An
.Dv I_STR
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,
.Dv I_STR
will fail with
.Va errno
set to the value in the message.
.It Dv I_SWROPT
Sets the write mode using the value of the argument
.Fa arg .
Legal bit settings for
.Fa arg
are:
.Bl -tag -width SNDZERO
.It Dv SNDZERO
Send a zero-length message downstream when a write of 0 bytes occurs.
.El
.Pp
To not send a zero-length message when a write of 0 bytes occurs, this bit must
not be set in
.Fa arg .
.Pp
On failure,
.Va errno
may be set to the following value:
.Bl -tag -width EINVAL
.It Er EINVAL
.Fa arg
is not the above legal value.
.El
.It Dv I_GWROPT
Returns the current write mode setting, as described above, in the
.Vt int
that is pointed to by the argument
.Fa arg .
.It Dv I_SENDFD
Requests the stream associated with
.Fa 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
.Fa arg ,
which must be an open file descriptor.
.Pp
.Dv I_SENDFD
converts
.Fa 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
.Xr Intro 3 )
of the stream head at the other end of the stream pipe to which it is connected.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EAGAIN
.It Er EAGAIN
The sending stream is unable to allocate a message block to contain the file
pointer.
.It Er EAGAIN
The read queue of the receiving stream head is full and cannot accept the
message sent by
.Dv I_SENDFD .
.It Er EBADF
.Fa arg
is not a valid, open file descriptor.
.It Er EINVAL
.Va fildes
is not connected to a stream pipe.
.It Er ENXIO
Hangup received on
.Fa fildes .
.El
.It Dv I_RECVFD
Retrieves the file descriptor associated with the message sent by an
.Dv I_SENDFD
.Fn ioctl
over a stream pipe.
.Fa arg
is a pointer to a data buffer large enough to hold an
.Vt strrecvfd
data structure containing the following members:
.Bd -literal -offset 2n
int	fd;
uid_t	uid;
gid_t	gid;
.Ed
.Pp
.Fa fd
is an integer file descriptor.
.Fa uid
and
.Fa gid
are the user id and group id, respectively, of the sending stream.
.Pp
If
.Dv O_NDELAY
and
.Dv O_NONBLOCK
are clear (see
.Xr open 2 ) ,
.Dv I_RECVFD
will block until a message is present at the stream head.
If
.Dv O_NDELAY
or
.Dv O_NONBLOCK
is set,
.Dv I_RECVFD
will fail with
.Va errno
set to
.Er EAGAIN
if no message is present at the stream head.
.Pp
If the message at the stream head is a message sent by an
.Dv 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
.Fa fd
field of the
.Vt strrecvfd
structure.
The structure is copied into the user data buffer pointed to by
.Fa arg .
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EOVERFLOW
.It Er EAGAIN
A message is not present at the stream head read queue, and the
.Dv O_NDELAY
or
.Dv O_NONBLOCK
flag is set.
.It Er EBADMSG
The message at the stream head read queue is not a message containing a passed
file descriptor.
.It Er EFAULT
.Fa arg
points outside the allocated address space.
.It Er EMFILE
.Dv NOFILES
file descriptors are currently open.
.It Er ENXIO
Hangup received on
.Fa fildes .
.It Er EOVERFLOW
.Fa uid
or
.Fa gid
is too large to be stored in the structure pointed to by
.Fa arg .
.El
.It Dv I_LIST
Allows the user to list all the module names on the stream, up to and including
the topmost driver name.
If
.Fa arg
is
.Dv NULL ,
the return value is the number of modules, including the driver, that are on
the stream pointed to by
.Fa fildes .
This allows the user to allocate enough space for the module
names.
If
.Fa arg
is non-null, it should point to an
.Vt str_list
structure that has the following members:
.Bd -literal -offset 2n
int sl_nmods;
struct  str_mlist  *sl_modlist;
.Ed
.Pp
The
.Vt str_mlist
structure has the following member:
.Bd -literal -offset 2n
char l_name[FMNAMESZ+1];
.Ed
.Pp
The
.Fa sl_nmods
member indicates the number of entries the process has allocated in the array.
Upon return, the
.Fa sl_modlist
member of the
.Vt str_list
structure contains the list of module names, and the number of
entries that have been filled into the
.Fa sl_modlist
array is found in the
.Fa sl_nmods
member (the number includes the number of modules including the driver).
The return value from
.Fn ioctl
is 0.
The entries are filled in
starting at the top of the stream and continuing downstream until either the
end of the stream is reached, or the number of requested modules
.Pq Fa sl_nmods
is satisfied.
On failure,
.Va errno
may be set to one of the following values:
.Bl -tag -width EINVAL
.It Er EINVAL
The
.Fa sl_nmods
member is less than 1.
.It Er EAGAIN
Unable to allocate buffers
.El
.It Dv I_ATMARK
Allows the user to see if the current message on the stream head read queue is
.Dq marked
by some module downstream.
.Fa arg
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:
.Bl -tag -width LASTMARK
.It Dv ANYMARK
Check if the message is marked.
.It Dv LASTMARK
Check if the message is the last one marked on the queue.
.El
.Pp
The return value is
.Sy 1
if the mark condition is satisfied and
.Sy 0
otherwise.
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EINVAL
.It Er EINVAL
Invalid
.Fa arg
value.
.El
.It Dv I_CKBAND
Check if the message of a given priority band exists on the stream head read
queue.
This returns
.Sy 1
if a message of a given priority exists,
.Sy 0
if not, or
.Sy \(mi1
on error.
.Fa arg
should be an integer containing the value of the priority band in question.
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EINVAL
.It Er EINVAL
Invalid
.Fa arg
value.
.El
.It Dv I_GETBAND
Returns the priority band of the first message on the stream head read queue in
the integer referenced by
.Fa arg .
On failure,
.Va errno
is set to the following value:
.Bl -tag -width ENODATA
.It Er ENODATA
No message on the stream head read queue.
.El
.It Dv I_CANPUT
Check if a certain band is writable.
.Fa arg
is set to the priority band in question.
The return value is
.Sy 0
if the priority band
.Fa arg
is flow controlled,
.Sy 1
if the band is writable, or
.Sy \(mi1
on error.
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EINVAL
.It Er EINVAL
Invalid
.Va arg
value.
.El
.It Dv I_SETCLTIME
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.
Note, however, that the module or driver may itself delay in its close routine;
this delay is independent of the stream head's delay and is not settable.
If, after the delay, data are still present, data will be flushed.
.Fa arg
is a pointer to an integer containing the number of
milliseconds to delay, rounded up to the nearest legal value on the system.
The default is fifteen seconds.
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EINVAL
.It Er EINVAL
Invalid
.Fa arg
value.
.El
.It Dv I_GETCLTIME
Returns the close time delay in the integer pointed by
.Va arg .
.It Dv I_SERROPT
Sets the error mode using the value of the argument
.Fa arg .
.Pp
Normally stream head errors are persistent; once they are set due to an
.Dv M_ERROR
or
.Dv M_HANGUP ,
the error condition will remain until the stream is closed.
This option can be used to set the stream head into
non-persistent error mode i\.e\. once the error has been returned in response
to a
.Xr read 2 ,
.Xr getmsg 2 ,
.Xr ioctl 2 ,
.Xr write 2 ,
or
.Xr putmsg 2
call the error condition will be cleared.
The error mode can be controlled independently for read and write side errors.
Legal
.Fa arg
values
are either none or one of:
.Bl -tag -width RERRNONPERSIST
.It Dv RERRNORM
Persistent read errors, the default.
.It Dv RERRNONPERSIST
Non-persistent read errors.
.El
.Pp
.Sy OR Ns 'ed
with either none or one of:
.Bl -tag -width WERRNONPERSIST
.It Dv WERRNORM
Persistent write errors, the default.
.It Dv WERRNONPERSIST
Non-persistent write errors.
.El
.Pp
When no value is specified e\.g\.  for the read side error behavior then the
behavior for that side will be left unchanged.
.Pp
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EINVAL
.It Er EINVAL
.Va arg
is not one of the above legal values.
.El
.It Dv I_GERROPT
Returns the current error mode setting in an
.Vt int
pointed to by the argument
.Fa arg .
Error modes are described above for
.Dv I_SERROPT .
On failure,
.Va errno
is set to the following value:
.Bl -tag -width EFAULT
.It Er EFAULT
.Fa arg
points outside the allocated address space.
.El
.El
.Pp
The following four commands are used for connecting and disconnecting
multiplexed STREAMS configurations.
.Bl -tag -width I_PUNLINK
.It Dv I_LINK
Connects two streams, where
.Fa fildes
is the file descriptor of the stream
connected to the multiplexing driver, and
.Fa arg
is the file descriptor of the stream connected to another driver.
The stream designated by
.Va arg
gets
connected below the multiplexing driver.
.Dv I_LINK
requires the multiplexing
driver to send an acknowledgement message to the stream head regarding the
linking operation.
This call returns a multiplexor ID number (an identifier
used to disconnect the multiplexor, see
.Dv I_UNLINK )
on success, and \(mi1 on failure.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EAGAIN
.It Er ENXIO
Hangup received on
.Va fildes .
.It Er ETIME
Time out before acknowledgement message was received at stream head.
.It Er EAGAIN
Temporarily unable to allocate storage to perform the
.Dv I_LINK .
.It Er ENOSR
Unable to allocate storage to perform the
.Dv I_LINK
due to insufficient
.Sy STREAMS
memory resources.
.It Er EBADF
.Va arg
is not a valid, open file descriptor.
.It Er EINVAL
.Va fildes
stream does not support multiplexing.
.It Er EINVAL
is not a stream, or is already linked under a multiplexor.
.It Er EINVAL
The specified link operation would cause a
.Dq cycle
in the resulting configuration; that is, a driver would be linked into the
multiplexing configuration in more than one place.
.It Er EINVAL
.Va fildes
is the file descriptor of a pipe or FIFO.
.It Er EINVAL
Either the upper or lower stream has a major number \(>= the maximum major
number on the system.
.El
.Pp
An
.Dv 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
.Fa fildes .
In addition, an error code can be
returned in the positive or negative acknowledgement message.
For these cases,
.Dv I_LINK
will fail with
.Va errno
set to the value in the message.
.It Dv I_UNLINK
Disconnects the two streams specified by
.Fa fildes
and
.Fa arg .
.Fa fildes
is the file descriptor of the stream connected to the multiplexing
driver.
.Fa arg
is the multiplexor ID number that was returned by the
.Dv I_LINK .
If
.Fa arg
is \(mi1, then all streams that were linked to
.Fa fildes
are disconnected.
As in
.Dv I_LINK ,
this command requires the multiplexing driver to acknowledge the unlink.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EINVAL
.It Er ENXIO
Hangup received on
.Va fildes .
.It Er ETIME
Time out before acknowledgement message was received at stream head.
.It Er ENOSR
Unable to allocate storage to perform the
.Dv I_UNLINK
due to insufficient
STREAMS memory resources.
.It Er EINVAL
.Fa arg
is an invalid multiplexor ID number or
.Fa fildes
is not the stream on which the
.Dv I_LINK
that returned
.Fa arg
was performed.
.It Er EINVAL
.Fa fildes
is the file descriptor of a pipe or FIFO.
.El
.Pp
An
.Dv 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
.Fa fildes .
In addition, an error code can be
returned in the positive or negative acknowledgement message.
For these cases,
.Dv I_UNLINK
will fail with
.Va errno
set to the value in the message.
.It Dv I_PLINK
Connects two streams, where
.Fa fildes
is the file descriptor of the stream
connected to the multiplexing driver, and
.Fa arg
is the file descriptor of
the stream connected to another driver.
The stream designated by
.Fa arg
gets
connected via a persistent link below the multiplexing driver.
.Dv I_PLINK
requires the multiplexing driver to send an acknowledgement message to the
stream head regarding the linking operation.
This call creates a persistent
link that continues to exist even if the file descriptor
.Fa fildes
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
.Dv I_PUNLINK )
on success, and \(mi1 on failure.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EAGAIN
.It Er ENXIO
Hangup received on
.Fa fildes .
.It Er ETIME
Time out before acknowledgement message was received at the stream head.
.It Er EAGAIN
Unable to allocate STREAMS storage to perform the
.Dv I_PLINK .
.It Er EBADF
.Va arg
is not a valid, open file descriptor.
.It Er EINVAL
.Va fildes
does not support multiplexing.
.It Er EINVAL
.Va arg
is not a stream or is already linked under a multiplexor.
.It Er EINVAL
The specified link operation would cause a
.Dq cycle
in the resulting configuration; that is, if a driver would be linked into the
multiplexing configuration in more than one place.
.It Er EINVAL
.Fa fildes
is the file descriptor of a pipe or FIFO.
.El
.Pp
An
.Dv I_PLINK
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
.Fa fildes .
In addition, an error code can be
returned in the positive or negative acknowledgement message.
For these cases,
.Dv I_PLINK
will fail with
.Va errno
set to the value in the message.
.It Dv I_PUNLINK
Disconnects the two streams specified by
.Fa fildes
and
.Fa arg
that are
connected with a persistent link.
.Fa fildes
is the file descriptor of the
stream connected to the multiplexing driver.
.Fa arg
is the multiplexor ID number that was returned by
.Dv I_PLINK
when a stream was linked below the multiplexing driver.
If
.Fa arg
is
.Dv MUXID_ALL
then all streams that are persistent links to
.Fa fildes
are disconnected.
As in
.Dv I_PLINK ,
this command requires the multiplexing driver to acknowledge the unlink.
On failure,
.Va errno
is set to one of the following values:
.Bl -tag -width EAGAIN
.It Er ENXIO
Hangup received on
.Fa fildes .
.It Er ETIME
Time out before acknowledgement message was received at the stream head.
.It Er EAGAIN
Unable to allocate buffers for the acknowledgement message.
.It Er EINVAL
Invalid multiplexor ID number.
.It Er EINVAL
.Fa fildes
is the file descriptor of a pipe or FIFO.
.El
.Pp
An
.Dv I_PUNLINK
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
.Fa fildes .
In addition, an error code can be
returned in the positive or negative acknowledgement message.
For these cases,
.Dv I_PUNLINK
will fail with
.Va errno
set to the value in the message.
.El
.Sh RETURN VALUES
Unless specified otherwise above, the return value from
.Xr ioctl 2
is
.Sy 0
upon success and
.Sy \(mi1
upon failure, with
.Va errno
set as indicated.
.Sh SEE ALSO
.Xr close 2 ,
.Xr fcntl 2 ,
.Xr getmsg 2 ,
.Xr ioctl 2 ,
.Xr open 2 ,
.Xr poll 2 ,
.Xr putmsg 2 ,
.Xr read 2 ,
.Xr write 2 ,
.Xr Intro 3 ,
.Xr signal 3C ,
.Xr signal.h 3HEAD
.Pp
.%B STREAMS Programming Guide