STREAMIO(4I) | Ioctl Requests | STREAMIO(4I) |
streamio
— STREAMS
ioctl commands
#include
<sys/types.h>
#include <stropts.h>
#include <sys/conf.h>
int
ioctl
(int fildes,
int command, ... /*arg*/);
STREAMS (see Intro(3))
ioctl
()
commands are a subset of the ioctl(2)
commands and perform a variety of control functions on streams.
The fildes argument is an open file descriptor that refers to a stream. The command argument determines the control function to be performed as described below. The arg argument 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 arguments 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
ioctls, they are
subject to the errors described in
ioctl(2). In addition to those errors,
the call will fail with errno set to
EINVAL
, 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 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 errno set to this value.
The following
ioctl
()
commands, with error values indicated, are applicable to all STREAMS
files:
I_PUSH
EINVAL
EFAULT
ENXIO
ENXIO
ENOTSUP
I_POP
I_POP
request. On failure,
errno is set to one of the following values:
EINVAL
ENXIO
EPERM
ENOTSUP
I_ANCHOR
I_ANCHOR
request. On
failure, errno is set to the following value:
EINVAL
I_LOOK
FMNAMESZ
+1 bytes long. This requires the
declaration ‘#include
<sys/conf.h>
’. On failure,
errno
is set to one of the following values:
EFAULT
EINVAL
I_FLUSH
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 arg.
If FLUSHR
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 FLUSHW
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 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.
Correct flush handling of a pipe or FIFO with modules pushed is achieved via the pipemod module. This module should be the first module pushed onto a pipe so that it is at the midpoint of the pipe itself.
On failure, errno is set to one of the following values:
ENOSR
EINVAL
ENXIO
I_FLUSHBAND
unsigned char bi_pri; int bi_flag;
The bi_flag field may be one of
FLUSHR
, FLUSHW
, or
FLUSHRW
as described earlier.
I_SETSIG
SIGPOLL
signal (see
signal(3C)) when a particular event
has occurred on the stream associated with fildes.
I_SETSIG
supports an asynchronous processing
capability in streams. The value of arg is a bitmask
that specifies the events for which the user should be signaled. It is the
bitwise OR of any combination of the following constants:
S_INPUT
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.S_RDNORM
S_RDBAND
S_HIPRI
S_OUTPUT
S_WRNORM
S_OUTPUT
.S_WRBAND
S_MSG
SIGPOLL
signal has reached the front of the
stream head read queue.S_ERROR
M_ERROR
message has reached the stream
head.S_HANGUP
M_HANGUP
message has reached the stream
head.S_BANDURG
S_RDBAND
,
SIGURG
is generated instead of
SIGPOLL
when a priority message reaches the
front of the stream head read queue.A user process may choose to be signaled only of high priority
messages by setting the arg bitmask to the value
S_HIPRI
.
Processes that wish to receive SIGPOLL
signals must explicitly register to receive them using
I_SETSIG
. If several processes register to
receive this signal for the same event on the same stream, each process
will be signaled when the event occurs.
If the value of arg is zero, the calling
process will be unregistered and will not receive further
SIGPOLL
signals. On failure,
errno is set to one of the following values:
EINVAL
SIGPOLL
signal.EAGAIN
I_GETSIG
SIGPOLL
signal. The events are
returned as a bitmask pointed to by arg, where the
events are those specified in the description of
I_SETSIG
above. On failure,
errno is set to one of the following values:
EINVAL
SIGPOLL
signal.EFAULT
I_FIND
EFAULT
EINVAL
I_PEEK
I_PEEK
is analogous to
getmsg(2) except that it does not
remove the message from the queue. arg points to a
strpeek structure, which contains the following
members:
struct strbuf ctlbuf; struct strbuf databuf; long flags;
The maxlen field in the
ctlbuf and databuf
strbuf structures (see
getmsg(2)) must be set to the
number of bytes of control information and/or data information,
respectively, to retrieve. flags may be set to
RS_HIPRI
or 0. If
RS_HIPRI
is set, I_PEEK
will look for a high priority message on the stream head read queue.
Otherwise, I_PEEK
will look for the first
message on the stream head read queue.
I_PEEK
returns 1 if
a message was retrieved, and returns 0 if no message
was found on the stream head read queue. It does not wait for a message
to arrive. On return, ctlbuf specifies information
in the control buffer, databuf specifies
information in the data buffer, and flags contains
the value RS_HIPRI
or 0. On
failure, errno is set to the following value:
EFAULT
EBADMSG
I_PEEK
.EINVAL
ENOSR
I_PEEK
due to insufficient STREAMS memory
resources.I_SRDOPT
In addition, the stream head's treatment of control messages may be changed by setting the following flags in arg:
RPROTNORM
EBADMSG
if a control message is at the front
of the stream head read queue.RPROTDAT
RPROTDIS
On failure, errno is set to the following value:
EINVAL
RMSGD
and
RMSGN
.I_GRDOPT
EFAULT
I_NREAD
ioctl
()
return value is greater than zero, this indicates that a zero-length
message is next on the queue. On failure, errno is
set to the following value:
EFAULT
I_FDINSERT
The arg argument points to a strfdinsert structure, which contains the following members:
struct strbuf ctlbuf; struct strbuf databuf; t_uscalar_t flags; int fildes; int offset;
The len member in the
ctlbuf strbuf structure (see
putmsg(2)) must be set to the size
of a t_uscalar_t plus the number of bytes of
control information to be sent with the message. The
fildes member specifies the file descriptor of the
other stream, and the offset member, which must be
suitably aligned for use as a t_uscalar_t,
specifies the offset from the start of the control buffer where
I_FDINSERT
will store a
t_uscalar_t whose interpretation is specific to
the stream end. The len member in the
databuf 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.
The flags member specifies the type of
message to be created. A normal message is created if
flags is set to 0, and a high-priority message is
created if flags is set to
RS_HIPRI
. For non-priority messages,
I_FDINSERT
will block if the stream write queue
is full due to internal flow control conditions. For priority messages,
I_FDINSERT
does not block on this condition. or
non-priority messages, I_FDINSERT
does not block
when the write queue is full and O_NDELAY
or
O_NONBLOCK
is set. Instead, it fails and sets
errno to EAGAIN
.
I_FDINSERT
also blocks, unless
prevented by lack of internal resources, waiting for the availability of
message blocks in the stream, regardless of priority or whether
O_NDELAY
or O_NONBLOCK
has been specified. No partial message is sent.
The
ioctl
()
function with the I_FDINSERT
command will fail
if:
EAGAIN
O_NDELAY
or O_NONBLOCK
flag is set, and the stream write queue is full due to internal flow
control conditions.ENOSR
EFAULT
EINVAL
ENXIO
ioctl
() call or the
fildes member of the
strfdinsert structure.ERANGE
I_FDINSERT
can also fail if an error
message was received by the stream head of the stream corresponding to
the fildes member of the
strfdinsert structure. In this case,
errno will be set to the value in the message.
I_STR
This mechanism is provided to send user
ioctl
()
requests to downstream modules and drivers. It allows information to be
sent with the ioctl
(), and will return to the
user any information sent upstream by the downstream recipient.
I_STR
blocks until the system responds with
either a positive or negative acknowledgement message, or until the
request times out after some period of time. If the request times out,
it fails with errno set to
ETIME
.
To send requests downstream, arg must point to a strioctl structure which contains the following members:
int ic_cmd; int ic_timout; int ic_len; char *ic_dp;
ic_cmd is the internal
ioctl
()
command intended for a downstream module or driver and
ic_timout is the number of seconds (-1 = infinite,
0 = use default, >0 = as specified) an I_STR
request will wait for acknowledgement before timing out.
ic_len is the number of bytes in the data argument
and ic_dp is a pointer to the data argument. The
ic_len field has two uses: on input, it contains
the length of the data argument passed in, and on return from the
command, it contains the number of bytes being returned to the user (the
buffer pointed to by ic_dp should be large enough
to contain the maximum amount of data that any module or the driver in
the stream can return).
At most one I_STR
can be
active on a stream. Further I_STR
calls will
block until the active I_STR
completes via a
positive or negative acknowledgement, a timeout, or an error condition
at the stream head. By setting the ic_timout field
to 0, the user is requesting STREAMS to provide the
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 O_NDELAY
and
O_NONBLOCK
(see
open(2)) flags have no effect on
this call.
The stream head will convert the information
pointed to by the strioctl structure to an
internal
ioctl
()
command message and send it downstream. On failure,
errno is set to one of the following values:
ENOSR
ioctl
()
message due to insufficient STREAMS memory resources.EFAULT
EINVAL
ENXIO
ETIME
ioctl
() timed out before
acknowledgement was received.An I_STR
can also fail while waiting
for an acknowledgement if a message indicating an error or a hangup is
received at the 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,
I_STR
will fail with errno
set to the value in the message.
I_SWROPT
SNDZERO
To not send a zero-length message when a write of 0 bytes occurs, this bit must not be set in arg.
On failure, errno may be set to the following value:
EINVAL
I_GWROPT
I_SENDFD
I_SENDFD
converts
arg into the corresponding system file pointer. It
allocates a message block and inserts the file pointer in the block. The
user id and group id associated with the sending process are also
inserted. This message is placed directly on the read queue (see
Intro(3)) of the stream head at the
other end of the stream pipe to which it is connected. On failure,
errno is set to one of the following values:
EAGAIN
EAGAIN
I_SENDFD
.EBADF
EINVAL
ENXIO
I_RECVFD
I_SENDFD
ioctl
()
over a stream pipe. arg is a pointer to a data
buffer large enough to hold an strrecvfd data
structure containing the following members:
int fd; uid_t uid; gid_t gid;
fd is an integer file descriptor. uid and gid are the user id and group id, respectively, of the sending stream.
If O_NDELAY
and
O_NONBLOCK
are clear (see
open(2)),
I_RECVFD
will block until a message is present
at the stream head. If O_NDELAY
or
O_NONBLOCK
is set,
I_RECVFD
will fail with
errno set to EAGAIN
if no
message is present at the stream head.
If the message at the stream head is a message sent by an
I_SENDFD
, a new user file descriptor is
allocated for the file pointer contained in the message. The new file
descriptor is placed in the fd field of the
strrecvfd structure. The structure is copied into
the user data buffer pointed to by arg. On
failure, errno is set to one of the following
values:
EAGAIN
O_NDELAY
or O_NONBLOCK
flag is set.EBADMSG
EFAULT
EMFILE
NOFILES
file descriptors are currently open.ENXIO
EOVERFLOW
I_LIST
NULL
, the return value is the number of modules,
including the driver, that are on the stream pointed to by
fildes. This allows the user to allocate enough
space for the module names. If arg is non-null, it
should point to an str_list structure that has the
following members:
int sl_nmods; struct str_mlist *sl_modlist;
The str_mlist structure has the following member:
char l_name[FMNAMESZ+1];
The sl_nmods member
indicates the number of entries the process has allocated in the array.
Upon return, the sl_modlist member of the
str_list structure contains the list of module
names, and the number of entries that have been filled into the
sl_modlist array is found in the
sl_nmods member (the number includes the number of
modules including the driver). The return value from
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 (sl_nmods) is
satisfied. On failure, errno may be set to one of
the following values:
EINVAL
EAGAIN
I_ATMARK
ANYMARK
LASTMARK
The return value is 1 if the mark condition is satisfied and 0 otherwise. On failure, errno is set to the following value:
EINVAL
I_CKBAND
EINVAL
I_GETBAND
ENODATA
I_CANPUT
EINVAL
I_SETCLTIME
EINVAL
I_GETCLTIME
I_SERROPT
Normally stream head errors are persistent; once they are set
due to an M_ERROR
or
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 read(2),
getmsg(2),
ioctl(2),
write(2), or
putmsg(2) call the error condition
will be cleared. The error mode can be controlled independently for read
and write side errors. Legal arg values are either
none or one of:
RERRNORM
RERRNONPERSIST
OR'ed with either none or one of:
WERRNORM
WERRNONPERSIST
When no value is specified e.g. for the read side error behavior then the behavior for that side will be left unchanged.
On failure, errno is set to the following value:
EINVAL
I_GERROPT
I_SERROPT
. On failure,
errno is set to the following value:
EFAULT
The following four commands are used for connecting and disconnecting multiplexed STREAMS configurations.
I_LINK
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 I_UNLINK
) on success, and −1 on
failure. On failure, errno is set to one of the
following values:
ENXIO
ETIME
EAGAIN
I_LINK
.ENOSR
I_LINK
due to insufficient
STREAMS memory resources.EBADF
EINVAL
EINVAL
EINVAL
EINVAL
EINVAL
An I_LINK
can also fail while waiting
for the multiplexing driver to acknowledge the link request, if a
message indicating an error or a hangup is received at the stream head
of fildes. In addition, an error code can be
returned in the positive or negative acknowledgement message. For these
cases, I_LINK
will fail with
errno set to the value in the message.
I_UNLINK
I_LINK
. If arg is
−1, then all streams that were linked to
fildes are disconnected. As in
I_LINK
, this command requires the multiplexing
driver to acknowledge the unlink. On failure, errno
is set to one of the following values:
ENXIO
ETIME
ENOSR
I_UNLINK
due to insufficient STREAMS memory
resources.EINVAL
I_LINK
that returned arg
was performed.EINVAL
An I_UNLINK
can also fail while
waiting for the multiplexing driver to acknowledge the link request, if
a message indicating an error or a hangup is received at the stream head
of fildes. In addition, an error code can be
returned in the positive or negative acknowledgement message. For these
cases, I_UNLINK
will fail with
errno set to the value in the message.
I_PLINK
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 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 I_PUNLINK
) on success, and
−1 on failure. On failure, errno is set to
one of the following values:
ENXIO
ETIME
EAGAIN
I_PLINK
.EBADF
EINVAL
EINVAL
EINVAL
EINVAL
An 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 fildes. In addition, an error code can be
returned in the positive or negative acknowledgement message. For these
cases, I_PLINK
will fail with
errno set to the value in the message.
I_PUNLINK
I_PLINK
when a stream was linked below the multiplexing driver. If
arg is MUXID_ALL
then all
streams that are persistent links to fildes are
disconnected. As in I_PLINK
, this command requires
the multiplexing driver to acknowledge the unlink. On failure,
errno is set to one of the following values:
ENXIO
ETIME
EAGAIN
EINVAL
EINVAL
An 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 fildes. In addition, an error code can be
returned in the positive or negative acknowledgement message. For these
cases, I_PUNLINK
will fail with
errno set to the value in the message.
Unless specified otherwise above, the return value from ioctl(2) is 0 upon success and −1 upon failure, with errno set as indicated.
close(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2), putmsg(2), read(2), write(2), Intro(3), signal(3C), signal.h(3HEAD)
STREAMS Programming Guide
March 13, 2022 | OmniOS |