OSF

NAME

streamio − STREAMS ioctl commands

SYNOPSIS

#include <sys/types.h>
#include <sys/stream.h>
#include <sys/stropts.h> int ioctl(
int fildes,
const command,
int arg);

PARAMETERS

fildesContains the open file descriptor for the stream to be operated on. 

commandSpecifies the command function to be performed on the stream. 

argContains additional information that the specified command needs for performing  its function, if needed.  The arg parameter value can be of any type, but is usually an integer, or a pointer to a command-specific structure. 

DESCRIPTION

The STREAMS ioctl commands are used with the ioctl() system call to perform control operations on streams.  User processes can use these commands on all STREAMS file types. 

When the stream head receives a STREAMS ioctl system call, it interprets the command parameter and arg parameter, when specified, into an M_IOCTL message.  In some cases, the command and arg parameters are passed on to a module or driver in the stream. 

The same errors can occur for the STREAMS ioctl commands as for the other commands that are used with the ioctl() system call.  Additionally, a STREAMS ioctl call will fail without performing the function and with errno set to [EINVAL]:

       •If the stream referred to by fildes is linked below a multiplexing driver. 

       •If command is not a valid value for the stream. 

The modules or drivers in a stream can also detect errors.  When they do, they send an error message containing an error number to the stream head.  Subsequent system calls will fail with errno set to this number.  More specific information about the errors for STREAMS ioctl commands can be found in the ERRORS section of this reference page. 

ioctl Commands

The STREAMS ioctl commands are the following:

I_PUSHPushes the module whose name is pointed to by arg on to the stream, just below the stream head, then calls the open routine of the module. 

I_POPRemoves the module just below the steam head on the stream referred to by fildes.  The arg parameter must be set to the value 0 (zero) in the request. 

I_LOOKRetrieves the name of the module located just below the stream head of the stream referred to by fildes, placing it in a null terminated character string pointed to by arg.  The arg parameter should point to a buffer, whose size is at least FMNAMESZ+1 bytes.  The user program must contain the declaration #include <sys/stream.h> for the header file. 

I_FLUSHFlushes the input and output queues of the stream head and all of the modules and drivers on the stream, according to the value of arg.  The arg parameter value can be one of the following:

FLUSHRFlush read queues. 

FLUSHWFlush write queues. 

FLUSHRWFlush read and write queues. 

ing: R, FLUSHW, or FLUSHRW. 

I_SETSIGInforms the stream head that the user process wishes the kernel to issue a SIGPOLL signal for a particular event that can occur on a stream.  This provides support for asynchronous processing in STREAMS. 

The arg parameter value is a bitmask that specifies the events for which to signal the user process.  The value is the bitwise-OR of any combination of the following constants:

S_INPUTA message other than an M_PCPROTO type message has arrived on the stream head read queue.  This bit is set even if a message is a zero length message.  The S_INPUT option is maintained for compatibility with SVID 2.  h SVID 2.  h message. 

S_HIPRIA high priority message has arrived on the stream head read queue.  This bit is set even if a message is a zero length message. 

S_OUTPUTThe write queue of the module just below the stream head is no longer full.  There is room on the queue for the user process to send (write) data to the stream.  d (write) data
 on the queue.

S_MSGA STREAMS signal (M_SIG) containing the SIGPOLL signal has reached the front of the stream head read queue.  The SIGPOLL signal is generated to the user if S_MSG is enabled.  If it is not, SIGPOLL is not sent.  s enabled.  If it e. [CHECK THIS SENTENCE]

User processes that wish to receive SIGPOLL (or SIGURG) signals must register explicitly with the Stream head using the I_SETSIG command.  When more than one user process registers to receive the signal for the same event on a stream, each is signaled when the event occurs.  If the value of arg is 0 (zero), the calling process is not registered and does not receive the signal. 

I_GETSIGReturns the events for which the calling process has registered to receive a SIGPOLL signal.  Events are returned as in arg bitmask as defined for the I_SETSIG command. 

I_FINDCompares the names of all modules currently present on the the stream to the name specified in arg.  The command returns a 1 (one) value if the module is present and a 0 (zero) value if the the module is not present. 

I_PEEKAllows the user process to look at the contents of the first message on the stream head read queue, without taking the message off the queue.  The I_PEEK ioctl operates the same way as the getmsg() function, except that it does not remove the message.  The arg parameter points to a strpeek structure (in the stropts.h header file) containing the following members:

