diff options
Diffstat (limited to 'usr/src/man/man7i/streamio.7i')
| -rw-r--r-- | usr/src/man/man7i/streamio.7i | 1550 |
1 files changed, 0 insertions, 1550 deletions
diff --git a/usr/src/man/man7i/streamio.7i b/usr/src/man/man7i/streamio.7i deleted file mode 100644 index d291cd82c3..0000000000 --- a/usr/src/man/man7i/streamio.7i +++ /dev/null @@ -1,1550 +0,0 @@ -.\" Copyright (c) 2017, Joyent, Inc. -.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright 1989 AT&T -.\" The contents of this file are subject to the terms of the -.\" Common Development and Distribution License (the "License"). -.\" You may not use this file except in compliance with the License. -.\" -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE -.\" or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions -.\" and limitations under the License. -.\" -.\" When distributing Covered Code, include this CDDL HEADER in each -.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. -.\" If applicable, add the following below this CDDL HEADER, with the -.\" fields enclosed by brackets "[]" replaced with your own identifying -.\" information: Portions Copyright [yyyy] [name of copyright owner] -.Dd October 29, 2017 -.Dt STREAMIO 7I -.Os -.Sh NAME -.Nm streamio -.Nd STREAMS ioctl commands -.Sh SYNOPSIS -.In sys/types.h -.In stropts.h -.In sys/conf.h -.Ft int -.Fo ioctl -.Fa "int fildes" -.Fa "int command" -.Fa "\&... /*arg*/" -.Fc -.Sh DESCRIPTION -STREAMS (see -.Xr Intro 3 ) -.Fn ioctl -commands are a subset of the -.Xr ioctl 2 -commands and perform a variety of control functions on streams. -.Pp -The -.Fa fildes -argument is an open file descriptor that refers to a stream. -The -.Fa command -argument determines the control function to be performed as -described below. -The -.Fa arg -argument represents additional information that -is needed by this command. -The type of -.Fa arg -depends upon the command, but -it is generally an integer or a pointer to a command-specific data structure. -The -.Fa command -and -.Fa arg -arguments are interpreted by the STREAM head. -Certain combinations of these arguments may be passed to a module or driver in -the stream. -.Pp -Since these STREAMS commands are -.Sy ioctls , -they are subject to the errors described in -.Xr ioctl 2 . -In addition to those errors, the call will fail -with -.Va errno -set to -.Er EINVAL , -without processing a control function, if the STREAM referenced by -.Fa fildes -is linked below a multiplexor, or if -.Fa command -is not a valid value for a stream. -.Pp -Also, as described in -.Xr 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 -.Va errno -set to this value. -.Sh IOCTLS -The following -.Fn ioctl -commands, with error values indicated, are applicable to all STREAMS files: -.Bl -tag -width I_SETCLTIME -.It Dv I_PUSH -Pushes the module whose name is pointed to by -.Va 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, -.Va errno -is set to one of the following values: -.Bl -tag -width ENOTSUP -.It Er EINVAL -Invalid module name. -.It Er EFAULT -.Va arg -points outside the allocated address space. -.It Er ENXIO -Open routine of new module failed. -.It Er ENXIO -Hangup received on -.Va fildes . -.It Er ENOTSUP -Pushing a module is not supported on this stream. -.El -.It Dv I_POP -Removes the module just below the STREAM head of the STREAM pointed to by -.Fa fildes . -To remove a module from a pipe requires that the module was -pushed on the side it is being removed from. -.Fa arg -should be -.Sy 0 -in an -.Dv I_POP -request. -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width ENOTSUP -.It Er EINVAL -No module present in the stream. -.It Er ENXIO -Hangup received on -.Fa fildes . -.It Er EPERM -Attempt to pop through an anchor by an unprivileged process. -.It Er ENOTSUP -Removal is not supported. -.El -.It Dv 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. -.Va arg -must be -.Sy 0 -in an -.Dv I_ANCHOR -request. -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EINVAL -.It Er EINVAL -Request to put an anchor on a pipe. -.El -.It Dv I_LOOK -Retrieves the name of the module just below the stream head of the stream -pointed to by -.Fa fildes , -and places it in a null terminated character string -pointed at by -.Fa arg . -The buffer pointed to by -.Fa arg -should be at least -.Dv FMNAMESZ Ns +1 -bytes long. -This requires the declaration -.Ql "#include <sys/conf.h>" . -On failure, -.Dv errno -is set to one of the following values: -.Bl -tag -width EFAULT -.It Er EFAULT -.Fa arg -points outside the allocated address space. -.It Er EINVAL -No module present in stream. -.El -.It Dv I_FLUSH -This request flushes all input and/or output queues, depending on the value of -.Fa arg . -Legal -.Fa arg -values are: -.Bl -tag -width FLUSHRW -.It Dv FLUSHR -Flush read queues. -.It Dv FLUSHW -Flush write queues. -.It Dv FLUSHRW -Flush read and write queues. -.El -.Pp -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 -.Fa arg . -.Pp -If -.Dv FLUSHR -is set and -.Fa 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 -.Fa fildes -is a FIFO, both queues are flushed. -.Pp -If -.Dv FLUSHW -is set and -.Fa 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 -.Fa fildes -is a FIFO, both queues of the -FIFO are flushed. -.Pp -If -.Dv 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. -.Pp -Correct flush handling of a pipe or FIFO with modules pushed is achieved via -the -.Sy pipemod -module. -This module should be the first module pushed onto a -pipe so that it is at the midpoint of the pipe itself. -.Pp -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EINVAL -.It Er ENOSR -Unable to allocate buffers for flush message due to insufficient stream memory -resources. -.It Er EINVAL -Invalid -.Va arg -value. -.It Er ENXIO -Hangup received on -.Fa fildes . -.El -.It Dv I_FLUSHBAND -Flushes a particular band of messages. -.Fa arg -points to a -.Vt bandinfo -structure that has the following members: -.Bd -literal -offset 2n -unsigned char bi_pri; -int bi_flag; -.Ed -.Pp -The -.Fa bi_flag -field may be one of -.Dv FLUSHR , -.Dv FLUSHW , -or -.Dv FLUSHRW -as described earlier. -.It Dv I_SETSIG -Informs the stream head that the user wishes the kernel to issue the -.Dv SIGPOLL -signal (see -.Xr signal 3C ) -when a particular event has occurred on the stream associated with -.Fa fildes . -.Dv I_SETSIG -supports an asynchronous processing capability in streams. -The value of -.Fa 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: -.Bl -tag -width S_BANDURG -.It Dv S_INPUT -Any message other than an -.Dv 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. -.It Dv 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. -.It Dv 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. -.It Dv 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. -.It Dv 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. -.It Dv S_WRNORM -This event is the same as -.Dv S_OUTPUT . -.It Dv 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. -.It Dv S_MSG -A STREAMS signal message that contains the -.Dv SIGPOLL -signal has reached the -front of the stream head read queue. -.It Dv S_ERROR -An -.Dv M_ERROR -message has reached the stream head. -.It Dv S_HANGUP -An -.Dv M_HANGUP -message has reached the stream head. -.It Dv S_BANDURG -When used in conjunction with -.Dv S_RDBAND , -.Dv SIGURG -is generated instead of -.Dv SIGPOLL -when a priority message reaches the front of the stream head -read queue. -.El -.Pp -A user process may choose to be signaled only of high priority messages by -setting the -.Fa arg -bitmask to the value -.Dv S_HIPRI . -.Pp -Processes that wish to receive -.Dv SIGPOLL -signals must explicitly register -to receive them using -.Dv 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. -.Pp -If the value of -.Fa arg -is zero, the calling process will be unregistered and -will not receive further -.Dv SIGPOLL -signals. -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EINVAL -.It Sy EINVAL -.Fa arg -value is invalid or -.Fa arg -is zero and process is not registered to receive the -.Dv SIGPOLL -signal. -.It Sy EAGAIN -Allocation of a data structure to store the signal request failed. -.El -.It Dv I_GETSIG -Returns the events for which the calling process is currently registered to be -sent a -.Dv SIGPOLL -signal. -The events are returned as a bitmask pointed to by -.Va arg , -where the events are those specified in the description of -.Dv I_SETSIG -above. -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EINVAL -.It Sy EINVAL -Process not registered to receive the -.Dv SIGPOLL -signal. -.It Sy EFAULT -.Fa arg -points outside the allocated address space. -.El -.It Dv I_FIND -Compares the names of all modules currently present in the stream to the name -pointed to by -.Fa 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, -.Va errno -is set to one of the following values: -.Bl -tag -width EINVAL -.It Sy EFAULT -.Fa arg -points outside the allocated address space. -.It Sy EINVAL -.Fa arg -does not contain a valid module name. -.El -.It Dv 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. -.Dv I_PEEK -is analogous to -.Xr getmsg 2 -except that it does not remove the message from the queue. -.Fa arg -points to a -.Vt strpeek -structure, which contains the following members: -.Bd -literal -offset 2n -struct strbuf ctlbuf; -struct strbuf databuf; -long flags; -.Ed -.Pp -The -.Ft maxlen -field in the -.Vt ctlbuf -and -.Vt databuf -.Vt strbuf -structures (see -.Xr getmsg 2 ) -must be set to the number of bytes of control -information and/or data information, respectively, to retrieve. -.Fa flags -may be set to -.Dv RS_HIPRI -or -.Sy 0 . -If -.Dv RS_HIPRI -is set, -.Dv I_PEEK -will look for a high priority message on the stream head read queue. -Otherwise, -.Dv I_PEEK -will look for the first message on the stream head read queue. -.Pp -.Dv I_PEEK -returns -.Sy 1 -if a message was retrieved, and returns -.Sy 0 -if no message was found on the stream head read queue. -It does not wait for a message to arrive. -On return, -.Vt ctlbuf -specifies information in the control buffer, -.Vt databuf -specifies information in the data buffer, and -.Fa flags -contains the value -.Dv RS_HIPRI -or -.Sy 0 . -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EBADMSG -.It Er EFAULT -.Fa arg -points, or the buffer area specified in -.Vt ctlbuf -or -.Vt databuf -is, outside the allocated address space. -.It Er EBADMSG -Queued message to be read is not valid for -.Dv I_PEEK . -.It Er EINVAL -Illegal value for -.Vt flags . -.It Er ENOSR -Unable to allocate buffers to perform the -.Dv I_PEEK -due to insufficient STREAMS memory resources. -.El -.It Dv I_SRDOPT -Sets the read mode (see -.Xr read 2 ) -using the value of the argument -.Va arg . -Legal -.Va arg -values are: -.Bl -tag -width RNORM -.It Dv RNORM -Byte-stream mode, the default. -.It Dv RMSGD -Message-discard mode. -.It Dv RMSGN -Message-nondiscard mode. -.El -.Pp -In addition, the stream head's treatment of control messages may be changed by -setting the following flags in -.Va arg : -.Bl -tag -width RPROTNORM -.It Dv RPROTNORM -Reject -.Xr read 2 -with -.Er EBADMSG -if a control message is at the front of the stream head read queue. -.It Dv RPROTDAT -Deliver the control portion of a message as data when a user issues -.Xr read 2 . -This is the default behavior. -.It Dv RPROTDIS -Discard the control portion of a message, delivering any data portion, when a -user issues a -.Xr read 2 . -.El -.Pp -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EINVAL -.It Er EINVAL -.Va arg -is not one of the above legal values, or -.Va arg -is the bitwise -inclusive -.Sy OR -of -.Dv RMSGD -and -.Dv RMSGN . -.El -.It Dv I_GRDOPT -Returns the current read mode setting in an -.Vt int -pointed to by the argument -.Fa arg . -Read modes are described in -.Xr read 2 . -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EFAULT -.It Er EFAULT -.Fa arg -points outside the allocated address space. -.El -.It Dv 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 -.Fa 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 -.Fa arg , -but the -.Fn ioctl -return value is greater than zero, this indicates that a -zero-length message is next on the queue. -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EFAULT -.It Er EFAULT -.Fa arg -points outside the allocated address space. -.El -.It Dv 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. -.Pp -The -.Fa arg -argument points to a -.Vt strfdinsert -structure, which contains -the following members: -.Bd -literal -offset 2n -struct strbuf ctlbuf; -struct strbuf databuf; -t_uscalar_t flags; -int fildes; -int offset; -.Ed -.Pp -The -.Fa len -member in the -.Vt ctlbuf -.Vt strbuf -structure (see -.Xr putmsg 2 ) -must be set to the size of a -.Vt t_uscalar_t -plus the number of bytes of -control information to be sent with the message. -The -.Fa fildes -member specifies the file descriptor of the other stream, and the -.Fa offset -member, which must be suitably aligned for use as a -.Vt t_uscalar_t , -specifies the offset from the start of the control buffer where -.Dv I_FDINSERT -will store a -.Vt t_uscalar_t -whose interpretation is specific to the stream end. -The -.Fa len -member in the -.Vt databuf -.Vt 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. -.Pp -The -.Fa flags -member specifies the type of message to be created. -A normal message is created if -.Fa flags -is set to 0, and a high-priority message is created if -.Fa flags -is set to -.Dv RS_HIPRI . -For non-priority messages, -.Dv I_FDINSERT -will block if the stream write queue is full due to internal -flow control conditions. -For priority messages, -.Dv I_FDINSERT -does not block on this condition. -or non-priority messages, -.Dv I_FDINSERT -does not -block when the write queue is full and -.Dv O_NDELAY -or -.Dv O_NONBLOCK -is set. -Instead, it fails and sets -.Va errno -to -.Er EAGAIN . -.Pp -.Dv 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 -.Dv O_NDELAY -or -.Dv O_NONBLOCK -has been specified. -No partial message is sent. -.Pp -The -.Fn ioctl -function with the -.Dv I_FDINSERT -command will fail if: -.Bl -tag -width EAGAIN -.It Er EAGAIN -A non-priority message is specified, the -.Dv O_NDELAY -or -.Dv O_NONBLOCK -flag is set, and the stream write queue is full due to internal flow control -conditions. -.It Er ENOSR -Buffers can not be allocated for the message that is to be created. -.It Er EFAULT -The -.Fa arg -argument points, or the buffer area specified in -.Vt ctlbuf -or -.Vt databuf -is, outside the allocated address space. -.It Er EINVAL -One of the following: The -.Fa fildes -member of the -.Vt strfdinsert -structure is not a valid, open stream file descriptor; the size of a -.Vt t_uscalar_t -plus -.Fa offset -is greater than the -.Fa len -member for the buffer specified through -.Fa ctlptr ; -the -.Fa offset -member does not specify a properly-aligned location in the data buffer; or an -undefined value is stored in -.Fa flags . -.It Er ENXIO -Hangup received on the -.Fa fildes -argument of the -.Fn ioctl -call or the -.Fa fildes -member of the -.Vt strfdinsert -structure. -.It Er ERANGE -The -.Fa len -field for the buffer specified through -.Vt databuf -does not fall within the range specified by the maximum and minimum packet -sizes of the topmost stream module; or the -.Fa len -member for the buffer specified through -.Vt databuf -is larger than the maximum configured size of the data part of a message; or the -.Fa len -member for the buffer specified through -.Vt ctlbuf -is larger than the maximum configured size of the control part of a message. -.El -.Pp -.Dv I_FDINSERT -can also fail if an error message was received by the stream -head of the stream corresponding to the -.Fa fildes -member of the -.Vt strfdinsert -structure. -In this case, -.Va errno -will be set to the value in the message. -.It Dv I_STR -Constructs an internal -.Sy STREAMS -ioctl message from the data pointed to by -.Fa arg , -and sends that message downstream. -.Pp -This mechanism is provided to send user -.Fn ioctl -requests to downstream modules and drivers. -It allows information to be sent with the -.Fn ioctl , -and will return to the user any information sent upstream by the downstream -recipient. -.Dv 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 -.Va errno -set to -.Er ETIME . -.Pp -To send requests downstream, -.Fa arg -must point to a -.Vt strioctl -structure which contains the following members: -.Bd -literal -offset 2n -int ic_cmd; -int ic_timout; -int ic_len; -char *ic_dp; -.Ed -.Pp -.Fa ic_cmd -is the internal -.Fn ioctl -command intended for a downstream module or driver and -.Fa ic_timout -is the number of seconds (-1 = infinite, 0 = use default, >0 = as specified) an -.Dv I_STR -request will wait for acknowledgement before timing out. -.Fa ic_len -is the number of bytes in the data argument and -.Fa ic_dp -is a pointer to the data argument. -The -.Fa 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 -.Fa ic_dp -should be large enough to contain the maximum amount of data that any module or -the driver in the stream can return). -.Pp -At most one -.Dv I_STR -can be active on a stream. -Further -.Dv I_STR -calls -will block until the active -.Dv I_STR -completes via a positive or negative -acknowlegment, a timeout, or an error condition at the stream head. -By setting the -.Fa ic_timout -field to 0, the user is requesting STREAMS to provide -the -.Sy 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 -.Dv O_NDELAY -and -.Dv O_NONBLOCK -(see -.Xr open 2 ) -flags have no effect on this call. -.Pp -The stream head will convert the information pointed to by the -.Vt strioctl -structure to an internal -.Fn ioctl -command message and send it downstream. -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EFAULT -.It Er ENOSR -Unable to allocate buffers for the -.Fn ioctl -message due to insufficient STREAMS memory resources. -.It Er EFAULT -Either -.Fa arg -points outside the allocated address space, or the buffer area -specified by -.Fa ic_dp -and -.Fa ic_len -(separately for data sent and data returned) is outside the allocated address -space. -.It Er EINVAL -.Fa ic_len -is less than 0 or -.Fa ic_len -is larger than the maximum configured size of the data part of a message or -.Fa ic_timout -is less than \(mi1. -.It Er ENXIO -Hangup received on -.Fa fildes . -.It Er ETIME -A downstream -.Fn ioctl -timed out before acknowledgement was received. -.El -.Pp -An -.Dv 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, -.Dv I_STR -will fail with -.Va errno -set to the value in the message. -.It Dv I_SWROPT -Sets the write mode using the value of the argument -.Fa arg . -Legal bit settings for -.Fa arg -are: -.Bl -tag -width SNDZERO -.It Dv SNDZERO -Send a zero-length message downstream when a write of 0 bytes occurs. -.El -.Pp -To not send a zero-length message when a write of 0 bytes occurs, this bit must -not be set in -.Fa arg . -.Pp -On failure, -.Va errno -may be set to the following value: -.Bl -tag -width EINVAL -.It Sy EINVAL -.Fa arg -is not the above legal value. -.El -.It Dv I_GWROPT -Returns the current write mode setting, as described above, in the -.Vt int -that is pointed to by the argument -.Fa arg . -.It Dv I_SENDFD -Requests the stream associated with -.Fa 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 -.Fa arg , -which must be an open file descriptor. -.Pp -.Dv I_SENDFD -converts -.Fa 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 -.Xr Intro 3 ) -of the stream head at the other end of the stream pipe to which it is connected. -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EAGAIN -.It Er EAGAIN -The sending stream is unable to allocate a message block to contain the file -pointer. -.It Er EAGAIN -The read queue of the receiving stream head is full and cannot accept the -message sent by -.Dv I_SENDFD . -.It Er EBADF -.Fa arg -is not a valid, open file descriptor. -.It Er EINVAL -.Va fildes -is not connected to a stream pipe. -.It Er ENXIO -Hangup received on -.Fa fildes . -.El -.It Dv I_RECVFD -Retrieves the file descriptor associated with the message sent by an -.Dv I_SENDFD -.Fn ioctl -over a stream pipe. -.Fa arg -is a pointer to a data buffer large enough to hold an -.Vt strrecvfd -data structure containing the following members: -.Bd -literal -offset 2n -int fd; -uid_t uid; -gid_t gid; -.Ed -.Pp -.Fa fd -is an integer file descriptor. -.Fa uid -and -.Fa gid -are the user id and group id, respectively, of the sending stream. -.Pp -If -.Dv O_NDELAY -and -.Dv O_NONBLOCK -are clear (see -.Xr open 2 ) , -.Dv I_RECVFD -will block until a message is present at the stream head. -If -.Dv O_NDELAY -or -.Dv O_NONBLOCK -is set, -.Dv I_RECVFD -will fail with -.Va errno -set to -.Er EAGAIN -if no message is present at the stream head. -.Pp -If the message at the stream head is a message sent by an -.Dv 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 -.Fa fd -field of the -.Vt strrecvfd -structure. -The structure is copied into the user data buffer pointed to by -.Fa arg . -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EOVERFLOW -.It Er EAGAIN -A message is not present at the stream head read queue, and the -.Dv O_NDELAY -or -.Dv O_NONBLOCK -flag is set. -.It Er EBADMSG -The message at the stream head read queue is not a message containing a passed -file descriptor. -.It Er EFAULT -.Fa arg -points outside the allocated address space. -.It Er EMFILE -.Dv NOFILES -file descriptors are currently open. -.It Er ENXIO -Hangup received on -.Fa fildes . -.It Er EOVERFLOW -.Fa uid -or -.Fa gid -is too large to be stored in the structure pointed to by -.Fa arg . -.El -.It Dv I_LIST -Allows the user to list all the module names on the stream, up to and including -the topmost driver name. -If -.Fa arg -is -.Dv NULL , -the return value is the number of modules, including the driver, that are on -the stream pointed to by -.Fa fildes . -This allows the user to allocate enough space for the module -names. -If -.Fa arg -is non-null, it should point to an -.Vt str_list -structure that has the following members: -.Bd -literal -offset 2n -int sl_nmods; -struct str_mlist *sl_modlist; -.Ed -.Pp -The -.Vt str_mlist -structure has the following member: -.Bd -literal -offset 2n -char l_name[FMNAMESZ+1]; -.Ed -.Pp -The -.Fa sl_nmods -member indicates the number of entries the process has allocated in the array. -Upon return, the -.Fa sl_modlist -member of the -.Vt str_list -structure contains the list of module names, and the number of -entries that have been filled into the -.Fa sl_modlist -array is found in the -.Fa sl_nmods -member (the number includes the number of modules including the driver). -The return value from -.Fn 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 -.Pq Fa sl_nmods -is satisfied. -On failure, -.Va errno -may be set to one of the following values: -.Bl -tag -width EINVAL -.It Er EINVAL -The -.Fa sl_nmods -member is less than 1. -.It Er EAGAIN -Unable to allocate buffers -.El -.It Dv I_ATMARK -Allows the user to see if the current message on the stream head read queue is -.Dq marked -by some module downstream. -.Fa 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: -.Bl -tag -width LASTMARK -.It Dv ANYMARK -Check if the message is marked. -.It Dv LASTMARK -Check if the message is the last one marked on the queue. -.El -.Pp -The return value is -.Sy 1 -if the mark condition is satisfied and -.Sy 0 -otherwise. -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EINVAL -.It Er EINVAL -Invalid -.Fa arg -value. -.El -.It Dv I_CKBAND -Check if the message of a given priority band exists on the stream head read -queue. -This returns -.Sy 1 -if a message of a given priority exists, -.Sy 0 -if not, or -.Sy \(mi1 -on error. -.Fa arg -should be an integer containing the value of the priority band in question. -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EINVAL -.It Er EINVAL -Invalid -.Fa arg -value. -.El -.It Dv I_GETBAND -Returns the priority band of the first message on the stream head read queue in -the integer referenced by -.Fa arg . -On failure, -.Va errno -is set to the following value: -.Bl -tag -width ENODATA -.It Er ENODATA -No message on the stream head read queue. -.El -.It Dv I_CANPUT -Check if a certain band is writable. -.Fa arg -is set to the priority band in question. -The return value is -.Sy 0 -if the priority band -.Fa arg -is flow controlled, -.Sy 1 -if the band is writable, or -.Sy \(mi1 -on error. -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EINVAL -.It Sy EINVAL -Invalid -.Va arg -value. -.El -.It Dv 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. -.Fa arg -is a pointer to an integer containing the number of -milliseconds to delay, rounded up to the nearest legal value on the system. -The default is fifteen seconds. -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EINVAL -.It Er EINVAL -Invalid -.Fa arg -value. -.El -.It Dv I_GETCLTIME -Returns the close time delay in the integer pointed by -.Va arg . -.It Dv I_SERROPT -Sets the error mode using the value of the argument -.Fa arg . -.Pp -Normally stream head errors are persistent; once they are set due to an -.Dv M_ERROR -or -.Dv 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 -.Xr read 2 , -.Xr getmsg 2 , -.Xr ioctl 2 , -.Xr write 2 , -or -.Xr putmsg 2 -call the error condition will be cleared. -The error mode can be controlled independently for read and write side errors. -Legal -.Fa arg -values -are either none or one of: -.Bl -tag -width RERRNONPERSIST -.It Dv RERRNORM -Persistent read errors, the default. -.It Dv RERRNONPERSIST -Non-persistent read errors. -.El -.Pp -.Sy OR Ns 'ed -with either none or one of: -.Bl -tag -width WERRNONPERSIST -.It Dv WERRNORM -Persistent write errors, the default. -.It Dv WERRNONPERSIST -Non-persistent write errors. -.El -.Pp -When no value is specified e\.g\. for the read side error behavior then the -behavior for that side will be left unchanged. -.Pp -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EINVAL -.It Er EINVAL -.Va arg -is not one of the above legal values. -.El -.It Dv I_GERROPT -Returns the current error mode setting in an -.Vt int -pointed to by the argument -.Fa arg . -Error modes are described above for -.Dv I_SERROPT . -On failure, -.Va errno -is set to the following value: -.Bl -tag -width EFAULT -.It Sy EFAULT -.Fa arg -points outside the allocated address space. -.El -.El -.Pp -The following four commands are used for connecting and disconnecting -multiplexed STREAMS configurations. -.Bl -tag -width I_PUNLINK -.It Dv I_LINK -Connects two streams, where -.Fa fildes -is the file descriptor of the stream -connected to the multiplexing driver, and -.Fa arg -is the file descriptor of the stream connected to another driver. -The stream designated by -.Va arg -gets -connected below the multiplexing driver. -.Dv 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 -.Dv I_UNLINK ) -on success, and \(mi1 on failure. -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EAGAIN -.It Er ENXIO -Hangup received on -.Va fildes . -.It Er ETIME -Time out before acknowledgement message was received at stream head. -.It Er EAGAIN -Temporarily unable to allocate storage to perform the -.Dv I_LINK . -.It Er ENOSR -Unable to allocate storage to perform the -.Dv I_LINK -due to insufficient -.Sy STREAMS -memory resources. -.It Er EBADF -.Va arg -is not a valid, open file descriptor. -.It Er EINVAL -.Va fildes -stream does not support multiplexing. -.It Er EINVAL -is not a stream, or is already linked under a multiplexor. -.It Er EINVAL -The specified link operation would cause a -.Dq cycle -in the resulting configuration; that is, a driver would be linked into the -multiplexing configuration in more than one place. -.It Er EINVAL -.Va fildes -is the file descriptor of a pipe or FIFO. -.It Er EINVAL -Either the upper or lower stream has a major number \(>= the maximum major -number on the system. -.El -.Pp -An -.Dv 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 -.Fa fildes . -In addition, an error code can be -returned in the positive or negative acknowledgement message. -For these cases, -.Dv I_LINK -will fail with -.Va errno -set to the value in the message. -.It Dv I_UNLINK -Disconnects the two streams specified by -.Fa fildes -and -.Fa arg . -.Fa fildes -is the file descriptor of the stream connected to the multiplexing -driver. -.Fa arg -is the multiplexor ID number that was returned by the -.Dv I_LINK . -If -.Fa arg -is \(mi1, then all streams that were linked to -.Fa fildes -are disconnected. -As in -.Dv I_LINK , -this command requires the multiplexing driver to acknowledge the unlink. -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EINVAL -.It Er ENXIO -Hangup received on -.Va fildes . -.It Er ETIME -Time out before acknowledgement message was received at stream head. -.It Er ENOSR -Unable to allocate storage to perform the -.Dv I_UNLINK -due to insufficient -STREAMS memory resources. -.It Er EINVAL -.Fa arg -is an invalid multiplexor ID number or -.Fa fildes -is not the stream on which the -.Dv I_LINK -that returned -.Fa arg -was performed. -.It Er EINVAL -.Fa fildes -is the file descriptor of a pipe or FIFO. -.El -.Pp -An -.Dv 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 -.Fa fildes . -In addition, an error code can be -returned in the positive or negative acknowledgement message. -For these cases, -.Dv I_UNLINK -will fail with -.Va errno -set to the value in the message. -.It Dv I_PLINK -Connects two streams, where -.Fa fildes -is the file descriptor of the stream -connected to the multiplexing driver, and -.Fa arg -is the file descriptor of -the stream connected to another driver. -The stream designated by -.Fa arg -gets -connected via a persistent link below the multiplexing driver. -.Dv 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 -.Fa 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 -.Dv I_PUNLINK ) -on success, and \(mi1 on failure. -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EAGAIN -.It Er ENXIO -Hangup received on -.Fa fildes . -.It Er ETIME -Time out before acknowledgement message was received at the stream head. -.It Er EAGAIN -Unable to allocate STREAMS storage to perform the -.Dv I_PLINK . -.It Er EBADF -.Va arg -is not a valid, open file descriptor. -.It Er EINVAL -.Va fildes -does not support multiplexing. -.It Er EINVAL -.Va arg -is not a stream or is already linked under a multiplexor. -.It Er EINVAL -The specified link operation would cause a -.Dq cycle -in the resulting configuration; that is, if a driver would be linked into the -multiplexing configuration in more than one place. -.It Er EINVAL -.Fa fildes -is the file descriptor of a pipe or FIFO. -.El -.Pp -An -.Dv 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 -.Fa fildes . -In addition, an error code can be -returned in the positive or negative acknowledgement message. -For these cases, -.Dv I_PLINK -will fail with -.Va errno -set to the value in the message. -.It Dv I_PUNLINK -Disconnects the two streams specified by -.Fa fildes -and -.Fa arg -that are -connected with a persistent link. -.Fa fildes -is the file descriptor of the -stream connected to the multiplexing driver. -.Fa arg -is the multiplexor ID number that was returned by -.Dv I_PLINK -when a stream was linked below the multiplexing driver. -If -.Fa arg -is -.Dv MUXID_ALL -then all streams that are persistent links to -.Fa fildes -are disconnected. -As in -.Dv I_PLINK , -this command requires the multiplexing driver to acknowledge the unlink. -On failure, -.Va errno -is set to one of the following values: -.Bl -tag -width EAGAIN -.It Sy ENXIO -Hangup received on -.Fa fildes . -.It Er ETIME -Time out before acknowledgement message was received at the stream head. -.It Er EAGAIN -Unable to allocate buffers for the acknowledgement message. -.It Er EINVAL -Invalid multiplexor ID number. -.It Er EINVAL -.Fa fildes -is the file descriptor of a pipe or FIFO. -.El -.Pp -An -.Dv 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 -.Fa fildes . -In addition, an error code can be -returned in the positive or negative acknowledgement message. -For these cases, -.Dv I_PUNLINK -will fail with -.Va errno -set to the value in the message. -.El -.Sh RETURN VALUES -Unless specified otherwise above, the return value from -.Xr ioctl 2 -is -.Sy 0 -upon success and -.Sy \(mi1 -upon failure, with -.Va errno -set as indicated. -.Sh SEE ALSO -.Xr close 2 , -.Xr fcntl 2 , -.Xr getmsg 2 , -.Xr ioctl 2 , -.Xr open 2 , -.Xr poll 2 , -.Xr putmsg 2 , -.Xr read 2 , -.Xr write 2 , -.Xr Intro 3 , -.Xr signal 3C , -.Xr signal.h 3HEAD -.Pp -.%B STREAMS Programming Guide |