STREAMIO

Section: Linux Fast-STREAMS Protocols (7)
Updated: 2008-10-31
Index Return to Main Contents

NAME

streamio - STREAMS ioctl commands

SYNOPSIS

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

int retval = ioctl (int fd, int command , ... /* arg */);

DESCRIPTION

STREAMS
I/O control commands are ioctl commands that are defined to operate on all STREAMS character special devices. All of these commands are interpreted by the stream head. Some commands are passed to the STREAMS module or driver.

STREAMS I/O control commands are invoked using the normal ioctl(2s) system call, but are defined only for STREAMS character special files.

fd: is an open file descriptor for a STREAMS character special file.
command: is the STREAMS I/O control function that the caller requests be performed.
arg: provides additional information required by the particular I/O command. Specific command and arg are described below.

IOCTLS

I_ATMARK

Checks whether the next messages on the stream head read queue is marked. arg is an integer value indicating which messages to check as follows:

ANYMARK: check whether the next message on the stream head read queue is marked.
LASTMARK: check whether the next message on the stream head read queue is the last marked message (i.e. it is not followed by a another marked message).

Marked messages are messages that have the MSGMARK flag set in the message b_flag field.

Upon success, I_ATMARK returns (0) to indicate that the stream head read queue does not meet the mark criteria, or (1) to indicate that it meets the mark criteria. Upon failure, I_ATMARK returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]: arg is invalid.

Solaris®[1] also uses the MSGNEXTMARK and MSGNOTNEXTMARK flags on the message blocks; but their use is undocumented. AIX®[2] indicates that it is permissible for arg to be the inclusive OR of the ANYMARK and LASTMARK flags. HP-UX®[3] indicates that if both ANYMARK and LASTMARK are set, ANYMARK supersedes LASTMARK. UnixWare®[4] indicates that the bitwise-OR of ANYMARK and LASTMARK is allowed and that, if both are set, ANYMARK supersedes LASTMARK.

I_CANPUT

Checks whether messages can be written to the queue band specified by arg. arg is an integer which contains the queue band to test for flow control.

Linux Fast-STREAMS adds the extension that arg can also be one of the following values:

ANYBAND: instead of testing a specified band, tests whether any (existing) band is writable.

Upon success, retval is false (0) if the queue band arg is flow controlled, true (1) if the queue band is not flow controlled. Upon failure, retval is -1 and errno(3) is set to one of the following errors numbers:

[EINVAL]: arg is outside the range 0 to 255 and does not represent a valid priority band.

Any of the errors returned by putpmsg(2s) may be returned in errno. Any error received in an M_ERROR(9) message indicating a write error for the stream will be returned in errno. (See also ERRORS below.)

I_CKBAND

Checks whether messages can be read from the queue band specified by arg. arg is an integer which contains the queue band to test for an available message. Upon success, I_CKBAND returns false (0) if there is no message for the specified queue band arg available, and true (1) if a message for the specified queue band arg is available to be read with read(2) or getmsg(2). Upon failure, I_CKBAND returns -1 and errno(3) is set to one of the following error numbers:

[EINVAL]: arg contains a priority band outside the range 0 - 255.

Any of the errors returned by getpmsg(2s) may be returned in errno. Any error received in an M_ERROR(9) message indicating a read error for the stream will be returned in errno. (See also ERRORS below.)

I_FDINSERT

This command performs similar to putmsg(2), however, it performs the additional function of inserting the bottom read queue pointer associated with a specified file descriptor in the resulting message. This ioctl is often used to accepting incoming connections on tpi(7) based protocols.

arg is a pointer to a strfdinsert structure that is formatted as follows:

struct strfdinsert {
    struct strbuf ctlbuf;
    struct strbuf databuf;
    ulong flags;
    int fildes;
    int offset;
};

ctlbuf: describes the control part of the message, and is formated the same as the strbuf structure pointed to by ctlptr as an argument to putmsg(2). The len field of this strbuf structure must be large enough to accept the translated file descriptor. Unlike putmsg(2) this message must contain a control part.
databuf: describes the data part of the message, formatted the same as the strbuf structure pointed to by datptr as an argument to putmsg(2). Unlike putmsg(2) if the len field of this strbuf structure is zero, it indicates that no data part is to be sent with the message. (For putmsg(2), a len field of zero (0) would indicate to send a zero-length data part message.)
flags: provides the options flags formatted the same as the flags argument to putmsg(2).
fildes: is the file descriptor of a stream to be translated to a read queue pointer and placed into the control part of the message.
offset: is the offset into the control part to place the read queue pointer associated with fildes. This offset must leave sufficient room in the control part of the message to permit the read queue pointer to be overwritten without exceeding the bounds of the control part.