struct strbufctlbuf;
struct strbufdatabuf;
longflags;

The strbuf structure pointed to by ctlbuf and databuf has the following members:

int maxlen;
int len;
char ∗buf

The maxlen field of the strbuf structure must specify the number of bytes of control information or data information to be retrieved.  The flags field can be set to RS_HIPRI or 0 (zero).  If this field is set to RS_HIPRI, the I_PEEK ioctl looks for a high priority message on the queue.  If the field is set to 0, the I_PEEK ioctl looks at the first message on the queue. 

The I_PEEK ioctl returns a 1 (one) value if a message was retrieved, and returns a 0 if not message was found.  It does not wait for a message to arrive.  On return, ctlbuf specifies control information in the control buffer, databuf specifies data information in the data buffer, and flags contains RS_HIPRI or 0. 

I_SRDOPTSets the read mode of the Stream (see read()) according to the value of arg.  The arg value specifies the following read modes related to data and message boundaries:

RNORMByte-stream mode (the default).  The read() function completes when the byte count is satisfied, the stream head read queue is empty, or a zero length message is encountered.  In the case of a zero length message, the message is placed back on the queue, and a subsequent read() returns 0 bytes. 

RMSGDMessage-discard mode.  The read() function completes when the byte count is satisfied, or a message boundary is reached.  Any remaining data in the message are discarded. 

RMSGNMessage-nondiscard mode.  The read() function completes when the byte count is satisfied, or a message boundary is reached.  Any data remaining in the message are put back on the read queue. 

read queue.  fB[CHECK ON THIS]

I_GRDOPTReturns the current read mode setting of the stream (see the read() function) in an integer pointed to by arg. 

I_NREADCounts the bytes in the data blocks of the first message on the stream head read queue, placing this value in the location pointed to by arg.  The value returned for the I_NREAD ioctl is the number of messages on the queue.  For example, if the ioctl results in a 0 (zero) value in arg, but a return value greater than 0, the first message in the queue contains 0 bytes. 

I_FDINSERT
Creates a message from a user specified buffer or buffers, adds information about another stream, and sends the message downstream. The message contains a control part and an optional data part, which are placed in separate buffers, ctlbuf and databuf pointed to by arg.  These buffers are contained in an strfdinsert structure (defined in the stropts.h header file), whose members are as follows:

struct strbufctlbuf;
struct strbufdatabuf;
longflags;
intfildes;
intoffset;

The strbuf structure pointed to by ctlbuf and databuf has the following members:

int maxlen;
int len;
∗char ∗buf

The len field of the strbuf structure for ctlbuf must specify the size of a pointer, plus the number of control bytes to be sent in the message. 

The fildes field in the strfdinsert structure specifies the file descriptor of the stream in which the message will be sent. 

The offset field, which must be properly aligned, must specify the number of bytes beyond the beginning of the control buffer where the I_FDINSERT command will store a pointer.  This pointer will be the address of the read queue structure of the device driver for the stream designated by fildes in the strfdinsert structure. 

The len field in the strbuf structure for databuf must be set to the number of bytes of data information to be sent with the message, or to 0 (zero) if no data part is to be sent. 

The flags field specifies the type of message to be created.  When this field contains 0 (zero), the I_FDINSERT command creates an ordinary message.  When the field is set to RS_HIPRI, the I_FDINSERT command creates a high priority message.  The ioctl will block for an ordinary message if the named stream’s read queue is full due to internal flow control conditions.  It will not block on these conditions for a high priority message.  For ordinary messages, the ioctl will not block when the write queue is full and O_NDELAY or O_NONBLOCK (see the open() function) is specified.  It will fail and sets errno to [EAGAIN].  ) function) ther O_NDELAY

The I_FDINSERT ioctl can also fail if an error (M_ERROR) message was received by the stream specified by the fildes field in the strfdinsert structure.  In this case, errno is set to the error value in the error message. 

I_STRBuilds a STREAMS ioctl (M_IOCTL) message from the data pointed to by arg and sends the message downstream to a module or driver.  The command allows a user process to send data with an ioctl request, and to receive any information that the downstream recipient of the message returns.  The I_STR ioctl blocks until the intended recipient of the M_IOCTL message responds with a positive acknowledgement (M_IOCACK) message or negative acknowledgement (M_IOCNAK) message, or until the request times out (default time = 15 seconds).  If the request times out, it fails with errno set to [ETIME]. 

