streamio(HW)

streamio -- STREAMS ioctl commands

Synopsis

#include <sys/types.h>
#include <stropts.h>

int ioctl (int fildes, int command, ... /* arg */);

Description

STREAMS (see intro(S)) ioctl commands are a subset of the ioctl(S) 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(S), 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(S) and modadmin(ADM)).

Command functions

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.
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.
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.
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(S)) 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.
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.

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(S) 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(S)) 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(S)) 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.

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(S). 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 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 strbuf	ctlbuf;
   struct strbuf	databuf;
   long	flags;
   int	fildes;
   int	offset;

The len field in the ctlbuf strbuf structure (see putmsg(S)) 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 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 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(S)) 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 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.

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(S)) 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;
   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(S)) 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_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(S) system call, which provides advisory access information.

If O_NDELAY and O_NONBLOCK are clear (see open(S)), 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 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];

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:

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

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.
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 with errno set to the value.

Unless specified otherwise above, ioctl returns 0 on success and -1 on failure and sets errno as indicated in the message.

References

close(S), fcntl(S), getmsg(S), Intro(S), Intro(MDI), ioctl(S), open(S), poll(S), putmsg(S), read(S), signal(S), signal(M), write(S)