I_STR streamio Operation

Purpose

Constructs an internal STREAMS ioctl message.

Description

The I_STR operation constructs an internal STREAMS ioctl message from the data pointed to by the arg parameter and sends that message downstream.

This mechanism is provided to send user ioctl requests to downstream modules and drivers. It allows information to be sent with the ioctl and returns to the user any information sent upstream by the downstream recipient. The I_STR operation blocks until the system responds with either a positive or negative acknowledgment message or until the request times out after some period of time. If the request times out, it fails with the errno global variable set to ETIME.

At most, one I_STR operation can be active on a stream. Further I_STR operation calls block until the active I_STR operation completes at the stream head. The default timeout interval for this request is 15 seconds. The O_NDELAY flag has no effect on this call.

To send a request downstream, the arg parameter must point to a strioctl structure that contains the following elements:

int  ic_cmd;      /* downstream operation */
int  ic_timeout;   /* ACK/NAK timeout */
int  ic_len:      /* length of data arg */
char *ic_dp;      /* ptr to data arg */

The elements of the strioctl structure are described as follows:

Element	Description
`ic_cmd`	The internal ioctl operation intended for a downstream module or driver.
`ic_timout`	The number of seconds an I_STR request waits for acknowledgment before timing out: -1 Waits an infinite number of seconds. 0 Uses default value. > 0 Waits the specified number of seconds.
`ic_len`	The number of bytes in the data argument. The `ic_len` field has two uses: On input, it contains the length of the data argument passed in. On return from the operation, it contains the number of bytes being returned to the user (the buffer pointed to by the `ic_dp` field should be large enough to contain the maximum amount of data that any module or the driver in the stream can return).
`ic_dp`	A pointer to the data parameter.

The stream head converts the information pointed to by the strioctl structure to an internal ioctl operation message and sends it downstream.

This operation is part of STREAMS Kernel Extensions.

Error Codes

If unsuccessful, the errno global variable is set to one of the following values:

Value	Description
EAGAIN	The value of ic_len is greater than the maximum size of a message block returned by the STREAMS allocb utility, or there is insufficient memory for a message block.
ENOSR	Unable to allocate buffers for the ioctl message due to insufficient STREAMS memory resources.
EFAULT	The area pointed to by the arg parameter or the buffer area specified by the `ic_dp` and `ic_len` fields (for data sent and data returned, respectively) is outside of the allocated address space.
EINVAL	The value of the `ic_len` field is less than 0 or greater than the maximum configured size of the data part of a message, or the value of the `ic_timout` field is less than -1.
ENXIO	Hangup received on the `fildes` field.
ETIME	A downstream streamio operation timed out before acknowledgment was received.

An I_STR operation can also be unsuccessful while waiting for an acknowledgment 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 acknowledgment messages, in the event that the streamio operation sent downstream fails. For these cases, the I_STR operation is unsuccessful and the errno global variable is set to the value in the message.