Ioctl Requests streamio(7I)
NAME
streamio - STREAMS ioctl commands
SYNOPSIS
#include
#include
#include
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:
IPUSH 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
SunOS 5.11 Last change: 17 Nov 2005 1
Ioctl Requests streamio(7I)
then calls the open routine of the newly-
pushed module. On failure, errno is set to
one of the following values:
EINVAL Invalid module name.
EFAULT arg points outside the allocated
address space.
ENXIO Open routine of new module failed.
ENXIO Hangup received on fildes.
ENOTSUP Pushing a module is not supported
on this stream.
IPOP 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 IPOP 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 unprivileged process.
ENOTSUP Removal is not supported.
IANCHOR 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
IANCHOR request. On failure, errno is set to
the following value:
SunOS 5.11 Last change: 17 Nov 2005 2
Ioctl Requests streamio(7I)
EINVAL Request to put an anchor on a pipe.
ILOK 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 . On
failure, errno is set to one of the following
values:
EFAULT arg points outside the allocated
address space.
EINVAL No module present in stream.
IFLUSH 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.
SunOS 5.11 Last change: 17 Nov 2005 3
Ioctl Requests streamio(7I)
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 fol-
lowing values:
ENOSR Unable to allocate buffers for
flush message due to insufficient
STREAMS memory resources.
EINVAL Invalid arg value.
ENXIO Hangup received on fildes.
IFLUSHBAND Flushes a particular band of messages. arg
points to a bandinfo structure that has the
following members:
unsigned char bipri;
int biflag;
The biflag field may be one of FLUSHR,
FLUSHW, or FLUSHRW as described earlier.
ISETSIG Informs the STREAM head that the user wishes
the kernel to issue the SIGPOL signal (see
signal(3C)) when a particular event has
occurred on the STREAM associated with
fildes. ISETSIG 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 fol-
lowing constants:
SINPUT Any message other than an
MPCPROTO has arrived on a
STREAM head read queue. This
event is maintained for
SunOS 5.11 Last change: 17 Nov 2005 4
Ioctl Requests streamio(7I)
compatibility with previous
releases. This event is trig-
gered even if the message is of
zero length.
SRDNORM An ordinary (non-priority) mes-
sage has arrived on a STREAM
head read queue. This event is
triggered even if the message is
of zero length.
SRDBAND A priority band message (band >
0) has arrived on a stream head
read queue. This event is trig-
gered even if the message is of
zero length.
SHIPRI A high priority message is
present on the STREAM head read
queue. This event is triggered
even if the message is of zero
length.
SOUTPUT 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 down-
stream.
SWRNORM This event is the same as
SOUTPUT.
SWRBAND 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.
SMSG A STREAMS signal message that
contains the SIGPOL signal has
reached the front of the STREAM
head read queue.
SunOS 5.11 Last change: 17 Nov 2005 5
Ioctl Requests streamio(7I)
SEROR An MEROR message has reached
the STREAM head.
SHANGUP An MHANGUP message has reached
the STREAM head.
SBANDURG When used in conjunction with
SRDBAND, SIGURG is generated
instead of SIGPOL when a prior-
ity 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 SHIPRI.
Processes that wish to receive SIGPOL sig-
nals must explicitly register to receive them
using ISETSIG. If several processes register
to receive this signal for the same event on
the same stream, each process will be sig-
naled when the event occurs.
If the value of arg is zero, the calling pro-
cess will be unregistered and will not
receive further SIGPOL 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 SIGPOL signal.
EAGAIN Allocation of a data structure to
store the signal request failed.
IGETSIG Returns the events for which the calling pro-
cess is currently registered to be sent a
SIGPOL signal. The events are returned as a
bitmask pointed to by arg, where the events
are those specified in the description of
ISETSIG above. On failure, errno is set to
one of the following values:
EINVAL Process not registered to receive
the SIGPOL signal.
SunOS 5.11 Last change: 17 Nov 2005 6
Ioctl Requests streamio(7I)
EFAULT arg points outside the allocated
address space.
IFIND 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.
IPEK Allows a user to retrieve the information in
the first message on the STREAM head read
queue without taking the message off the
queue. IPEK 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 RSHIPRI or 0.
If RSHIPRI is set, IPEK will look for a
high priority message on the STREAM head read
queue. Otherwise, IPEK will look for the
first message on the STREAM head read queue.
IPEK 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 speci-
fies information in the control buffer, data-
buf specifies information in the data buffer,
and flags contains the value RSHIPRI or 0.
On failure, errno is set to the following
SunOS 5.11 Last change: 17 Nov 2005 7
Ioctl Requests streamio(7I)
value:
EFAULT arg points, or the buffer area
specified in ctlbuf or databuf is,
outside the allocated address
space.
EBADMSG Queued message to be read is not
valid for IPEK.
EINVAL Illegal value for flags.
ENOSR Unable to allocate buffers to per-
form the IPEK due to insuffi-
cient STREAMS memory resources.
ISRDOPT 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
control messages may be changed by setting
the following flags in arg:
RPROTNORM Reject read() with EBADMSG if a
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
portion, when a user issues a
read().
SunOS 5.11 Last change: 17 Nov 2005 8
Ioctl Requests streamio(7I)
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.
IGRDOPT 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.
INREAD 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 fol-
lowing value:
EFAULT arg points outside the allocated
address space.
IFDINSERT 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;
tuscalart flags;
int fildes;
SunOS 5.11 Last change: 17 Nov 2005 9
Ioctl Requests streamio(7I)
int offset;
The len member in the ctlbuf strbuf structure
(see putmsg(2)) must be set to the size of a
tuscalart plus the number of bytes of con-
trol information to be sent with the message.
The fildes member specifies the file descrip-
tor of the other STREAM, and the offset
member, which must be suitably aligned for
use as a tuscalart, specifies the offset
from the start of the control buffer where
IFDINSERT will store a tuscalart whose
interpretation is specific to the STREAM end.
The len member in the databuf strbuf struc-
ture 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 mes-
sage 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 RSHIPRI. For non-priority messages,
IFDINSERT will block if the STREAM write
queue is full due to internal flow control
conditions. For priority messages,
IFDINSERT does not block on this condition.
For non-priority messages, IFDINSERT does
not block when the write queue is full and
ONDELAY or ONONBLOCK is set. Instead, it
fails and sets errno to EAGAIN.
IFDINSERT also blocks, unless prevented by
lack of internal resources, waiting for the
availability of message blocks in the STREAM,
regardless of priority or whether ONDELAY or
ONONBLOCK has been specified. No partial
message is sent.
The ioctl() function with the IFDINSERT com-
mand will fail if:
EAGAIN A non-priority message is speci-
fied, the ONDELAY or ONONBLOCK
flag is set, and the STREAM write
queue is full due to internal flow
control conditions.
ENOSR Buffers can not be allocated for
the message that is to be created.
SunOS 5.11 Last change: 17 Nov 2005 10
Ioctl Requests streamio(7I)
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 strfdinsert structure
is not a valid, open STREAM file
descriptor; the size of a
tuscalart 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 undefined value
is stored in flags.
ENXIO Hangup received on the fildes argu-
ment of the ioctl call or the
fildes member of the strfdinsert
structure.
ERANGE The len field for the buffer speci-
fied 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 configured size of the data
part of a message; or the len
member for the buffer specified
through ctlbuf is larger than the
maximum configured size of the con-
trol part of a message.
IFDINSERT 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.
ISTR Constructs an internal STREAMS ioctl message
from the data pointed to by arg, and sends
that message downstream.
This mechanism is provided to send user ioctl
requests to downstream modules and drivers.
SunOS 5.11 Last change: 17 Nov 2005 11
Ioctl Requests streamio(7I)
It allows information to be sent with the
ioctl, and will return to the user any infor-
mation sent upstream by the downstream reci-
pient. ISTR 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.
To send requests downstream, arg must point
to a strioctl structure which contains the
following members:
int iccmd;
int ictimout;
int iclen;
char *icdp;
iccmd is the internal ioctl command intended
for a downstream module or driver and
ictimout is the number of seconds (-1 =
infinite, 0 = use default, >0 = as specified)
an ISTR request will wait for acknowledge-
ment before timing out. iclen is the number
of bytes in the data argument and icdp is a
pointer to the data argument. The iclen
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 icdp 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 ISTR can be active on a stream.
Further ISTR calls will block until the
active ISTR completes via a positive or
negative acknowlegment, a timeout, or an
error condition at the STREAM head. By set-
ting the ictimout 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 ONDELAY and ONONBLOCK
(see open(2)) flags have no effect on this
call.
SunOS 5.11 Last change: 17 Nov 2005 12
Ioctl Requests streamio(7I)
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 insufficient
STREAMS memory resources.
EFAULT Either arg points outside the allo-
cated address space, or the buffer
area specified by icdp and iclen
(separately for data sent and data
returned) is outside the allocated
address space.
EINVAL iclen is less than 0 or iclen is
larger than the maximum configured
size of the data part of a message
or ictimout is less than -1.
ENXIO Hangup received on fildes.
ETIME A downstream ioctl timed out before
acknowledgement was received.
An ISTR 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 ack-
nowledgement message, in the event the ioctl
command sent downstream fails. For these
cases, ISTR will fail with errno set to the
value in the message.
ISWROPT Sets the write mode using the value of the
argument arg. Legal bit settings for arg are:
SNDZERO Send a zero-length message down-
stream 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.
SunOS 5.11 Last change: 17 Nov 2005 13
Ioctl Requests streamio(7I)
On failure, errno may be set to the following
value:
EINVAL arg is not the above legal value.
IGWROPT Returns the current write mode setting, as
described above, in the int that is pointed
to by the argument arg.
ISENDFD 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.
ISENDFD 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 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
ISENDFD.
EBADF arg is not a valid, open file
descriptor.
EINVAL fildes is not connected to a STREAM
pipe.
ENXIO Hangup received on fildes.
SunOS 5.11 Last change: 17 Nov 2005 14
Ioctl Requests streamio(7I)
IRECVFD Retrieves the file descriptor associated with
the message sent by an ISENDFD 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;
uidt uid;
gidt gid;
fd is an integer file descriptor. uid and gid
are the user id and group id, respectively,
of the sending stream.
If ONDELAY and ONONBLOCK are clear (see
open(2)), IRECVFD will block until a message
is present at the STREAM head. If ONDELAY or
ONONBLOCK is set, IRECVFD 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 mes-
sage sent by an ISENDFD, 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 fol-
lowing values:
EAGAIN A message is not present at the
STREAM head read queue, and the
ONDELAY or ONONBLOCK flag is
set.
EBADMSG The message at the STREAM head
read queue is not a message con-
taining a passed file descrip-
tor.
EFAULT arg points outside the allocated
address space.
EMFILE NOFILES file descriptors are
currently open.
SunOS 5.11 Last change: 17 Nov 2005 15
Ioctl Requests streamio(7I)
ENXIO Hangup received on fildes.
EOVERFLOW uid or gid is too large to be
stored in the structure pointed
to by arg.
ILIST Allows the user to list all the module names
on the stream, up to and including the top-
most driver name. If arg is NUL, 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 strlist
structure that has the following members:
int slnmods;
struct strmlist *slmodlist;
The strmlist structure has the following
member:
char lname[FMNAMESZ]1];
The slnmods member indicates the number of
entries the process has allocated in the
array. Upon return, the slmodlist member of
the strlist structure contains the list of
module names, and the number of entries that
have been filled into the slmodlist array is
found in the slnmods 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 (slnmods) is
satisfied. On failure, errno may be set to
one of the following values:
EINVAL The slnmods member is less than 1.
EAGAIN Unable to allocate buffers
IATMARK Allows the user to see if the current message
on the stream head read queue is ``marked''
SunOS 5.11 Last change: 17 Nov 2005 16
Ioctl Requests streamio(7I)
by some module downstream. arg determines how
the checking is done when there may be multi-
ple marked messages 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 condition
is satisfied and 0 otherwise. On failure,
errno is set to the following value:
EINVAL Invalid arg value.
ICKBAND Check if the message of a given priority band
exists on the stream head read queue. This
returns 1 if a message of a given priority
exists, 0 if not, or -1 on error. arg should
be an integer containing the value of the
priority band in question. On failure, errno
is set to the following value:
EINVAL Invalid arg value.
IGETBAND Returns the priority band of the first mes-
sage on the STREAM head read queue in the
integer referenced by arg. On failure, errno
is set to the following value:
ENODATA No message on the STREAM head read
queue.
ICANPUT Check if a certain band is writable. arg is
set to the priority band in question. The
return value is 0 if the priority band arg is
flow controlled, 1 if the band is writable,
or -1 on error. On failure, errno is set to
the following value:
EINVAL Invalid arg value.
SunOS 5.11 Last change: 17 Nov 2005 17
Ioctl Requests streamio(7I)
ISETCLTIME 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, how-
ever, 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. 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, errno
is set to the following value:
EINVAL Invalid arg value.
IGETCLTIME Returns the close time delay in the integer
pointed by arg.
ISEROPT Sets the error mode using the value of the
argument arg.
Normally STREAM head errors are persistent;
once they are set due to an MEROR or
MHANGUP, 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:
RERNORM Persistent read errors, the
default.
RERNONPERSIST Non-persistent read errors.
OR'ed with either none or one of:
WERNORM Persistent write errors,
the default.
SunOS 5.11 Last change: 17 Nov 2005 18
Ioctl Requests streamio(7I)
WERNONPERSIST 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 following
value:
EINVAL arg is not one of the above legal
values.
IGEROPT Returns the current error mode setting in an
int pointed to by the argument arg. Error
modes are described above for ISEROPT. 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.
ILINK Connects two streams, where fildes is the file
descriptor of the stream connected to the mul-
tiplexing driver, and arg is the file descrip-
tor of the STREAM connected to another driver.
The STREAM designated by arg gets connected
below the multiplexing driver. ILINK requires
the multiplexing driver to send an acknowledge-
ment message to the STREAM head regarding the
linking operation. This call returns a multi-
plexor ID number (an identifier used to discon-
nect the multiplexor, see IUNLINK) 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 mes-
sage was received at STREAM head.
SunOS 5.11 Last change: 17 Nov 2005 19
Ioctl Requests streamio(7I)
EAGAIN Temporarily unable to allocate
storage to perform the ILINK.
ENOSR Unable to allocate storage to perform
the ILINK 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 multiplexor.
EINVAL The specified link operation would
cause a ``cycle'' in the resulting
configuration; that is, a driver
would be linked into the multiplexing
configuration in more than one place.
EINVAL fildes is the file descriptor of a
pipe or FIFO.
EINVAL Either the upper or lower stream has
a major number >= the maximum major
number on the system.
An ILINK 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 ack-
nowledgement message. For these cases, ILINK
will fail with errno set to the value in the
message.
IUNLINK 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 multiplexor ID number that was
returned by the ILINK. If arg is -1, then all
SunOS 5.11 Last change: 17 Nov 2005 20
Ioctl Requests streamio(7I)
streams that were linked to fildes are discon-
nected. As in ILINK, this command requires
the multiplexing driver to acknowledge the
unlink. On failure, errno is set to one of the
following values:
ENXIO Hangup received on fildes.
ETIME Time out before acknowledgement mes-
sage was received at STREAM head.
ENOSR Unable to allocate storage to perform
the IUNLINK due to insufficient
STREAMS memory resources.
EINVAL arg is an invalid multiplexor ID
number or fildes is not the STREAM on
which the ILINK that returned arg
was performed.
EINVAL fildes is the file descriptor of a
pipe or FIFO.
An IUNLINK 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 ack-
nowledgement message. For these cases,
IUNLINK will fail with errno set to the value
in the message.
IPLINK Connects two streams, where fildes is the file
descriptor of the stream connected to the mul-
tiplexing driver, and arg is the file descrip-
tor of the STREAM connected to another driver.
The STREAM designated by arg gets connected via
a persistent link below the multiplexing
driver. IPLINK requires the multiplexing
driver to send an acknowledgement message to
the STREAM head regarding the linking opera-
tion. 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
SunOS 5.11 Last change: 17 Nov 2005 21
Ioctl Requests streamio(7I)
that may be used to disconnect the multiplexor,
see IPUNLINK) on success, and -1 on failure.
On failure, errno is set to one of the follow-
ing values:
ENXIO Hangup received on fildes.
ETIME Time out before acknowledgement mes-
sage was received at the STREAM head.
EAGAIN Unable to allocate STREAMS storage to
perform the IPLINK.
EBADF arg is not a valid, open file
descriptor.
EINVAL fildes does not support multiplexing.
EINVAL arg is not a STREAM or is already
linked under a multiplexor.
EINVAL The specified link operation would
cause a ``cycle'' in the resulting
configuration; that is, if a driver
would be linked into the multiplexing
configuration in more than one place.
EINVAL fildes is the file descriptor of a
pipe or FIFO.
An IPLINK 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 ack-
nowledgement message. For these cases, IPLINK
will fail with errno set to the value in the
message.
IPUNLINK Disconnects the two streams specified by fildes
and arg that are connected with a persistent
link. fildes is the file descriptor of the
STREAM connected to the multiplexing driver.
SunOS 5.11 Last change: 17 Nov 2005 22
Ioctl Requests streamio(7I)
arg is the multiplexor ID number that was
returned by IPLINK when a STREAM was linked
below the multiplexing driver. If arg is
MUXIDAL then all streams that are persistent
links to fildes are disconnected. As in
IPLINK, this command requires the multiplexing
driver to acknowledge the unlink. On failure,
errno is set to one of the following values:
ENXIO Hangup received on fildes.
ETIME Time out before acknowledgement mes-
sage was received at the STREAM head.
EAGAIN Unable to allocate buffers for the
acknowledgement message.
EINVAL Invalid multiplexor ID number.
EINVAL fildes is the file descriptor of a
pipe or FIFO.
An IPUNLINK 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 ack-
nowledgement message. For these cases,
IPUNLINK 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.h(3HEAD),
STREAMS Programming Guide
SunOS 5.11 Last change: 17 Nov 2005 23
|
