STREAMIO(7I) Ioctl Requests STREAMIO(7I) NNAAMMEE ssttrreeaammiioo - STREAMS ioctl commands SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t iiooccttll(_i_n_t _f_i_l_d_e_s, _i_n_t _c_o_m_m_a_n_d, _._._. _/_*_a_r_g_*_/); DDEESSCCRRIIPPTTIIOONN STREAMS (see Intro(3)) iiooccttll() commands are a subset of the ioctl(2) commands and perform a variety of control functions on streams. The _f_i_l_d_e_s argument is an open file descriptor that refers to a stream. The _c_o_m_m_a_n_d argument determines the control function to be performed as described below. The _a_r_g argument represents additional information that is needed by this command. The type of _a_r_g depends upon the command, but it is generally an integer or a pointer to a command-specific data structure. The _c_o_m_m_a_n_d and _a_r_g 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 iiooccttllss, they are subject to the errors described in ioctl(2). In addition to those errors, the call will fail with _e_r_r_n_o set to EINVAL, without processing a control function, if the STREAM referenced by _f_i_l_d_e_s is linked below a multiplexor, or if _c_o_m_m_a_n_d 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 _e_r_r_n_o set to this value. IIOOCCTTLLSS The following iiooccttll() commands, with error values indicated, are applicable to all STREAMS files: I_PUSH Pushes the module whose name is pointed to by _a_r_g 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, _e_r_r_n_o is set to one of the following values: EINVAL Invalid module name. EFAULT _a_r_g points outside the allocated address space. ENXIO Open routine of new module failed. ENXIO Hangup received on _f_i_l_d_e_s. ENOTSUP Pushing a module is not supported on this stream. I_POP Removes the module just below the STREAM head of the STREAM pointed to by _f_i_l_d_e_s. To remove a module from a pipe requires that the module was pushed on the side it is being removed from. _a_r_g should be 00 in an I_POP request. On failure, _e_r_r_n_o is set to one of the following values: EINVAL No module present in the stream. ENXIO Hangup received on _f_i_l_d_e_s. EPERM Attempt to pop through an anchor by an unprivileged process. ENOTSUP Removal is not supported. I_ANCHOR Positions the stream anchor to be at the stream's module directly below the stream head. Once this has been done, only a privileged process may pop modules below the anchor on the stream. _a_r_g must be 00 in an I_ANCHOR request. On failure, _e_r_r_n_o 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 _f_i_l_d_e_s, and places it in a null terminated character string pointed at by _a_r_g. The buffer pointed to by _a_r_g should be at least FMNAMESZ+1 bytes long. This requires the declaration `#include '. On failure, errno is set to one of the following values: EFAULT _a_r_g 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 _a_r_g. Legal _a_r_g 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 _a_r_g. If FLUSHR is set and _f_i_l_d_e_s 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 _f_i_l_d_e_s is a FIFO, both queues are flushed. If FLUSHW is set and _f_i_l_d_e_s 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 _f_i_l_d_e_s 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 ppiippeemmoodd 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, _e_r_r_n_o is set to one of the following values: ENOSR Unable to allocate buffers for flush message due to insufficient stream memory resources. EINVAL Invalid _a_r_g value. ENXIO Hangup received on _f_i_l_d_e_s. I_FLUSHBAND Flushes a particular band of messages. _a_r_g points to a _b_a_n_d_i_n_f_o structure that has the following members: unsigned char bi_pri; int bi_flag; The _b_i___f_l_a_g 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 _f_i_l_d_e_s. I_SETSIG supports an asynchronous processing capability in streams. The value of _a_r_g 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 _a_r_g 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 _a_r_g is zero, the calling process will be unregistered and will not receive further SIGPOLL signals. On failure, _e_r_r_n_o is set to one of the following values: EEIINNVVAALL _a_r_g value is invalid or _a_r_g is zero and process is not registered to receive the SIGPOLL signal. EEAAGGAAIINN 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 _a_r_g, where the events are those specified in the description of I_SETSIG above. On failure, _e_r_r_n_o is set to one of the following values: EEIINNVVAALL Process not registered to receive the SIGPOLL signal. EEFFAAUULLTT _a_r_g 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 _a_r_g, and returns 1 if the named module is present in the stream. It returns 0 if the named module is not present. On failure, _e_r_r_n_o is set to one of the following values: EEFFAAUULLTT _a_r_g points outside the allocated address space. EEIINNVVAALL _a_r_g 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. _a_r_g points to a _s_t_r_p_e_e_k structure, which contains the following members: struct strbuf ctlbuf; struct strbuf databuf; long flags; The _m_a_x_l_e_n field in the _c_t_l_b_u_f and _d_a_t_a_b_u_f _s_t_r_b_u_f structures (see getmsg(2)) must be set to the number of bytes of control information and/or data information, respectively, to retrieve. _f_l_a_g_s may be set to RS_HIPRI or 00. 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 11 if a message was retrieved, and returns 00 if no message was found on the stream head read queue. It does not wait for a message to arrive. On return, _c_t_l_b_u_f specifies information in the control buffer, _d_a_t_a_b_u_f specifies information in the data buffer, and _f_l_a_g_s contains the value RS_HIPRI or 00. On failure, _e_r_r_n_o is set to the following value: EFAULT _a_r_g points, or the buffer area specified in _c_t_l_b_u_f or _d_a_t_a_b_u_f is, outside the allocated address space. EBADMSG Queued message to be read is not valid for I_PEEK. EINVAL Illegal value for _f_l_a_g_s. ENOSR Unable to allocate buffers to perform the I_PEEK due to insufficient STREAMS memory resources. I_SRDOPT Sets the read mode (see read(2)) using the value of the argument _a_r_g. Legal _a_r_g 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 _a_r_g: RPROTNORM Reject read(2) 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(2). This is the default behavior. RPROTDIS Discard the control portion of a message, delivering any data portion, when a user issues a read(2). On failure, _e_r_r_n_o is set to the following value: EINVAL _a_r_g is not one of the above legal values, or _a_r_g is the bitwise inclusive OORR of RMSGD and RMSGN. I_GRDOPT Returns the current read mode setting in an _i_n_t pointed to by the argument _a_r_g. Read modes are described in read(2). On failure, _e_r_r_n_o is set to the following value: EFAULT _a_r_g 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 _a_r_g. The return value for the command is the number of messages on the stream head read queue. For example, if zero is returned in _a_r_g, but the iiooccttll() return value is greater than zero, this indicates that a zero-length message is next on the queue. On failure, _e_r_r_n_o is set to the following value: EFAULT _a_r_g 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 _a_r_g argument points to a _s_t_r_f_d_i_n_s_e_r_t structure, which contains the following members: struct strbuf ctlbuf; struct strbuf databuf; t_uscalar_t flags; int fildes; int offset; The _l_e_n member in the _c_t_l_b_u_f _s_t_r_b_u_f structure (see putmsg(2)) must be set to the size of a _t___u_s_c_a_l_a_r___t plus the number of bytes of control information to be sent with the message. The _f_i_l_d_e_s member specifies the file descriptor of the other stream, and the _o_f_f_s_e_t member, which must be suitably aligned for use as a _t___u_s_c_a_l_a_r___t, specifies the offset from the start of the control buffer where I_FDINSERT will store a _t___u_s_c_a_l_a_r___t whose interpretation is specific to the stream end. The _l_e_n member in the _d_a_t_a_b_u_f _s_t_r_b_u_f 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 _f_l_a_g_s member specifies the type of message to be created. A normal message is created if _f_l_a_g_s is set to 0, and a high-priority message is created if _f_l_a_g_s 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. or 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 _e_r_r_n_o 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 iiooccttll() 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 _a_r_g argument points, or the buffer area specified in _c_t_l_b_u_f or _d_a_t_a_b_u_f is, outside the allocated address space. EINVAL One of the following: The _f_i_l_d_e_s member of the _s_t_r_f_d_i_n_s_e_r_t structure is not a valid, open stream file descriptor; the size of a _t___u_s_c_a_l_a_r___t plus _o_f_f_s_e_t is greater than the _l_e_n member for the buffer specified through _c_t_l_p_t_r; the _o_f_f_s_e_t member does not specify a properly-aligned location in the data buffer; or an undefined value is stored in _f_l_a_g_s. ENXIO Hangup received on the _f_i_l_d_e_s argument of the iiooccttll() call or the _f_i_l_d_e_s member of the _s_t_r_f_d_i_n_s_e_r_t structure. ERANGE The _l_e_n field for the buffer specified through _d_a_t_a_b_u_f does not fall within the range specified by the maximum and minimum packet sizes of the topmost stream module; or the _l_e_n member for the buffer specified through _d_a_t_a_b_u_f is larger than the maximum configured size of the data part of a message; or the _l_e_n member for the buffer specified through _c_t_l_b_u_f 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 _f_i_l_d_e_s member of the _s_t_r_f_d_i_n_s_e_r_t structure. In this case, _e_r_r_n_o will be set to the value in the message. I_STR Constructs an internal SSTTRREEAAMMSS ioctl message from the data pointed to by _a_r_g, and sends that message downstream. This mechanism is provided to send user iiooccttll() requests to downstream modules and drivers. It allows information to be sent with the iiooccttll(), 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 _e_r_r_n_o set to ETIME. To send requests downstream, _a_r_g must point to a _s_t_r_i_o_c_t_l structure which contains the following members: int ic_cmd; int ic_timout; int ic_len; char *ic_dp; _i_c___c_m_d is the internal iiooccttll() command intended for a downstream module or driver and _i_c___t_i_m_o_u_t is the number of seconds (-1 = infinite, 0 = use default, >0 = as specified) an I_STR request will wait for acknowledgement before timing out. _i_c___l_e_n is the number of bytes in the data argument and _i_c___d_p is a pointer to the data argument. The _i_c___l_e_n 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 _i_c___d_p 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 _i_c___t_i_m_o_u_t field to 0, the user is requesting STREAMS to provide the DDEEFFAAUULLTT 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 _s_t_r_i_o_c_t_l structure to an internal iiooccttll() command message and send it downstream. On failure, _e_r_r_n_o is set to one of the following values: ENOSR Unable to allocate buffers for the iiooccttll() message due to insufficient STREAMS memory resources. EFAULT Either _a_r_g points outside the allocated address space, or the buffer area specified by _i_c___d_p and _i_c___l_e_n (separately for data sent and data returned) is outside the allocated address space. EINVAL _i_c___l_e_n is less than 0 or _i_c___l_e_n is larger than the maximum configured size of the data part of a message or _i_c___t_i_m_o_u_t is less than -1. ENXIO Hangup received on _f_i_l_d_e_s. ETIME A downstream iiooccttll() 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 _e_r_r_n_o set to the value in the message. I_SWROPT Sets the write mode using the value of the argument _a_r_g. Legal bit settings for _a_r_g 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 _a_r_g. On failure, _e_r_r_n_o may be set to the following value: EEIINNVVAALL _a_r_g is not the above legal value. I_GWROPT Returns the current write mode setting, as described above, in the _i_n_t that is pointed to by the argument _a_r_g. I_SENDFD Requests the stream associated with _f_i_l_d_e_s 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 _a_r_g, which must be an open file descriptor. I_SENDFD converts _a_r_g 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, _e_r_r_n_o 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 _a_r_g is not a valid, open file descriptor. EINVAL _f_i_l_d_e_s is not connected to a stream pipe. ENXIO Hangup received on _f_i_l_d_e_s. I_RECVFD Retrieves the file descriptor associated with the message sent by an I_SENDFD iiooccttll() over a stream pipe. _a_r_g is a pointer to a data buffer large enough to hold an _s_t_r_r_e_c_v_f_d data structure containing the following members: int fd; uid_t uid; gid_t gid; _f_d is an integer file descriptor. _u_i_d and _g_i_d 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 _e_r_r_n_o 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 _f_d field of the _s_t_r_r_e_c_v_f_d structure. The structure is copied into the user data buffer pointed to by _a_r_g. On failure, _e_r_r_n_o 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 _a_r_g points outside the allocated address space. EMFILE NOFILES file descriptors are currently open. ENXIO Hangup received on _f_i_l_d_e_s. EOVERFLOW _u_i_d or _g_i_d is too large to be stored in the structure pointed to by _a_r_g. I_LIST Allows the user to list all the module names on the stream, up to and including the topmost driver name. If _a_r_g is NULL, the return value is the number of modules, including the driver, that are on the stream pointed to by _f_i_l_d_e_s. This allows the user to allocate enough space for the module names. If _a_r_g is non-null, it should point to an _s_t_r___l_i_s_t structure that has the following members: int sl_nmods; struct str_mlist *sl_modlist; The _s_t_r___m_l_i_s_t structure has the following member: char l_name[FMNAMESZ+1]; The _s_l___n_m_o_d_s member indicates the number of entries the process has allocated in the array. Upon return, the _s_l___m_o_d_l_i_s_t member of the _s_t_r___l_i_s_t structure contains the list of module names, and the number of entries that have been filled into the _s_l___m_o_d_l_i_s_t array is found in the _s_l___n_m_o_d_s member (the number includes the number of modules including the driver). The return value from iiooccttll() 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 (_s_l___n_m_o_d_s) is satisfied. On failure, _e_r_r_n_o may be set to one of the following values: EINVAL The _s_l___n_m_o_d_s 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. _a_r_g 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 11 if the mark condition is satisfied and 00 otherwise. On failure, _e_r_r_n_o is set to the following value: EINVAL Invalid _a_r_g value. I_CKBAND Check if the message of a given priority band exists on the stream head read queue. This returns 11 if a message of a given priority exists, 00 if not, or --11 on error. _a_r_g should be an integer containing the value of the priority band in question. On failure, _e_r_r_n_o is set to the following value: EINVAL Invalid _a_r_g value. I_GETBAND Returns the priority band of the first message on the stream head read queue in the integer referenced by _a_r_g. On failure, _e_r_r_n_o is set to the following value: ENODATA No message on the stream head read queue. I_CANPUT Check if a certain band is writable. _a_r_g is set to the priority band in question. The return value is 00 if the priority band _a_r_g is flow controlled, 11 if the band is writable, or --11 on error. On failure, _e_r_r_n_o is set to the following value: EEIINNVVAALL Invalid _a_r_g 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. _a_r_g is a pointer to an integer containing the number of milliseconds to delay, rounded up to the nearest legal value on the system. The default is fifteen seconds. On failure, _e_r_r_n_o is set to the following value: EINVAL Invalid _a_r_g value. I_GETCLTIME Returns the close time delay in the integer pointed by _a_r_g. I_SERROPT Sets the error mode using the value of the argument _a_r_g. 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 _a_r_g values are either none or one of: RERRNORM Persistent read errors, the default. RERRNONPERSIST Non-persistent read errors. OORR'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, _e_r_r_n_o is set to the following value: EINVAL _a_r_g is not one of the above legal values. I_GERROPT Returns the current error mode setting in an _i_n_t pointed to by the argument _a_r_g. Error modes are described above for I_SERROPT. On failure, _e_r_r_n_o is set to the following value: EEFFAAUULLTT _a_r_g 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 _f_i_l_d_e_s is the file descriptor of the stream connected to the multiplexing driver, and _a_r_g is the file descriptor of the stream connected to another driver. The stream designated by _a_r_g 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, _e_r_r_n_o is set to one of the following values: ENXIO Hangup received on _f_i_l_d_e_s. 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 SSTTRREEAAMMSS memory resources. EBADF _a_r_g is not a valid, open file descriptor. EINVAL _f_i_l_d_e_s stream does not support multiplexing. EINVAL 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 _f_i_l_d_e_s 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 _f_i_l_d_e_s. In addition, an error code can be returned in the positive or negative acknowledgement message. For these cases, I_LINK will fail with _e_r_r_n_o set to the value in the message. I_UNLINK Disconnects the two streams specified by _f_i_l_d_e_s and _a_r_g. _f_i_l_d_e_s is the file descriptor of the stream connected to the multiplexing driver. _a_r_g is the multiplexor ID number that was returned by the I_LINK. If _a_r_g is -1, then all streams that were linked to _f_i_l_d_e_s are disconnected. As in I_LINK, this command requires the multiplexing driver to acknowledge the unlink. On failure, _e_r_r_n_o is set to one of the following values: ENXIO Hangup received on _f_i_l_d_e_s. 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 _a_r_g is an invalid multiplexor ID number or _f_i_l_d_e_s is not the stream on which the I_LINK that returned _a_r_g was performed. EINVAL _f_i_l_d_e_s 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 _f_i_l_d_e_s. In addition, an error code can be returned in the positive or negative acknowledgement message. For these cases, I_UNLINK will fail with _e_r_r_n_o set to the value in the message. I_PLINK Connects two streams, where _f_i_l_d_e_s is the file descriptor of the stream connected to the multiplexing driver, and _a_r_g is the file descriptor of the stream connected to another driver. The stream designated by _a_r_g 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 _f_i_l_d_e_s 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, _e_r_r_n_o is set to one of the following values: ENXIO Hangup received on _f_i_l_d_e_s. ETIME Time out before acknowledgement message was received at the stream head. EAGAIN Unable to allocate STREAMS storage to perform the I_PLINK. EBADF _a_r_g is not a valid, open file descriptor. EINVAL _f_i_l_d_e_s does not support multiplexing. EINVAL _a_r_g 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 _f_i_l_d_e_s 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 _f_i_l_d_e_s. In addition, an error code can be returned in the positive or negative acknowledgement message. For these cases, I_PLINK will fail with _e_r_r_n_o set to the value in the message. I_PUNLINK Disconnects the two streams specified by _f_i_l_d_e_s and _a_r_g that are connected with a persistent link. _f_i_l_d_e_s is the file descriptor of the stream connected to the multiplexing driver. _a_r_g is the multiplexor ID number that was returned by I_PLINK when a stream was linked below the multiplexing driver. If _a_r_g is MUXID_ALL then all streams that are persistent links to _f_i_l_d_e_s are disconnected. As in I_PLINK, this command requires the multiplexing driver to acknowledge the unlink. On failure, _e_r_r_n_o is set to one of the following values: EENNXXIIOO Hangup received on _f_i_l_d_e_s. 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 _f_i_l_d_e_s 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 _f_i_l_d_e_s. In addition, an error code can be returned in the positive or negative acknowledgement message. For these cases, I_PUNLINK will fail with _e_r_r_n_o set to the value in the message. RREETTUURRNN VVAALLUUEESS Unless specified otherwise above, the return value from ioctl(2) is 00 upon success and --11 upon failure, with _e_r_r_n_o set as indicated. SSEEEE AALLSSOO close(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2), putmsg(2), read(2), write(2), Intro(3), signal(3C), signal.h(3HEAD) _S_T_R_E_A_M_S _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e illumos October 29, 2017 illumos