SunOS man pages : streamio (7)
Ioctl Requests streamio(7I)
NAME
streamio - STREAMS ioctl commands
SYNOPSIS
#include <sys/types.h>
#include <stropts.h>
#include <sys/conf.h>
int ioctl(int fildes, int command, ... /*arg*/);
DESCRIPTION
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 argu-
ment 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.
IOCTLS
The following ioctl commands, with error values indicated,
are applicable to all STREAMS files:
I_PUSH
Pushes the module whose name is pointed to by arg onto
the top of the current stream, just below the STREAM
head. If the STREAM is a pipe, the module will be
inserted between the stream heads of both ends of the
pipe. It then calls the open routine of the newly-
pushed module. On failure, errno is set to one of the
following values:
SunOS 5.8 Last change: 19 Apr 1999 1
Ioctl Requests streamio(7I)
EINVAL
Invalid module name.
EFAULT
arg points outside the allocated address space.
ENXIO Open routine of new module failed.
ENXIO Hangup received on fildes.
I_POP Removes the module just below the STREAM head of the
STREAM pointed to by fildes. To remove a module from
a pipe requires that the module was pushed on the side
it is being removed from. arg should be 0 in an I_POP
request. On failure, errno is set to one of the fol-
lowing values:
EINVAL
No module present in the stream.
ENXIO Hangup received on fildes.
EPERM Attempt to pop through an anchor by an
unpriviledged process.
I_ANCHOR
Positions the stream anchor to be at the STREAMS
module directly below the STREAM head. Once this has
been done, only a privileged process may pop modules
below the anchor on the stream. arg must be 0 in an
I_ANCHOR request. On failure, errno is set to the fol-
lowing value:
EINVAL
Request to put an anchor on a pipe.
I_LOOK
Retrieves the name of the module just below the STREAM
head of the STREAM pointed to by fildes, and places it
in a null terminated character string pointed at by
arg. The buffer pointed to by arg should be at least
FMNAMESZ+1 bytes long. This requires the declaration
#include <sys/conf.h>. On failure, errno is set to one
of the following values:
EFAULT
arg points outside the allocated address space.
EINVAL
SunOS 5.8 Last change: 19 Apr 1999 2
Ioctl Requests streamio(7I)
No module present in stream.
I_FLUSH
This request flushes all input and/or output queues,
depending on the value of arg. Legal arg values are:
FLUSHR
Flush read queues.
FLUSHW
Flush write queues.
FLUSHRW
Flush read and write queues.
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 Unable to allocate buffers for flush message due
to insufficient STREAMS memory resources.
EINVAL
Invalid arg value.
ENXIO Hangup received on fildes.
SunOS 5.8 Last change: 19 Apr 1999 3
Ioctl Requests streamio(7I)
I_FLUSHBAND
Flushes a particular band of messages. arg points to a
bandinfo structure that has the following members:
unsigned char bi_pri;
int bi_flag;
The bi_flag field may be one of FLUSHR, FLUSHW, or
FLUSHRW as described earlier.
I_SETSIG
Informs the STREAM head that the user wishes the
kernel to issue the 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 combi-
nation of the following constants:
S_INPUT
Any message other than an 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
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.
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.
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.
S_OUTPUT
The write queue just below the STREAM head
is no longer full. This notifies the user
SunOS 5.8 Last change: 19 Apr 1999 4
Ioctl Requests streamio(7I)
that there is room on the queue for send-
ing (or writing) data downstream.
S_WRNORM
This event is the same as S_OUTPUT.
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) prior-
ity data downstream.
S_MSG A STREAMS signal message that contains the
SIGPOLL signal has reached the front of
the STREAM head read queue.
S_ERROR
An M_ERROR message has reached the STREAM
head.
S_HANGUP
An M_HANGUP message has reached the STREAM
head.
S_BANDURG
When used in conjunction with 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
arg value is invalid or arg is zero and
process is not registered to receive the
SIGPOLL signal.
EAGAIN
SunOS 5.8 Last change: 19 Apr 1999 5
Ioctl Requests streamio(7I)
Allocation of a data structure to store
the signal request failed.
I_GETSIG
Returns the events for which the calling process
is currently registered to be sent a 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
Process not registered to receive the SIG-
POLL signal.
EFAULT
arg points outside the allocated address
space.
I_FIND
Compares the names of all modules currently
present in the STREAM to the name pointed to by
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, errno is set
to one of the following values:
EFAULT
arg points outside the allocated address
space.
EINVAL
arg does not contain a valid module name.
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. 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;
SunOS 5.8 Last change: 19 Apr 1999 6
Ioctl Requests streamio(7I)
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 mes-
sage 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 informa-
tion in the data buffer, and flags contains
the value RS_HIPRI or 0. On failure, errno
is set to the following value:
EFAULT
arg points, or the buffer area speci-
fied in ctlbuf or databuf is, outside
the allocated address space.
EBADMSG
Queued message to be read is not
valid for I_PEEK.
EINVAL
Illegal value for flags.
I_SRDOPT
Sets the read mode (see read(2)) using the
value of the argument arg. Legal arg
values are:
RNORM Byte-stream mode, the default.
RMSGD Message-discard mode.
RMSGN Message-nondiscard mode.
In addition, the STREAM head's treatment of con-
trol messages may be changed by setting the fol-
lowing flags in arg:
RPROTNORM
Reject read() with EBADMSG if a
SunOS 5.8 Last change: 19 Apr 1999 7
Ioctl Requests streamio(7I)
control message is at the front of
the STREAM head read queue.
RPROTDAT
Deliver the control portion of a
message as data when a user issues
read(). This is the default
behavior.
RPROTDIS
Discard the control portion of a
message, delivering any data por-
tion, when a user issues a read().
On failure, errno is set to the following
value:
EINVAL
arg is not one of the above legal
values, or arg is the bitwise
inclusive OR of RMSGD and RMSGN.
I_GRDOPT
Returns the current read mode setting in
an int pointed to by the argument arg.
Read modes are described in read(). On
failure, errno is set to the following
value:
EFAULT
arg points outside the allocated
address space.
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 arg. The return
value for the command is the number of
messages on the STREAM head read queue.
For example, if zero is returned in arg,
but the 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
arg points outside the allocated
address space.
SunOS 5.8 Last change: 19 Apr 1999 8
Ioctl Requests streamio(7I)
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.
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 struc-
ture (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 speci-
fies 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 mes-
sages, I_FDINSERT will block if the
STREAM write queue is full due to internal
flow control conditions. For priority mes-
sages, I_FDINSERT does not block on this
condition. For non-priority messages,
I_FDINSERT does not block when the write
queue is full and O_NDELAY or O_NONBLOCK
SunOS 5.8 Last change: 19 Apr 1999 9
Ioctl Requests streamio(7I)
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
A non-priority message is
specified, the O_NDELAY or
O_NONBLOCK flag is set, and the
STREAM write queue is full due
to internal flow control condi-
tions.
ENOSR Buffers can not be allocated
for the message that is to be
created.
EFAULT
The arg argument points, or the
buffer area specified in ctlbuf
or databuf is, outside the
allocated address space.
EINVAL
One of the following: The
fildes member of the strfdin-
sert structure is not a valid,
open STREAM file descriptor;
the size of a t_uscalar_t plus
offset is greater than the len
member for the buffer specified
through ctlptr; the offset
member does not specify a
properly-aligned location in
the data buffer; or an unde-
fined value is stored in flags.
ENXIO Hangup received on the fildes
argument of the ioctl call or
the fildes member of the
strfdinsert structure.
ERANGE
SunOS 5.8 Last change: 19 Apr 1999 10
Ioctl Requests streamio(7I)
The len field for the buffer
specified through databuf does
not fall within the range
specified by the maximum and
minimum packet sizes of the
topmost STREAM module; or the
len member for the buffer
specified through databuf is
larger than the maximum config-
ured size of the data part of a
message; or the len member for
the buffer specified through
ctlbuf is larger than the max-
imum configured size of the
control part of a message.
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 Constructs an internal STREAMS ioctl
message from the data pointed to by
arg, and sends that message down-
stream.
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 ack-
nowledgement message, or until the
request "times out" after some
period of time. If the request times
out, it fails with errno set to
ETIME.
At most one I_STR can be active on a
stream. Further I_STR calls will
block until the active I_STR com-
pletes at the STREAM head. The
default timeout interval for these
requests is 15 seconds. The O_NDELAY
and O_NONBLOCK (see open(2)) flags
have no effect on this call.
SunOS 5.8 Last change: 19 Apr 1999 11
Ioctl Requests streamio(7I)
To send requests downstream, arg
must point to a strioctl structure
which contains the following
members:
int ic_cmd;
int ic_timeout;
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 acknowledge-
ment 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).
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 Unable to allocate
buffers for the ioctl
message due to insuffi-
cient STREAMS memory
resources.
EFAULT
Either arg points outside
the allocated address
space, or the buffer area
specified by ic_dp and
SunOS 5.8 Last change: 19 Apr 1999 12
Ioctl Requests streamio(7I)
ic_len (separately for
data sent and data
returned) is outside the
allocated address space.
EINVAL
ic_len is less than 0 or
ic_len is larger than the
maximum configured size
of the data part of a
message or ic_timout is
less than -1.
ENXIO Hangup received on
fildes.
ETIME A downstream ioctl timed
out before acknowledge-
ment 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 addi-
tion, an error code can be
returned in the positive or
negative acknowledgement mes-
sage, 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
Sets the write mode using the
value of the argument arg.
Legal bit settings for arg
are:
SNDZERO
Send a zero-length mes-
sage downstream when a
write of 0 bytes occurs.
To not send a zero-length message
when a write of 0 bytes occurs, this
bit must not be set in arg.
On failure, errno may be set
to the following value:
SunOS 5.8 Last change: 19 Apr 1999 13
Ioctl Requests streamio(7I)
EINVAL
arg is not the above
legal value.
I_GWROPT
Returns the current write mode
setting, as described above,
in the int that is pointed to
by the argument arg.
I_SENDFD
Requests the STREAM associated
with fildes to send a message,
containing a file pointer, to
the stream head at the other
end of a STREAM pipe. The file
pointer corresponds to arg,
which must be an open file
descriptor.
I_SENDFD converts arg into the
corresponding system file
pointer. It allocates a mes-
sage block and inserts the
file pointer in the block.
The user id and group id asso-
ciated with the sending pro-
cess 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
The sending STREAM is
unable to allocate a
message block to contain
the file pointer.
EAGAIN
The read queue of the
receiving STREAM head is
full and cannot accept
the message sent by
I_SENDFD.
EBADF arg is not a valid, open
file descriptor.
SunOS 5.8 Last change: 19 Apr 1999 14
Ioctl Requests streamio(7I)
EINVAL
fildes is not connected
to a STREAM pipe.
ENXIO Hangup received on
fildes.
I_RECVFD
Retrieves the file descriptor
associated with the message
sent by an 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;
gif_t gif;
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 struc-
ture. The structure is copied
into the user data buffer
pointed to by arg. On failure,
errno is set to one of the
following values:
SunOS 5.8 Last change: 19 Apr 1999 15
Ioctl Requests streamio(7I)
EAGAIN
A message is not
present at the
STREAM head read
queue, and the
O_NDELAY or
O_NONBLOCK flag is
set.
EBADMSG
The message at the
STREAM head read
queue is not a mes-
sage containing a
passed file
descriptor.
EFAULT
arg points outside
the allocated
address space.
EMFILE
NOFILES file
descriptors are
currently open.
ENXIO Hangup received on
fildes.
EOVERFLOW
uid or gid is too
large to be stored
in the structure
pointed to by arg.
I_LIST
Allows the user to list
all the module names on
the stream, up to and
including the topmost
driver name. If arg is
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-
SunOS 5.8 Last change: 19 Apr 1999 16
Ioctl Requests streamio(7I)
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 indi-
cates the
number of
entries the
process has
allocated in
the array.
Upon return,
the sl_modlist
member of the
str_list
structure con-
tains 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()
SunOS 5.8 Last change: 19 Apr 1999 17
Ioctl Requests streamio(7I)
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
The
sl_nmods
member
is less
than 1.
EAGAIN
Unable
to allo-
cate
buffers
I_ATMARK
Allows the
user to see
if the
current mes-
sage on the
stream head
read queue is
``marked'' by
some module
downstream.
arg deter-
mines how the
checking is
done when
SunOS 5.8 Last change: 19 Apr 1999 18
Ioctl Requests streamio(7I)
there may be
multiple
marked mes-
sages on the
STREAM head
read queue.
It may take
the following
values:
ANYMARK
Check
if the
message
is
marked.
LASTMARK
Check
if the
message
is the
last
one
marked
on the
queue.
The return
value is 1 if
the mark con-
dition is
satisfied and
0 otherwise.
On failure,
errno is set
to the fol-
lowing value:
EINVAL
Invalid
arg
value.
I_CKBAND
Check if the
message of a
given prior-
ity band
exists on the
SunOS 5.8 Last change: 19 Apr 1999 19
Ioctl Requests streamio(7I)
stream head
read queue.
This returns
1 if a mes-
sage of a
given prior-
ity exists, 0
if not, or -1
on error. arg
should be an
integer con-
taining the
value of the
priority band
in question.
On failure,
errno is set
to the fol-
lowing value:
EINVAL
Invalid
arg
value.
I_GETBAND
Returns the prior-
ity band of the
first message on
the STREAM head
read queue in the
integer referenced
by arg. On
failure, errno is
set to the follow-
ing value:
ENODATA
No message
on the
STREAM head
read queue.
I_CANPUT
Check if a certain
band is writable.
arg is set to the
priority band in
question. The
SunOS 5.8 Last change: 19 Apr 1999 20
Ioctl Requests streamio(7I)
return value is 0
if the priority
band arg is flow
controlled, 1 if
the band is writ-
able, or -1 on
error. On failure,
errno is set to
the following
value:
EINVAL
Invalid arg
value.
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 indepen-
dent of the STREAM
head's delay and
is not settable.
If, after the
delay, data are
still present,
data will be
flushed. arg is
the number of mil-
liseconds to
delay, rounded up
to the nearest
legal value on the
system. The
SunOS 5.8 Last change: 19 Apr 1999 21
Ioctl Requests streamio(7I)
default is fifteen
seconds. On
failure, errno is
set to the follow-
ing value:
EINVAL
Invalid arg
value.
I_GETCLTIME
Returns the close
time delay in the
integer pointed by
arg.
I_SERROPT
Sets the error
mode using the
value of the argu-
ment arg.
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
SunOS 5.8 Last change: 19 Apr 1999 22
Ioctl Requests streamio(7I)
side errors.
Legal arg values
are either none or
one of:
RERRNORM
Persistent
read errors,
the default.
RERRNONPERSIST
Non-
persistent
read errors.
OR'ed with either none
or one of:
WERRNORM
Persistent
write
errors, the
default.
WERRNONPERSIST
Non-
persistent
write
errors.
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 fol-
lowing value:
EINVAL
arg is not
one of the
SunOS 5.8 Last change: 19 Apr 1999 23
Ioctl Requests streamio(7I)
above legal
values.
I_GERROPT
Returns the current
error mode setting in an
int pointed to by the
argument arg. Error
modes are described
above for I_SERROPT. On
failure,errno is set to
the following value:
EFAULT
arg points outside
the allocated
address space.
The following four commands
are used for connecting and
disconnecting multiplexed
STREAMS configurations.
I_LINK
Connects two streams,
where fildes is the file
descriptor of the stream
connected to the multi-
plexing driver, and arg
is the file descriptor
of the STREAM connected
to another driver. The
STREAM designated by arg
gets connected below the
multiplexing driver.
I_LINK requires the mul-
tiplexing driver to send
an acknowledgement mes-
sage 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:
SunOS 5.8 Last change: 19 Apr 1999 24
Ioctl Requests streamio(7I)
ENXIO Hangup received on
fildes.
ETIME Time out before
acknowledgement
message was
received at STREAM
head.
EAGAIN
Temporarily unable
to allocate
storage to perform
the I_LINK.
ENOSR Unable to allocate
storage to perform
the I_LINK due to
insufficient
STREAMS memory
resources.
EBADF arg is not a
valid, open file
descriptor.
EINVAL
fildes STREAM does
not support multi-
plexing.
EINVAL
arg is not a
stream, or is
already linked
under a multi-
plexor.
EINVAL
The specified link
operation would
cause a ``cycle''
in the resulting
configuration;
that is, a driver
would be linked
into the multi-
plexing configura-
tion in more than
one place.
EINVAL
SunOS 5.8 Last change: 19 Apr 1999 25
Ioctl Requests streamio(7I)
fildes is the file
descriptor of a
pipe or FIFO.
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 acknowledge-
ment message. For these
cases, I_LINK will fail
with errno set to the
value in the message.
I_UNLINK
Disconnects the two
streams specified by
fildes and arg. fildes
is the file descriptor
of the STREAM connected
to the multiplexing
driver. arg is the mul-
tiplexor ID number that
was returned by the
I_LINK. If arg is -1,
then all streams that
were linked to fildes
are disconnected. As in
I_LINK, this command
requires the multiplex-
ing driver to ack-
nowledge the unlink. On
failure, errno is set to
one of the following
values:
ENXIO Hangup received on
fildes.
ETIME Time out before
acknowledgement
message was
received at STREAM
head.
SunOS 5.8 Last change: 19 Apr 1999 26
Ioctl Requests streamio(7I)
ENOSR Unable to allocate
storage to perform
the I_UNLINK due
to insufficient
STREAMS memory
resources.
EINVAL
arg is an invalid
multiplexor ID
number or fildes
is not the STREAM
on which the
I_LINK that
returned arg was
performed.
EINVAL
fildes is the file
descriptor of a
pipe or FIFO.
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 acknowledge-
ment message. For these
cases, I_UNLINK will
fail with errno set to
the value in the mes-
sage.
I_PLINK
Connects two streams,
where fildes is the file
descriptor of the stream
connected to the multi-
plexing driver, and arg
is the file descriptor
of the STREAM connected
to another driver. The
STREAM designated by arg
gets connected via a
persistent link below
SunOS 5.8 Last change: 19 Apr 1999 27
Ioctl Requests streamio(7I)
the multiplexing driver.
I_PLINK requires the
multiplexing driver to
send an acknowledgement
message to the STREAM
head regarding the link-
ing operation. This call
creates a persistent
link that continues to
exist even if the file
descriptor fildes asso-
ciated with the upper
STREAM to the multiplex-
ing driver is closed.
This call returns a mul-
tiplexor 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 Hangup received on
fildes.
ETIME Time out before
acknowledgement
message was
received at the
STREAM head.
EAGAIN
Unable to allocate
STREAMS storage to
perform the
I_PLINK.
EBADF arg is not a
valid, open file
descriptor.
EINVAL
fildes does not
support multiplex-
ing.
EINVAL
arg is not a
SunOS 5.8 Last change: 19 Apr 1999 28
Ioctl Requests streamio(7I)
STREAM or is
already linked
under a multi-
plexor.
EINVAL
The specified link
operation would
cause a ``cycle''
in the resulting
configuration;
that is, if a
driver would be
linked into the
multiplexing con-
figuration in more
than one place.
EINVAL
fildes is the file
descriptor of a
pipe or FIFO.
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 acknowledge-
ment message. For these
cases, I_PLINK will fail
with errno set to the
value in the message.
I_PUNLINK
Disconnects the two
streams specified by
fildes and arg that are
connected with a per-
sistent link. fildes is
the file descriptor of
the STREAM connected to
the multiplexing driver.
arg is the multiplexor
ID number that was
returned by I_PLINK when
SunOS 5.8 Last change: 19 Apr 1999 29
Ioctl Requests streamio(7I)
a STREAM was linked
below the multiplexing
driver. If arg is
MUXID_ALL then all
streams that are per-
sistent links to fildes
are disconnected. As in
I_PLINK, this command
requires the multiplex-
ing driver to ack-
nowledge the unlink. On
failure, errno is set to
one of the following
values:
ENXIO Hangup received on
fildes.
ETIME Time out before
acknowledgement
message was
received at the
STREAM head.
EAGAIN
Unable to allocate
buffers for the
acknowledgement
message.
EINVAL
Invalid multi-
plexor ID number.
EINVAL
fildes is the file
descriptor of a
pipe or FIFO.
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
SunOS 5.8 Last change: 19 Apr 1999 30
Ioctl Requests streamio(7I)
acknowledgement message.
For these cases,
I_PUNLINK will fail with
errno set to the value
in the message.
RETURN VALUES
Unless specified otherwise above, the return value from
ioctl() is 0 upon success and -1 upon failure, with errno
set as indicated.
SEE ALSO
intro(3), close(2), fcntl(2), getmsg(2), ioctl(2), open(2),
poll(2), putmsg(2), read(2), write(2), signal(3C),
signal(3HEAD), pipemod(7M)
STREAMS Programming Guide
SunOS 5.8 Last change: 19 Apr 1999 31
|
 |
|
|