Only one I_STR ioctl can be active on a stream at a time.  Other requests must wait until the active request completes at the stream head.  The O_NDELAY and O_NONBLOCK flags (see the open() function) have no effect on the call. 

User values for the I_STR ioctl request are supplied by a strioctl structure (in the stropts.h header file), to which the arg parameter points.  The members of strioctl structure are the following:

intic_cmd;
intic_timeout;
intic_len;
char∗ic_dp;

The ic_cmd field of the strioctl structure contains the ioctl command to be sent to the downstream module or driver.  The ic_timeout field specifies the number of seconds that the I_STR request will wait for an acknowledgement before timing out (-1 = infinite; 0 = use default, which is infinite; >0 = use specified value).  On input, the ic_len field contains the length of the data argument.  On return, it contains the number of bytes being returned to the user process, (the buffer pointed to by ic_dp).  The buffer pointed to by ic_dp should be large enough to contain the maximum amount of data that any module or driver in the stream can return. 

The I_STR ioctl can also fail if the stream head receives a message indicating an error (M_ERROR) or a hangup (M_HANGUP).  In addition, an error can be returned in an M_IOCACK or M_IOCNAK message.  In these cases, the ioctl will fail with errno set to the error value in the message.  o set to the N SET BY A PREVIOUSLY ISSUED

I_LINKConnects two streams, where fildes is the file descriptor of the stream associated with a multilexing driver, and arg is the file descriptor of the stream associated with another driver.  The stream referred to by arg is connected below the multiplexing driver. 

The I_LINK ioctl requires a multiplexing driver to send an acknowledgement message (M_IOCACK or M_IOCNAK) to the stream head about the linking operation.  On success, the call returns a multiplexor ID number, which is an identifier that is used to disconnect the link (see the I_UNLINK command).  If the request fails, it returns a -1. 

The I_LINK ioctl can also fail if it is waiting for the multiplexing driver to acknowledge the link request and an error (M_ERROR) message, or hangup (M_HANGUP) message is received at the stream head for fildes.  In addition, an error can be returned in an M_IOCACK or M_IOCNAK message.  When this occurs, the I_LINK ioctl will fail with errno set to the value in the message. 

I_UNLINKDisconnects two streams, where fildes is the file descriptor of the stream associated with a multilexing driver and arg is the multiplexor identifier number returned by the I_LINK ioctl, which created the multiplexing configuration.  If arg is MUXID_ALL (defined in the stropts.h header file), all streams connected to the stream referred to by fildes are disconnected. 

The I_UNLINK ioctl requires a multiplexing driver to send an acknowledgement message (M_IOCACK or M_IOCNAK) to the stream head about the unlinking operation. 

An I_UNLINK ioctl can also fail if it is waiting for the multiplexor to acknowledge the unlink request and an error (M_ERROR) message, or hangup (M_HANGUP) is received at the stream head for fildes.  In addition, an error can be returned in M_IOCACK or M_IOCNAK message.  When this occurs, the UNI_LINK ioctl will fail with errno set to the value in the message.  _IOCNAK message. 

EXAMPLES

The following example shows how to open a Stream to a device, dev1, and push the module, mod1, onto the Stream:

int fd;
fd = open("/dev/streams/dev1", O_RDWR);
if (ioctl(fd, I_PUSH, "mod1") < 0) {
       perror("I_PUSH ioctl failed");
       exit(1);
}

The following example shows how to open Streams to two devices, dev1 and dev2, and how to link the Stream to dev2 under the Stream to dev1:

int fd1, fd2;
fd1 = open("/dev/streams/dev1", O_RDWR);
fd2 = open("/dev/streams/dev2", O_RDWR);
if (ioctl(fd1, I_LINK, fd2) < 0) {
       perror("I_LINK ioctl failed");
       exit(1);
}

RETURN VALUES

Unless specified differently for a command, the return value for a STREAMS ioctl() call is 0 (zero) on success and -1 (minus one) on failure. 

ERRORS

On failure, the STREAMS ioctl commands return the following errors: I_PUSH

[EINVAL]Invalid module name. 

[EFAULT]arg points outside the allocated address space. 

[ENXIO]Error value returned by the module being pushed.  The push has failed. 

Hangup was received on fildes. 

I_POP

[EINVAL]The named module is not present on the stream. 

[ENXIO]Error value returned by the module being popped.  The pop has failed. [TRUE?]

Hangup received on fildes. 

I_LOOK

