|
Ioctl Requests | streamio(7I) |
| streamio - STREAMS ioctl commands |
SYNOPSIS
|
#include <sys/types.h>
#include <stropts.h>
#include <sys/conf.h> int ioctl(int fildes, int command, ... /*arg*/); |
|
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.
|
|
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 following 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 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 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 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.
-
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:
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
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.
|
|
Unless specified otherwise above, the return value from ioctl() is 0 upon success and -1
upon failure, with errno set as indicated.
|
|
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
|
| |