| 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_PUSHEINVALEFAULTENXIOENXIOENOTSUPI_POPI_POP request. On failure,
errno is set to one of the following values:
EINVALENXIOEPERMENOTSUPI_ANCHORI_ANCHOR request. On
failure, errno is set to the following value:
EINVALI_LOOKFMNAMESZ+1 bytes long. This requires the
declaration ‘#include
<sys/conf.h>’. On failure,
errno is set to one of the following values:
EFAULTEINVALI_FLUSHIf 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:
ENOSREINVALENXIOI_FLUSHBANDunsigned char bi_pri; int bi_flag;
The bi_flag field may be one of
FLUSHR, FLUSHW, or
FLUSHRW as described earlier.
I_SETSIGSIGPOLL 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_INPUTM_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_RDNORMS_RDBANDS_HIPRIS_OUTPUTS_WRNORMS_OUTPUT.S_WRBANDS_MSGSIGPOLL signal has reached the front of the
stream head read queue.S_ERRORM_ERROR message has reached the stream
head.S_HANGUPM_HANGUP message has reached the stream
head.S_BANDURGS_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:
EINVALSIGPOLL signal.EAGAINI_GETSIGSIGPOLL 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:
EINVALSIGPOLL
signal.EFAULTI_FINDEFAULTEINVALI_PEEKI_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:
EFAULTEBADMSGI_PEEK.EINVALENOSRI_PEEK due to insufficient STREAMS memory
resources.I_SRDOPTIn addition, the stream head's treatment of control messages may be changed by setting the following flags in arg:
RPROTNORMEBADMSG if a control message is at the front
of the stream head read queue.RPROTDATRPROTDISOn failure, errno is set to the following value:
EINVALRMSGD and
RMSGN.I_GRDOPTEFAULTI_NREADioctl()
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:
EFAULTI_FDINSERTThe 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:
EAGAINO_NDELAY or O_NONBLOCK
flag is set, and the stream write queue is full due to internal flow
control conditions.ENOSREFAULTEINVALENXIOioctl() call or the
fildes member of the
strfdinsert structure.ERANGEI_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_STRThis 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:
ENOSRioctl()
message due to insufficient STREAMS memory resources.EFAULTEINVALENXIOETIMEioctl() 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_SWROPTSNDZEROTo 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:
EINVALI_GWROPTI_SENDFDI_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:
EAGAINEAGAINI_SENDFD.EBADFEINVALENXIOI_RECVFDI_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:
EAGAINO_NDELAY or O_NONBLOCK
flag is set.EBADMSGEFAULTEMFILENOFILES
file descriptors are currently open.ENXIOEOVERFLOWI_LISTNULL, 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:
EINVALEAGAINI_ATMARKANYMARKLASTMARKThe return value is 1 if the mark condition is satisfied and 0 otherwise. On failure, errno is set to the following value:
EINVALI_CKBANDEINVALI_GETBANDENODATAI_CANPUTEINVALI_SETCLTIMEEINVALI_GETCLTIMEI_SERROPTNormally 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:
RERRNORMRERRNONPERSISTOR'ed with either none or one of:
WERRNORMWERRNONPERSISTWhen 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:
EINVALI_GERROPTI_SERROPT. On failure,
errno is set to the following value:
EFAULTThe following four commands are used for connecting and disconnecting multiplexed STREAMS configurations.
I_LINKI_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:
ENXIOETIMEEAGAINI_LINK.ENOSRI_LINK due to insufficient
STREAMS memory resources.EBADFEINVALEINVALEINVALEINVALEINVALAn 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_UNLINKI_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:
ENXIOETIMEENOSRI_UNLINK due to insufficient STREAMS memory
resources.EINVALI_LINK that returned arg
was performed.EINVALAn 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_PLINKI_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:
ENXIOETIMEEAGAINI_PLINK.EBADFEINVALEINVALEINVALEINVALAn 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_PUNLINKI_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:
ENXIOETIMEEAGAINEINVALEINVALAn 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 |