Upon success, I_FDINSERT returns zero (0). Upon failure, I_FDINSERT returns -1 and sets errno(3) to one of the following error numbers:

[EFAULT]: arg, ctlbuf, databuf, ctlbuf.buf or databuf.buf points outside the caller's valid address space.
[ENOSR]: a buffer for the resulting message could not be allocated.
[EINVAL]: fildes is invalid, or offset is invalid, or flags is invalid.

I_FIND

Checks whether the specified module is currently present in the stream specified by fd.

arg is a pointer to a string which provides the name of the module to find.

Upon success, I_FIND returns true (1) if the module is present in the stream under the name arg, and returns false (0) if the module is not present in the stream. Upon failure, I_FIND returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points to a string which exceeds the callers valid address space.

I_FLUSHBAND

Flushes the stream for a specified band. arg points to a bandinfo structure formatted as follows:

struct bandinfo {
        unsigned char bi_pri;
        int bi_flag;
};

bi_pri specifies the priority of the band to flush. bi_flag specifies which queues to flush and has one of the following values:

FLUSHR: flush the read queues.
FLUSHW: flush the write queues.
FLUSHRW: flush the read and write queues.

Note that on a bare STREAMS-based pipe(4), specifying FLUSHR will flush the read queues at both ends of the pipe, and FLUSHW will flush the write queues at both ends of the pipe. FLUSHRW will still flush both queues. This is expected behaviour for bare STREAMS-based pipes (that is, pipes that have no modules pushed on either end). For the I_FLUSH command to flush the proper queues in modules pushed on a STREAMS-based pipe, pipemod(4) must be pushed onto one end of the pipe before pushing any other modules. Pushing pipemod(4) will also reverse the effect that FLUSHR and FLUSHW have on the opposite STREAM head: FLUSHR flushes the near read queue and the far write queue, FLUSHW flushes the near write queue and the far read queue. See pipemod(4) for details.

Upon success, I_FLUSHBAND returns zero (0). Upon failure, I_FLUSHBAND returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points outside the caller's valid address space.
[EINVAL]: bi_flag contains invalid flags other than FLUSHR, FLUSHW or FLUSHRW.
[ENOSR]: the M_FLUSH(9) message could not be allocated.

(See also ERRORS below.)

I_FLUSH

Flushes the stream.

arg is an integer containing one of the following flags:

FLUSHR: flush the read queues.
FLUSHW: flush the write queues.
FLUSHRW: flush both the read and write queues.

Upon success, I_FLUSH returns zero (0). Upon failure, I_FLUSH returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]: arg contains invalid flags other than FLUSHR, FLUSHW or FLUSHRW.
[ENOSR]: the M_FLUSH(9) message could not be allocated.

(See also ERRORS below.)

I_GETBAND

Gets the priority band associated with the next message on the stream head read queue. arg is a pointer to an integer to receive the band number. Upon success, I_GETBAND returns (0) and places the band associated with the next message on the stream head read queue into the integer pointed to by arg. Upon failure, I_GETBAND returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points outside the caller's valid address space.
[ENODATA]: there is no message on the stream head read queue.

I_GETCLTIME

Gets the close delay time (in milliseconds) associated with the stream head. arg points to an int to receive the delay.

Upon success, I_GETCLTIME returns zero (0) and the close delay time in the int pointed to by arg. Upon failure, I_GETCLTIME returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points outside the caller's valid address space.

I_GETSIG

Gets a bitmask of the events for which the calling process is registered to be sent a SIGPOLL signal. arg points to an integer into which will be returned the bit mask. The bit mask returned in the integer pointed to by arg will contain a bitwise OR of one or more of the following flags:

S_INPUT: any message but high priority on read queue.
S_HIPRI: high priority message on read queue.
S_OUTPUT: write queue is no longer full.
S_MSG: signal message at front of read queue.
S_ERROR: error message arrived at stream head.
S_HANGUP: hangup message arrived at stream head.
S_RDNORM: normal message on read queue
S_WRNORM: same as S_OUTPUT.
S_RDBAND: out of band message on read queue.
S_WRBAND: can write out of band message.
S_BANDURG: modifier to S_RDBAND, to generate SIGURG instead of SIGPOLL.
S_ALL: all flags.

