man/man7i/streamio.7i

     te
 Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
 Copyright 1989 AT&T
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
 See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
 the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 STREAMIO 7I "Apr 8, 2009"
 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 argument represents additional information that
is needed by this command. The type of arg depends upon the command, but
it is generally an integer or a pointer to a command-specific data structure.
The command and arg arguments are interpreted by the STREAM head.
Certain combinations of these arguments may be passed to a module or driver in
the stream.

Since these STREAMS commands are ioctls, they are subject to the errors
described in ioctl(2). In addition to those errors, the call will fail
with errno set to EINVAL, without processing a control function, if
the STREAM referenced by fildes is linked below a multiplexor, or if
command is not a valid value for a stream.

Also, as described in ioctl(2), STREAMS modules and drivers can detect
errors. In this case, the module or driver sends an error message to the STREAM
head containing an error value. This causes subsequent calls to fail with
errno set to this value.
 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.


ENOTSUP

Pushing a module is not supported on this stream.


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 following
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.


I_ANCHOR

Positions the stream anchor to be at the stream's 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 following 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 stream 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 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 combination 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 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 downstream 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 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

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 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 information, respectively, to retrieve. flags may
be set to RS_HIPRI or 0. If RS_HIPRI is set, I_PEEK
will look for a high priority message on the stream head read queue. Otherwise,
I_PEEK will look for the first message on the stream head read queue.
I_PEEK returns 1 if a message was retrieved, and returns 0 if
no message was found on the stream head read queue. It does not wait for a
message to arrive. On return, ctlbuf specifies information in the control
buffer, databuf specifies information in the data buffer, and flags
contains the value RS_HIPRI or 0. On failure, errno is set to
the following value:
EFAULT

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.


ENOSR

Unable to allocate buffers to perform the I_PEEK due to insufficient STREAMS
memory resources.


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 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.


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 undefined 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

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 maximum 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 downstream.
This mechanism is provided to send user ioctl requests to downstream
modules and drivers. It allows information to be sent with the ioctl, and
will return to the user any information sent upstream by the downstream
recipient. I_STR blocks until the system responds with either a positive
or negative acknowledgement message, or until the request times out after some
period of time. If the request times out, it fails with errno set to
ETIME.
To send requests downstream, arg must point to a strioctl structure
which contains the following members:
int ic_cmd;
int ic_timout;
int ic_len;
char *ic_dp;


ic_cmd is the internal ioctl command intended for a downstream
module or driver and ic_timout is the number of seconds (-1 = infinite, 0
= use default, >0 = as specified) an I_STR request will wait for
acknowledgement before timing out. ic_len is the number of bytes in the
data argument and ic_dp is a pointer to the data argument. The
ic_len field has two uses: on input, it contains the length of the data
argument passed in, and on return from the command, it contains the number of
bytes being returned to the user (the buffer pointed to by ic_dp should
be large enough to contain the maximum amount of data that any module or the
driver in the stream can return).
At most one I_STR can be active on a stream. Further I_STR calls
will block until the active I_STR completes via a positive or negative
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 provide
the DEFAULT timeout. The default timeout is specific to the STREAMS
implementation and may vary depending on which release of Solaris you are
using. For Solaris 8 (and earlier versions), the default timeout is fifteen
seconds. The O_NDELAY and O_NONBLOCK (see open(2)) flags have
no effect on this call.
The stream head will convert the information pointed to by the strioctl
structure to an internal ioctl command message and send it downstream. On
failure, errno is set to one of the following values:
ENOSR

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 acknowledgement was received.


An I_STR can also fail while waiting for an acknowledgement if a message
indicating an error or a hangup is received at the stream head. In addition, an
error code can be returned in the positive or negative acknowledgement message,
in the event the ioctl command sent downstream fails. For these cases,
I_STR will fail with errno set to the value in the message.


I_SWROPT

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 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.


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;
gid_t gid;


fd is an integer file descriptor. uid and gid are the user id
and group id, respectively, of the sending stream.
If O_NDELAY and O_NONBLOCK are clear (see open(2)),
I_RECVFD will block until a message is present at the stream head. If
O_NDELAY or O_NONBLOCK is set, I_RECVFD will fail with
errno set to EAGAIN if no message is present at the stream head.
If the message at the stream head is a message sent by an I_SENDFD, a new
user file descriptor is allocated for the file pointer contained in the
message. The new file descriptor is placed in the fd field of the
strrecvfd structure. The structure is copied into the user data buffer
pointed to by arg. On failure, errno is set to one of the following
values:
EAGAIN

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 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 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 satisfied 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 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.


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 condition will remain until the
stream is closed. This option can be used to set the stream head into
non-persistent error mode i.e. once the error has been returned in response to
a read(2), getmsg(2), ioctl(2), write(2), or
putmsg(2) call the error condition will be cleared. The error mode can be
controlled independently for read and write side errors. Legal arg values
are either none or one of:
RERRNORM

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 multiplexor, 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 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 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 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 I_LINK can also fail while waiting for the multiplexing driver to
acknowledge the link request, if a message indicating an error or a hangup is
received at the stream head of fildes. In addition, an error code can be
returned in the positive or negative acknowledgement message. For these cases,
I_LINK will fail with errno set to the value in the message.


I_UNLINK

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
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 multiplexing driver to
acknowledge the link request, if a message indicating an error or a hangup is
received at the stream head of fildes. In addition, an error code can be
returned in the positive or negative acknowledgement message. For these cases,
I_UNLINK will fail with errno set to the value in the message.


I_PLINK

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 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 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 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 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 multiplexor 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 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.h(3HEAD),

STREAMS Programming Guide