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.