Upon success, I_GETSIG returns (0) and the event bit mask in the integer pointed to by arg. Upon failure, I_GETSIG returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points outside the caller's valid address space.
[EINVAL]: the calling process is not registered to receive a SIGPOLL signal.

I_SRDOPT

Sets the read(2s) options flags for the stream head. These flags alter the behaviour of the read(2s) call when called for fd. arg is an integer value containing the read options flags which may be one flag from the mode group as follows:

RNORM: byte-stream mode. This is the default read mode. This is the normal byte-stream mode where message boundaries are ignored. read(2s) and readv(2s) returns data until the read count has been satisfied or a zero length message is received.
RMSGN: message non-discard mode. The read(2s) or readv(2s) will return when either the count is satisfied, a zero length message is received, or a message boundary is encountered. If there is any data left in a message after the read count has been satisfied, the message is placed back on the stream head read queue. The data will be read on a subsequent read(2s) or readv(2s) call.
RMSGD: message discard mode. Similar to RMSGN mode, above, but data that remains in a message after the read count has been satisfied is discarded.
RFILL: message fill mode. Similar to RNORM but requests that the stream head fill a buffer completely before returning to the application. This is used in conjunction with a cooperating module and M_READ(9) messages.

bitwise OR'ed with one flag from the protocol group as follows:

RPROTNORM: fail read when control part present. Fail read(2s) with [EBADMSG] if a message containing a control part is at the front of the stream head read queue. Otherwise, the message is read as normal. This is the default setting for new stream heads. This setting is used with the timod(4) module requiring the use of the tirdwr(4) module for use with the xti(3) library[5].
RPROTDAT: deliver control part of a message as data. The control part of the message is prepended to the data part. This may be useful for specialized libraries or at the user's option with timod(4) or sockmod(4) modules.
RPROTDIS: discard control part of message, delivering any data part. The control part of the message is discarded and the data part is processed. This setting is used with the sockmod(4) module, or at the user's option with other modules or drivers.

Note: Although all modes terminate the read on a zero-length message, POSIX requires that zero only be returned from read when the requested length is zero or an end of file (M_HANGUP(9)) has occurred. Therefore, LfS[6] only returns on a zero-length message if some data has been read already.

I_GRDOPT

Gets the read options flags for the stream head. arg is a pointer to an integer to receive the stream head read options. The integer pointed to by arg will return one flag from the following mode flags:

RNORM: byte-stream mode. This is the default read mode.
RMSGN: message non-discard mode.
RMSGD: message discard mode.
RFILL: message fill mode.

bitwise OR'ed with one flag from the following protocol flags:

RPROTNORM: fail read when control part present.
RPROTDAT: deliver control part of a message as data.
RPROTDIS: discard control part of message, delivering any data part.

Upon success, I_GRDOPT returns zero (0) and the read options flags in the integer pointed to by arg. Upon failure, I_GRDOPT returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points outside the caller's valid address space.

I_SWROPT

Sets the write(2s) options flags for the stream head. These flags alter the behaviour of the write(2) and putmsg(2) calls when called for fd. arg is an integer value containing the write options flags which may be one or more flags from the following:

SNDZERO: send a zero-length message downstream when a write of zero bytes occurs.
SNDPIPE: send SIGPIPE on write(2s) and putmsg(2) if the stream head has received a write error (M_ERROR(9)) message.
SNDHOLD: hold messages briefly in an attempt to coalesce smaller transmissions into larger ones.

I_GWROPT

Gets the write options flags for the stream head. arg is a pointer to an integer to receive the stream head write options. The integer pointed to by arg will return zero or more flags from the following flags: (These flags alter the operations of write(2) and putmsg(2) on a STREAMS character special file.)

SNDZERO: send a zero-length message downstream when a write of zero bytes occurs.
SNDPIPE: send SIGPIPE on write(2s) and putmsg(2) if the stream head has received a write error (M_ERROR(9)) message.
SNDHOLD: hold messages briefly in an attempt to coalesce smaller transmissions into larger ones.

Upon success, I_GWROPT returns zero (0) and the write options flags in the integer pointed to by arg. Upon failure, I_GWROPT returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg pointed outside the caller's valid address space.

I_SERROPT

Sets the error options flags for the stream head. These flags alter the behavior of system calls in response to the receipt of an M_ERROR(9) message at the stream head when called for fd. arg is an integer value containing the error option flags which may be one flag controlling the read error behaviour from the following:

