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:
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
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.
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 ker-
nel to issue the SIGPOLL signal (see signal(3C)) when
a particular event has occurred on the STREAM associ-
ated 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 main-
tained 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 trig-
gered 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 trig-
gered 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 that there
is room on the queue for sending (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 down-
stream exists and is writable. This notifies
the user that there is room on the queue for
sending (or writing) priority data downstream.
S_MSG A STREAMS signal message that contains the SIG-
POLL 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 prior-
ity messages by setting the arg bitmask to the value
S_HIPRI.
Processes that wish to receive SIGPOLL signals must expli-
citly 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 fol-
lowing values:
EINVAL
arg value is invalid or arg is zero and process
is not registered to receive the SIGPOLL signal.
EAGAIN
Allocation of a data structure to store the sig-
nal 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 descrip-
tion of I_SETSIG above. On failure, errno is set to
one of the following values:
EINVAL
Process not registered to receive the SIGPOLL
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;
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 informa-
tion, 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 information 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 specified 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 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().
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 mes-
sages 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.
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 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. For 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
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 conditions.
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
strfdinsert 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 strfdin-
sert structure.
ERANGE
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 configured 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 correspond-
ing 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 informa-
tion 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 ack-
nowledgement 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 com-
pletes via a positive or negative acknowlegment, a
timeout, or an error condition at the STREAM head. By
setting the ic_timout
field to 0, the user is requesting STREAMS to pro-
vide 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 com-
mand 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 allocated address
space, or the buffer area specified by ic_dp and
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 ack-
nowledgement 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 com-
mand 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 message 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:
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 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 mes-
sage 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.
EINVAL
fildes is not connected to a STREAM pipe.
ENXIO Hangup received on fildes.
I_RECVFD
Retrieves the file descriptor associated with the mes-
sage 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;
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 mes-
sage 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
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 message 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-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 down-
stream until either the end of the STREAM is reached,
or the number of requested modules (sl_nmods) is satis-
fied. On failure, errno may be set to one of the fol-
lowing values:
EINVAL
The sl_nmods member is less than 1.
EAGAIN
Unable to allocate buffers
I_ATMARK
Allows the user to see if the current message on the
stream head read queue is ``marked'' by some module
downstream. arg determines how the checking is done
when there may be multiple marked messages on the
STREAM head read queue. It may take the following
values:
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 satis-
fied and 0 otherwise. On failure, errno is set to the
following value:
EINVAL
Invalid arg value.
I_CKBAND
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.
I_GETBAND
Returns the priority band of the first message 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.
I_CANPUT
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.
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 rou-
tine; 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 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 fol-
lowing 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 argument
arg.
Normally STREAM head errors are persistent; once they
are set due to an M_ERROR or M_HANGUP, the error con-
dition 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 con-
dition will be cleared. The error mode can be con-
trolled independently for read and write 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 following value:
EINVAL
arg is not one of the 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 multiplexing
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 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 multi-
plexor, see I_UNLINK) 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 STREAM head.
EAGAIN
Temporarily unable to allocate storage to per-
form 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 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, a driver would be linked into the multiplex-
ing 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 sys-
tem.
An I_LINK can also fail while waiting for the multi-
plexing 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, 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 con-
nected to the multiplexing driver. arg is the multi-
plexor 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 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 message was
received at STREAM head.
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 mul-
tiplexing 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, I_UNLINK will
fail with errno set to the value in the message.
I_PLINK
Connects two streams, where fildes is the file
descriptor of the stream connected to the multiplexing
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 the
multiplexing driver. 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 identif-
ier 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 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 multi-
plexing configuration 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
acknowledgement 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 persistent 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 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 follow-
ing 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 acknowledge-
ment message.
EINVAL
Invalid multiplexor ID number.
EINVAL
fildes is the file descriptor of a pipe or FIFO.
An I_PUNLINK can also fail while waiting for the mul-
tiplexing 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, 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),
STREAMS Programming Guide
Man(1) output converted with
man2html