[EINVAL]The named module is not present on the stream. 

[EFAULT]arg points outside the allocated address space. 

I_FLUSH

[ENOSR]Unable to allocate buffers for flush operation due to a lack of STREAMS memory resources. 

[EINVAL]Invalid arg value. 

[ENXIO]a lack of STREAMS Hangup was received on fildes. 

I_SETSIG

[EINVAL]The user process is not registered to receive the SIGPOLL signal. 

[EAGAIN]A data structure to store the signal request could not be allocated. 

 be allocated.  d bi_flag is not set I_GETSIG

[EINVAL]User process is not registered to receive the SIGPOLL signal. 

[EFAULT]arg points outside the allocated address space. 

I_FIND

[EINVAL]arg does not contain a valid module name. 

[EFAULT]arg points outside the allocated address space. 

I_PEEK

[EINVAL]Illegal value for flags. 

[EFAULT]arg points, or ctrlbuf or databuf is, outside the allocated address space. 

[EBADMSG]Message to be looked at is not valid for the I_PEEK command. 

I_SRDOPT

[EINVAL]arg does not contain a legal value. 

I_GRDOPT

[EINVAL]arg points outside the allocated address space. 

I_NREAD

[EFAULT]arg points outside the allocated address space. 

I_FDINSERT

[EINVAL]fildes in the strfdinsert structure is not a valid, open file descriptor. 

The size of the pointer plus offset is greater than the value of the en field for the buffer specified through ctlptr. 

offset does not specify a properly aligned location in the data buffer. 

flags contains an undefined value. 

[EFAULT]arg points, or ctrlbuf or databuf is, outside the allocated address space. 

[EAGAIN]The ioctl request failed because a non-priority message was to be created, the O_NDELAY or O_NONBLOCK flag was set, and the stream’s write queue was full due to internal flow control conditions. 

[ENOSR]Buffers could not be allocated for the message that was to be created due to insufficient STREAMS memory resources. 

[ENXIO]Hangup was received on the stream specified by fildes in the I_FDINSERT ioctl call or on the stream specified by fildes in the strfdinsert. 

[ERANGE]The value of the len field for the buffer specified through databuf does not fall within the range for the minimum and maximum sizes of packets for the topmost module on the stream. 

The value of the len field for the buffer specified through databuf is larger the the maximum allowable size for the data part of a message. 

The value of the len field for the buffer specified through ctlbuf is larger the the maximum allowable size for the control part of a message. 

I_STR

[EINVAL]ic_len is less than 0 (zero) bytes or larger than the maximum allowable size of the data part of a message (ic_dp). 

ic_timeout is less than -1. 

[EFAULT]arg points, or the buffer area specified by ic_dp or ic_len is, outside the allocated address space. 

[ENOSR]Buffers could not be allocated for the ioctl request due to a lack of STREAMS memory resources. 

[ENXIO]Hangup was received on the stream referred to by fildes. 

[ETIME]The ioctl request timed out before an acknowledgement was received. 

ement was received.  I_LINK

[ENXIO]Hangup was received on fildes. 

[EAGAIN]Temporarily unable to allocate storage to perform the linking operation. 

[EBADF]arg is not a valid, open file descriptor. 

[EINVAL]The stream referred to by fildes does not support multiplexing. 

The file referred to by arg is not a stream, or the stream is already linked under a multiplexor. 

The link operation would cause a "cycle" in the resulting multiplexing configuration.  That is, the driver referred to by arg is linked into this configuration at more than one place. 

I_UNLINK

[ENXIO]Hangup was received on fildes. 

[ETIME]Timeout occured before an acknowledgement message was received at the stream head. 

[EINVAL]arg is not a valid multiplexor ID number, or fildes is already linked under a multiplexing driver. 

STREAMS FIFO.  STREAMS FIFO. 

FILES

/sys/stream.h
The system file containing all of the structure and constant definitions for STREAMS.

/sys/types.h
The system file that contains type definitions used in STREAMS header files.

/sys/stropts.h
The system file that contains definitions of the arguments to the ioctl system call required by users and STREAMS modules and drivers. 

/sys/errno.h
The system file that contains definitions of the possible values of errno that can be set by the ioctl system call. 

/sys/signal.h
The system file that contains definitions of the valid signal values.

/sys/file.hThe system file that contains file structure information. 

RELATED INFORMATION

Functions: close(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2), putmsg(2), read(2), sigaction(2), write(2) Files: signal(4)