RERRNORM: specifies that read errors are treated as normal and persist until they are cleared with a subsequent M_ERROR(9) message indicating a read error of zero (0), or until the stream is closed. This is the default.
RERRNONPERSIST: specifies that read errors are treated as non-persistent. Once the read error is delivered to a system call, it is cleared automatically.

and one flag controlling the write error behaviour from the following:

WERRNORM: specifies that write errors are treated as normal and persist until they are cleared with a subsequent M_ERROR(9) message indicating a write error of zero (0), or until the stream is closed. This is the default.
WERRNONPERSIST: specifies that write errors are treated as non-persistent. Once the write error is delivered to a system call, it is cleared automatically.

Upon success, I_SERROPT returns zero (0) and the error options flags are set according to the value in arg. Upon failure, I_SERROPT returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]: the flags specified in arg are invalid.

I_GERROPT

Gets ther error options flags for the stream head. arg is a pointer to an integer to receive the stream head error options. The integer pointed to by arg will return one flag from the following flags: (These flags alter the operations of read errors in return to system calls.)

RERRNORM: indicates that read errors are treated as normal and persist until they are cleared with a subsequent M_ERROR(9) message indicating a read error of zero (0), or until the stream is closed. This is the default.
RERRNONPERSIST: indicates that read errors are treated as non-persistent. Once the read error is delivered to a system call, it is cleared automatically.

and one flag from the following flags: (These flags alter the operations of the write errors in return to system calls.)

WERRNORM: indicates that write errors are treated as normal and persist until they are cleared with a subsequent M_ERROR(9) message indicating a write error of zero (0), or until the stream is closed. This is the default.
WERRNONPERSIST: indicates that write errors are treated as non-persistent. Once the write error is delivered to a system call, it is cleared automatically.

Upon success, I_GERROPT returns the error options flags in the integer pointed to by arg. Upon failure, I_GERROPT returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points outside the user's valid address space.

I_LINK

Links one Stream under the multiplexing driver on stream fd. arg is the integer file descriptor of the stream to link under fd.

This call is passed as an I_STR ioctl using an M_IOCTL(9) down the stream head write queue to be processed by the multiplexing driver on fd. I_LINK will block until an acknowledgement is received from the driver, the call times out waiting for an acknowledgement, the call is interrupted while blocked by a signal, or the receipt of hangup or error message.

Upon success, I_LINK returns a positive integer representing the multiplex identifier of the lower stream. This value can be subsequently used in a I_UNLINK command. Upon failure, I_LINK returns -1 and sets errno(3) to an appropriate error number as follows:

[EBADF]: arg is not a valid open file descriptor.
[ETIME]: the command timed out before receiving an acknowledgement.
[ENOSR]: a buffer for the ioctl message could not be allocated.
[EINVAL]: fd received an error message.
[EIO]: the stream specified by fd is closing.
[ENXIO]: the stream specified by fd received a hangup.
[EINVAL]: fd has no lower multiplexing driver definition.
[EINVAL]: arg is already linked under a multiplexer or is not a STREAMS character special file.

In addition, any error received in an error message will be returned in errno. Also, any error returned by the module or driver in an ioctl positive or negative acknowledgement message will also be returned in errno.

I_LIST

List all of the modules pushed on the stream specified by fd. arg is a pointer to a str_list structure to place the module names as follows:

struct str_list {
    int sl_nmods;
    struct str_mlist *sl_modlist;
};

sl_nmods indicates the number of str_mlist structures the array pointed to by sl_modlist. sl_modlist points to a list of str_mlist structures formatted as follows:

struct str_mlist {
    char l_name[FMNAMESZ + 1];
};

If arg is NULL, I_LIST will return a positive integer retval indicating the number of modules, including the driver, on stream fd. This can be used to determine the number of module and driver names before passing the str_list structure.

I_LIST only lists sl_nmods number of modules and drivers starting with the module below the stream head. If there is an insufficient number of members in the sl_modlist array to hold all of the names, I_LIST will success, but will return only the number of names in the space provided.

Upon success, I_LIST returns zero (0) and the module and driver names in the passed in str_list and str_mlist structures, or, when arg is NULL, returns a positive integer indicating the number of modules plus the driver on the stream fd. Upon failure, I_LIST returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg or str_mlist points outside the caller's valid address space.
[EINVAL]: sl_nmods is less than 1, or, str_mlist is NULL.

