Constructs an internal STREAMS ioctl message.
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:
|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:|
|ic_len||The number of bytes in the data argument. The ic_len
field has two uses:
|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.
If unsuccessful, the
errno global variable is set to one of the following values:
|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.
This operation is part of STREAMS Kernel Extensions.
The timod Module.
The streamio operations.
Understanding STREAMS Messages in AIX 5L Version 5.1 Communications Programming Concepts.