streamio(7) streamio(7)
NAME
streamio - STREAMS ioctl commands
SYNOPSIS
#include <sys/types.h>
#include <stropts.h>
int ioctl (int fildes, int command, ... /* arg */);
DESCRIPTION
STREAMS [see intro(2)] ioctl commands are a subset of the
ioctl(2) system calls which perform a variety of control
functions on streams.
fildes is an open file descriptor that refers to a stream.
command determines the control function to be performed as
described below. arg 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 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 a subset of ioctl, they are
subject to the errors described there. 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, 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.
Dynamically Loadable Modules
STREAMS modules and drivers may be dynamically loadable. If a
dynamically loadable module or driver is accessed via an
open() or an I_PUSH (streamio) and it is not currently present
in memory, then it is automatically loaded as a side effect of
the access. The loading process will bring the driver or
module into memory and call its load() routine to initialize
it. See modload(2), modadmin(1m).
Command Functions
The following ioctl commands, with error values indicated, are
applicable to all STREAMS files:
Copyright 1994 Novell, Inc. Page 1
streamio(7) streamio(7)
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.
ENOLOAD failure in loading a loadable exec
module
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.
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.
A #include <sys/conf.h> declaration is required.
On failure, errno is set to one of the following
values:
EFAULT arg points outside the allocated
address space.
Copyright 1994 Novell, Inc. Page 2
streamio(7) streamio(7)
EINVAL No module present in stream.
I_FLUSH This request flushes all input and/or output
queues, depending on the value of arg. Valid
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.
Copyright 1994 Novell, Inc. Page 3
streamio(7) streamio(7)
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 wants the
kernel to issue the SIGPOLL signal [see
signal(2)] 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, except where noted, 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
prior releases. This is set even
if the message is of zero length.
S_RDNORM An ordinary (non-priority) message
has arrived on a stream head read
queue. This is set 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 is set even if the
message is of zero length.
S_HIPRI A high priority message is present
on the stream head read queue.
This is set even if the message is
of zero length.
Copyright 1994 Novell, Inc. Page 4
streamio(7) streamio(7)
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 want 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.
Copyright 1994 Novell, Inc. Page 5
streamio(7) streamio(7)
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:
Copyright 1994 Novell, Inc. Page 6
streamio(7) streamio(7)
struct strbufctlbuf;
struct strbufdatabuf;
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 Invalid value for flags.
I_SRDOPT Sets the read mode [see read(2)] using the value
of the argument arg. Valid arg values are:
RNORM Byte-stream mode, the default.
RMSGD Message-discard mode.
RMSGN Message-nondiscard mode.
Setting both RMSGD and RMSGN is an error.
RMSGD and RMSGN override RNORM.
Copyright 1994 Novell, Inc. Page 7
streamio(7) streamio(7)
In addition, treatment of control messages by
the stream head may be changed by setting the
following flags in arg:
RPROTNORM Fail read with EBADMSG if a
control message is at the front of
the stream head read queue. This
is the default behavior.
RPROTDAT Deliver the control portion of a
message as data when a user issues
read.
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 valid
values.
EINVAL Both RMSGD and RMSGN are set.
I_GRDOPT Returns the current read mode setting in an int
pointed to by the argument arg. Read modes are
described in read(2). 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:
Copyright 1994 Novell, Inc. Page 8
streamio(7) streamio(7)
EFAULT arg points outside the allocated
address space.
I_FDINSERT Creates a message from user 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.
arg points to a strfdinsert structure which
contains the following members:
struct strbufctlbuf;
struct strbufdatabuf;
long flags;
int fildes;
int offset;
The len field in the ctlbuf strbuf structure
[see putmsg(2)] must be set to the size of a
pointer plus the number of bytes of control
information to be sent with the message. fildes
in the strfdinsert structure specifies the file
descriptor of the other stream. offset, which
must be word-aligned, specifies the number of
bytes beyond the beginning of the control buffer
where I_FDINSERT will store a pointer. This
pointer will be the address of the read queue
structure of the driver for the stream
corresponding to fildes in the strfdinsert
structure. The len field in the databuf strbuf
structure must be set to the number of bytes of
data information to be sent with the message or
zero if no data part is to be sent.
flags specifies the type of message to be
created. An ordinary (non-priority) message is
created if flags is set to 0, a high priority
message is created if flags is set to RS_HIPRI.
For normal messages, I_FDINSERT will block if
the stream write queue is full due to internal
flow control conditions. For high priority
messages, I_FDINSERT does not block on this
condition. For normal messages, I_FDINSERT does
not block when the write queue is full and
O_NDELAY or O_NONBLOCK is set. Instead, it
Copyright 1994 Novell, Inc. Page 9
streamio(7) streamio(7)
fails and sets errno to EAGAIN.
I_FDINSERT also blocks, unless prevented by lack
of internal resources, waiting for the
availability of message blocks, regardless of
priority or whether O_NDELAY or O_NONBLOCK has
been specified. No partial message is sent. On
failure, errno is set to one of the following
values:
EAGAIN A non-priority message was 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 could not be allocated for the
message that was to be created due to
insufficient STREAMS memory resources.
EFAULT arg points, or the buffer area specified
in ctlbuf or databuf is, outside the
allocated address space.
EINVAL One of the following: fildes in the
strfdinsert structure is not a valid,
open stream file descriptor; the size of
a pointer plus offset is greater than
the len field for the buffer specified
through ctlptr; offset does not specify
a properly-aligned location in the data
buffer; an undefined value is stored in
flags.
ENXIO Hangup received on fildes of the ioctl
call or fildes in 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 field for the
buffer specified through databuf is
larger than the maximum configured size
of the data part of a message, or the
len field for the buffer specified
Copyright 1994 Novell, Inc. Page 10
streamio(7) streamio(7)
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 fildes in 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.
At most, one I_STR can be active on a stream.
Further I_STR calls will block until the active
I_STR completes at the stream head. The default
timeout interval for these requests is 15
seconds. The O_NDELAY and O_NONBLOCK [see
open(2)] flags have no effect on this call.
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.
The default timeout is infinite. ic_len is the
Copyright 1994 Novell, Inc. Page 11
streamio(7) streamio(7)
number of bytes in the data argument and ic_dp
is a pointer to the data argument. The ic_len
field has two uses: on input, it contains the
length of the data argument passed in, and on
return from the command, it contains the number
of bytes being returned to the user (the buffer
pointed to by ic_dp should be large enough to
contain the maximum amount of data that any
module or the driver in the stream can return).
The stream head will convert the information
pointed to by the strioctl structure to an
internal ioctl command message and send it
downstream. On failure, errno is set to one of
the following values:
ENOSR Unable to allocate buffers for the
ioctl message due to insufficient
STREAMS memory resources.
EFAULT arg points, 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.
Copyright 1994 Novell, Inc. Page 12
streamio(7) streamio(7)
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 on pipes and FIFOs.
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 valid 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(2)] 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.
Copyright 1994 Novell, Inc. Page 13
streamio(7) streamio(7)
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;
char fill[8];
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.
Copyright 1994 Novell, Inc. Page 14
streamio(7) streamio(7)
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_S_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 s_strrecvfd data
structure containing the following members:
int fd;
uid_t uid;
gid_t gid;
struct sub_attr s_attrs;
fd is an integer file descriptor. uid and gid
are the user ID and group ID, respectively, of
the sending stream. sub_attr contains security
relevant information. The sub_attr structure is
used as an argument for the secadvise(2) system
call, which provides advisory access
information.
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
Copyright 1994 Novell, Inc. Page 15
streamio(7) streamio(7)
in the fd field of the s_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:
ENOMEM The system cannot allocate memory
for the s_strrecvfd structure.
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];
Copyright 1994 Novell, Inc. Page 16
streamio(7) streamio(7)
sl_nmods indicates the number of entries the
user has allocated in the array. On success,
the return value is 0, sl_modlist 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. 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.
The bitwise-OR of these flags is allowed. 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.
If both ANYMARK and LASTMARK are set, ANYMARK
supersedes LASTMARK.
The return value is 1 if the mark condition is
satisfied and 0 otherwise. On failure, errno
may be set to the following value:
EINVAL A value other than
(ANYMARK|LASTMARK) is set in arg.
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, or -1 on error. arg should be an
integer containing the value of the priority
band in question. On failure, errno may be set
to the following value:
Copyright 1994 Novell, Inc. Page 17
streamio(7) streamio(7)
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 may be 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 may be 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 is
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. If, after the delay, data is
still present, data will be flushed. arg is a
pointer to the number of milliseconds to delay,
rounded up to the nearest valid value on the
system. The default is fifteen seconds. On
failure, errno may be set to the following
value:
EINVAL Invalid arg value.
I_GETCLTIME Returns the close time delay in the long pointed
by arg.
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
Copyright 1994 Novell, Inc. Page 18
streamio(7) streamio(7)
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 a -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, if a given
driver is linked into a
multiplexing configuration in more
than one place.
EINVAL fildes is the file descriptor of a
pipe or FIFO.
An I_LINK can also fail while waiting for the
multiplexing driver to acknowledge the link
request, if a message indicating an error or a
hangup is received at the stream head of fildes.
Copyright 1994 Novell, Inc. Page 19
streamio(7) streamio(7)
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 which 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.
Copyright 1994 Novell, Inc. Page 20
streamio(7) streamio(7)
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
which can 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 a -1 on failure.
On failure, errno may be 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 given
stream head is linked into a
multiplexing configuration in more
than one place.
Copyright 1994 Novell, Inc. Page 21
streamio(7) streamio(7)
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 which are persistent
links to fildes are disconnected. As in
I_PLINK, this command requires the multiplexing
driver to acknowledge the unlink. On failure,
errno may be 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
Copyright 1994 Novell, Inc. Page 22
streamio(7) streamio(7)
with errno set to the value.
Return Values
Unless specified otherwise above, ioctl returns 0 on success
and -1 on failure and sets errno as indicated in the message.
REFERENCES
close(2), fcntl(2), getmsg(2), intro(2), ioctl(2), open(2),
poll(2), putmsg(2), read(2), signal(2), signal(5), write(2)
Copyright 1994 Novell, Inc. Page 23