I_LOOK

Gets the name of the first module beneath the stream head. arg is a pointer to a character string buffer to accept the name. This buffer must be at least (FNAMESZ + 1) in length.

Upon success, I_LOOK copies the name of the module beneath the stream head to the buffer pointed to by arg. Upon failure, I_LOOK returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg pointed outside the caller's valid address space.
[EINVAL]: there is no module beneath the stream head.

I_NREAD

Gets the number of unread data bytes contained in M_DATA(9) message blocks in the first message on the stream head read queue. arg points to an integer to contain the number of unread bytes.

Upon success, I_NREAD returns zero (0) or a positive integer indicating the number of messages on the stream head read queue. Upon failure, I_NREAD returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points outside the caller's valid address space.

I_PEEK

Peeks at the next message on the stream head read queue without removing the message from the queue. arg is a pointer to a strpeek structure formatted as follows:

struct strpeek {
    struct strbuf ctlbuf;
    struct strbuf databuf;
    long flags;
};

ctlbuf: describes the control part of the message, and is formatted the same as the strbuf structure pointed to by ctlptr as an argument to getmsg(2). If there is no control part, the maxlen field of this strbuf should be zero (0).
databuf: describes the data part of the message, and is formatted the same as the strbuf structure pointed to by datptr as an argument to getmsg(2). If there is no data part, the maxlen field of this strbuf should be zero (0).
flags: provides the read flags and is formatted the same as the flags argument to getmsg(2).

Upon success, I_PEEK returns zero (0) if there was no message on the stream head read queue, and returns one (1) and the retrieved message in the structure pointed to by arg, if there was a message on the stream head read queue. Upon failure, I_PEEK returns -1 and sets errno(3) to an appropriate error message as follows:

[EFAULT]: arg, ctlbuf.buf or databuf.buf point outside the caller's valid address space.

In addition, I_PEEK can return any errno(3) returned by getmsg(2). See getmsg(2).

I_PLINK

Links on stream under the multiplexing driver on stream fd. arg is the integer file descriptor of the stream to link under fd.

This call is passed as an I_STR ioctl using an M_IOCTL(9) down the stream head write queue to be processed by the multiplexing driver on fd. I_PLINK will block until an acknowledgement is received from the driver, the call times out waiting for an acknowledgement, the call is interrupted while blocked by a signal, or the receipt of hangup or error message.

Upon success, I_PLINK returns a positive integer representing the multiplex identifier of the lower stream. This value can be subsequently used in a I_PUNLINK command. Upon failure, I_PLINK returns -1 and sets errno(3) to an appropriate error number as follows:

[EBADF]: arg is not a valid open file descriptor.
[ETIME]: the command timed out before receiving an acknowledgement.
[ENOSR]: a buffer for the ioctl message could not be allocated.
[EINVAL]: fd received an error message.
[EIO]: the stream specified by fd is closing.
[ENXIO]: the stream specified by fd received a hangup.
[EINVAL]: fd has no lower multiplexing driver definition.
[EINVAL]: arg is already linked under a multiplexer or is not a STREAMS character special file.

I_POP

Pops the STREAMS module just beneath the stream head from fd. arg is ignored.

Upon success, I_POP pops the moudule beneath the stream head by calling qdetach(9) and returns (0). Upon failure, I_POP returns -1 and sets errno(3) to an appropriate error number as follows:

[EIO]: the stream specified by fd is closing.
[ENXIO]: the stream specified by fd received a hangup.
[EINVAL]: there was no module beneath the stream head.
[EPERM]: an anchor was placed with I_ANCHOR and an attempt is being made by a non-privileged process to pop beneath the anchor position.

See qdetach(9) for more information.

I_PUNLINK

Unlink a stream from under a multiplexing driver that was previously linked with I_PLINK. arg is the multiplexer identifier of the linked stream, or, MUXID_ALL indicating that all linked streams are requested to be unlinked.

When MUXID_ALL is specified, all streams previously linked under the multiplexing driver with I_PLINK will be unlinked.

This call is passed as an I_STR ioctl using an M_IOCTL(9) down the stream head write queue to be processed by the multiplexing driver on fd. I_PUNLINK will block until an acknowledgement is received from the driver, the call times out waiting for an acknowledgement, the call is interrupted while blocked by a signal, or the receipt of hangup or error message.

Upon success, I_PUNLINK returns zero (0) and unlinks the specified stream(s). Upon failure, I_PUNLINK returns -1 and sets errno(3) to an appropriate error number as follows:

[EIO]: the stream specified by fd is closing.
[ENXIO]: the stream specified by fd received a hangup.
[EINVAL]: arg is invalid.
[ETIME]: the call timed out waiting for a response from the driver.
[ERESTARTSYS]: a signal arrived before the operation could begin.
[EINTR]: a signal arrived before the operation could complete.
[ENOSR], [EAGAIN]: could not allocate the buffer for the ioctl message.

In addition, any error received in a error message will be returned in errno. Also, any error returned by the module or driver in a ioctl positive or negative acknowledgement message will also be returned in errno.

I_PUSH

Pushes a STREAMS module by name on the stream specified by fd. arg is a pointer to a string that contains the name of the module to push.

Upon success, I_PUSH pushes the named module and returns zero (0). Upon failure, I_PUSH returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points outside the caller's valid address space.
[EIO]: the stream specified by fd is closing.
[ENXIO]: the stream specified by fd received a hangup.
[ENXIO]: the open procedure of the pushed module failed.
[EINVAL]: the module name pointed to by arg is invalid.
[ENOSR]: fd has reached its maximum push count. No more modules can be pushed on the stream.
[ENOMEM]: memory allocation for the queue pair for the pushed module failed.
[ENOPKG]: the module has no qopen routine.

In addition, any error returned by the module's qopen(9) function may be returned by I_PUSH. See qattach(9) and qopen(9) for more information.

I_ANCHOR

Requests that an anchor be placed at the position beneath the stream head. When an anchor is placed, modules beneath the anchor point can no longer be popped from the stream by non-privileged processing using I_POP. Modules can still be pushed and popped above the anchor by non-privileged processes. If an anchor already exists, the anchor is moved. arg is ignored and should be set to zero (0).

Upon success, I_ANCHOR places the anchor and returns zero. Upon failure, I_ANCHOR returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]: fd specifies a pipe.

I_RECVFD

arg is a pointer to a strrecvfd structure formatted as follows:

struct strrecvfd {
    int fd;
    uid_t uid;
    gid_t gid;
    ...
};

In the strrecfd structure, fd is the file descriptor received, and uid and gid are the credentials associated with the file descriptor.

Upon success, I_RECVFD returns zero (0) and the completed strrecvfd structure. Upon failure, I_RECVFD returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg points outside the caller's valid address space.
[EPIPE]: fd refers to a pipe and the other end of the pipe is closed.
[EIO]: fd is a valid, open, file descriptor, but the stream is closing.
[ENXIO]: fd refers to a stream that has received a hangup.
[EBADF]: fd is not a stream.
[EAGAIN]: no file descriptor message (M_PASSFP(9)) is waiting.
[ENFILE]: no remaining file descriptors could be allocated for the receiving process.
[EBADMSG]: the message on the top of the stream head read queue is not a passed file descriptor (M_PASSFD(9)) message.

I_SENDFD

Sends a file descriptor to the other end of a pipe. arg is the integer file descriptor to send.

Upon success, I_SENDFD returns (0). Upon failure, I_SENDFD returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]: fd is not a STREAMS based pipe.
[EIO]: fd is a valid, open, file descriptor, but the stream is closing.
[ENXIO]: fd refers to a stream that has received a hangup.
[EPIPE]: fd refers to a pipe, but the other end of the pipe is closed.
[EBADF]: arg is not a valid file descriptor.
[ENOSR]: a buffer could not be allocated to send the file descriptor.
[EAGAIN]: the read queue at the other end of the pipe is full.

I_SETCLTIME

Sets the closing delay time for the stream head. arg points to an int that specifies the delay time in milliseconds.

Upon success, I_SETCLTIME returns zero (0) and sets the close delay time for fd. Upon failure, I_SETCLTIME returns -1 and sets errno(3) to an appropriate error number as follows:

[EINVAL]: arg is outside the valid range 0 to 300,000 milliseconds.

I_SETSIG

Sets the mask of events for which the stream head will send the calling process a SIGPOLL or SIGURG signal. arg is an integer value contains one or more of the following event flags:

S_INPUT: any message but high priority on read queue.
S_HIPRI: high priority message on read queue.
S_OUTPUT: write queue is no longer full.
S_MSG: signal message at front of read queue.
S_ERROR: error message arrived at stream head.
S_HANGUP: hangup message arrived at stream head.
S_RDNORM: normal message on read queue
S_WRNORM: same as S_OUTPUT.
S_RDBAND: out of band message on read queue.
S_WRBAND: can write out of band message.
S_BANDURG: modifier to S_RDBAND, to generate SIGURG instead of SIGPOLL.
S_ALL: all flags.

I_STR

Generates an internal STREAMS ioctl message and places it on the stream head's write queue for processing by the module or driver and returns the response. arg is a pointer to a strioctl structure formatted as follows:

struct strioctl {
    int ic_cmd;
    int ic_timout;
    int ic_len;
    char *ic_dp;
};

ic_cmd: is the command to issue. The command can by any of the commands listed here that are handled by the module or driver (e.g. I_LINK) or any other ioctl command understood by a module or driver on the stream fd.
ic_timout: is the period of time to wait for an acknowledgement in milliseconds, or -1 indicating that there is no timeout.
ic_len: is the length of the argument data pointed to by ic_dp.
ic_dp: is a pointer to the argument data of length ic_len bytes.

I_STR generates an M_IOCTL(9) message an passes it downstream to the module or driver and blocks until a positive or negative acknowledgement is received, the command times out, an hangup or error message is received by the stream head, or a signal is received.

Upon success, I_STR returns the return value specified in the positive or negative acknowledgement message. Upon failure, I_STR returns -1 and sets errno(3) to an appropriate error number as follows:

[EFAULT]: arg or ic_dp point outside the caller's valid address space.
[EINVAL]: ic_len is less than 0.
[EINVAL]: ic_len is greater than the maximum size of the data part of a message.
[EINVAL]: ic_timout is less than -1.
[ETIME], [EAGAIN]: the operation timed out waiting for an acknowledgement.
[ERESTARTSYS]: a signal arrived before the operation could begin.
[EINTR]: a signal arrived before the operation could complete.
[EIO]: the stream specified by fd is closing.
[ENXIO]: the stream specified by fd received a hangup.
[ENOSR]: a buffer for the ioctl message could not be allocated.

In addition, I_STR can return any errno(3) placed in an error message received by the stream head, or placed in the positive or negative acknowledgement message by the module or driver.

I_UNLINK

Unlink a stream from under a multiplexing driver that was previously linked with I_LINK. arg is the multiplexer identifier of the linked stream, or, MUXID_ALL indicating that all linked streams are requested to be unlinked.

When MUXID_ALL is specified, all streams previously linked under the multiplexing driver with I_LINK for the specified control stream, fd, will be unlinked.

This call is passed as an I_STR ioctl using an M_IOCTL(9) down the stream head write queue to be processed by the multiplexing driver on fd. I_UNLINK will block until an acknowledgement is received from the driver, the call times out waiting for an acknowledgement, the call is interrupted while blocked by a signal, or the receipt of hangup or error message.

Upon success, I_UNLINK returns zero (0) and unlinks the specified stream(s). Upon failure, I_UNLINK returns -1 and sets errno(3) to an appropriate error number as follows:

[EIO]: the stream specified by fd is closing.
[ENXIO]: the stream specified by fd received a hangup.
[EINVAL]: arg is invalid, or fd is a pipe or FIFO.
[ETIME]: the call timed out waiting for a response from the driver.
[ERESTARTSYS]: a signal arrived before the operation could begin.
[EINTR]: a signal arrived before the operation could complete.
[ENOSR], [EAGAIN]: could not allocate the buffer for the ioctl message.

RETURN VALUE

Upon success, ioctl() returns zero (0) or a positive integer. Upon failure, ioctl() returns -1 and sets errno(3) to an appropriate error number.

ERRORS

When ioctl() fails, it returns -1 and sets errno(3) to one of the following errors:

[EFAULT]: arg or a member of arg, points to an address that is outside the caller's valid address space.
[EINVAL]: fd, command, arg or a member of arg is invalid.
[EBADF]: fd is not a valid open file descriptor.
[ENOSTR]: fd is not a stream special character device.
[EOPNOTSUPP]: fd does not support the requested operation.
[EIO]: fd refers to stream that is closing.
[ENOTTY]: fd does not refer to a STREAMS device that accepts I/O controls.
[ENODEV]: fd refers to a STREAMS device that does not support the ioctl(2s) system call.
[ENXIO]: fd refers to stream that has received a hangup.
[ENXIO]: the I/O control command cannot be performed by this particular sub-device.
[EPIPE]: fd refers to a pipe and the other end of the pipe is closed.
[ESTRPIPE]: fd refers to a STREAMS-based pipe and a write operation was attempted with no readers at the other end, or a read operation was attempted, the pipe is empty, and there are no readers at the other end. (This error is returned by strread(9) and strwrite(9) internally and should not be exposed to the user. Instead, a [EPIPE] should be generated.)
[EINVAL]: fd refers to a stream that is linked under a multiplexing driver. If a stream is linked under a multiplexing driver, all ioctl(2s) commands other than I_UNLINK or I_PUNLINK will return [EINVAL].
[ERESTARTSYS]: a signal was received before the operation could begin.
[EINTR]: a signal was recievied before the operation could complete.
[EAGAIN], [EWOULDBLOCK]: the file is set for asynchronous I/O and the operation would block.
[ETIME]: the operation timed out awaiting an acknowledgement or response from the driver.
[ENOSR]: a message block could not be allocated during the operation and the operation is not permitted to block.

Any error delivered to the stream head in an M_ERROR(9) message can be returned in errno(3).

Where the command is passed to the module or driver, or the command results in the call to a module or driver open or close procedures, or link or unlink procedures, the error number returned by the module or driver open or close procedure can be returned in errno(3).

Any error returned in an M_IOCNAK(9) message from the driver in response to a I_STR ioctl can be returned in errno(3).

NOTICES

STREAMS ioctl() calls are complex and there is much conflicting documentation in specific areas of behaviour. Not all bugs are bugs and not all features are features.

BUGS

streamio has no known bugs.

STREAMS ioctl() calls are complex and there is much conflicting documentation in specific areas of behaviour. Not all bugs are bugs and not all features are features.

COMPATIBILITY

streamio is compatible with SVR 4.2[7], Solaris®, UnixWare® and LiS[8], with the following portability considerations:

---: Linux Fast-STREAMS supports the RFILL read mode. This read mode is AIX®[9] specific.
---: Linux Fast-STREAMS provides ioctls that are used to implement this system call.
---: Linux Fast-STREAMS recognizes some Solaris®-specific and LiS-specific IO control numbers for compatibility.
---: The numbering of standard input-output control commands for STREAMS(9) is split between SVR 4.2-style[7] implementations and OSF/1.2-style[10] style implementations. The OpenGroup SUS/POSIX specifications specify the input-output control names, but not the numbering. Specific intput-output control numbers that differ between SVR 4.2 and OSF/1.2 are: I_SWROPT(7), I_GWROPT(7), I_LIST(7), I_FLUSHBAND(7), I_CKBAND(7), I_GETBAND(7), I_ATMARK(7), I_SETCLTIME(7), I_GETCLTIME(7), I_CANPUT(7).
: (If we were smart, we would change the numbering in <sys/stropts.h> depending upon the processor for which the package is compiled to match the particular UNIX® vendor's numbering scheme.)
---: Two standard input-output control commands,--- I_PLINK(7) and I_PUNLINK(7), differ in numbering between SVR 3[11], and SVR 4[12].
---: AIX® HP-UX®, and UnixWare® document that, when command is I_SETCLTIME, arg is a pointer to an integer timeout value. Solaris® documents that, when command is I_SETCLTIME, arg is a long timeout value. LiS follows Solaris®. SUSv2[13] documents that, when command is I_SETCLTIME, arg is a pointer to an integer timeout value. Solaris® can be seen in strace(8) output to pass a pointer instead of a value. This means that Solaris® documentation is erroneous, and LiS implementation is wrong.
: Portable STREAMS(9) libraries and applications programs will use Linux Fast-STREAMS instead of LiS.

CONFORMANCE

SVID[14], XID[15], SUSv2[13], SUSv3[16], POSIX.

Conformance is tested using the test-streams(8) test case executable and the Linux Fast-STREAMS autotest test suite.

HISTORY

ioctl() for STREAMS first appeared in SVR 3[11].

REFERENCES

[1]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[2]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[3]: HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>
[4]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[5]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9] 525.
[6]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[7]: SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[8]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[9]: AIX® 5L Version 5.1, AIX Communications Programming Concepts, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. "Differences Between Portable Streams Environment and V.4 STREAMS" <http://publibn.boulder.ibm.com/>
[10]: Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[11]: SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[12]: SVR 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[13]: SUS Version 2, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[14]: SVID, System V, Interface Definition, Fourth Edition.
[15]: XBD Issue 5, X/Open System Interface Definitions, Issue 5, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[16]: SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>