STREAMS-UX Programmer's Guide (February 2007)

Modules and Drivers
Entry Points
Chapter 4
72
The timeout value for STREAMS IOCTL is infinite except for I_STR IOCTLs where a user can specify a
timeout value.
Modules must pass an unrecognized M_IOCTL message to the next component on the stream without any
modifications to the message.
Drivers must respond with an M_IOCNAK message to the stream head for an unrecognized M_IOCTL message.
At any point in time only one ioctl (2) system call is active on the stream head.
An M_IOCTL message consists of an M_IOCTL message block followed by zero or more M_DATA blocks. The
M_IOCTL message block contains an iocblk structure defined in <sys/stream.h> and has the following
fields:
int ioc_cmd; /* ioctl command type */
cred_t * ioc_cr; /* pointer to full credentials */
uint ioc_id; /* ioctl id */
uint ioc_flag; /* see flag values below */
ioc_pad ioc_cnt; /* count of bytes in data field */
int ioc_error; /* error code */
int ioc_rval; /* return value */
The ioc_cmd, ioc_cr, ioc_uid and ioc_id fields of the iocblk structure must not be modified by modules or
drivers.
The ioc_error is an optional field that can be used for setting error codes to accompany an M_IOCNAK or
M_IOCACK message.
The ioc_rval can be used to return a value to user application.
If a module or driver detects an error while processing the M_IOCTL message, it must send a negative
acknowledgement (M_IOCNAK) upstream. For an M_IOCNAK message no data or return value can be sent to
user. If ioc_error is set to zero, the stream head will return EINVAL to user indicating ioctl (2) system call
failure. Alternatively, the driver can specify a different ioc_error value if desired. can be used to return a
value to user application.
For the positive acknowledgment (M_IOCACK) message a return value can be sent to the user along with the
M_IOCACK message. For the I_STR IOCTLs the return value can be sent in ioc_rval field and for transparent
IOCTLs a more general mechanism is used as explained in the “Transparent IOCTL Processing” section.
If stream head does not receive an M_IOCACK or M_IOCNAK message in response to an M_IOCTL message, it will
block all IOCTL calls except for I_STR IOCTLs. For I_STR IOCTLs if an M_IOCACK or M_IOCNAK message is not
received as a response to an M_IOCTL message, it will fail when the timeout expires and is blocked when the
timeout is infinite.
I_STR IOCTL Processing
A user process can make I_STR IOCTL
call325466665555555555555555555555555555555555555555555555555555555477777777777777777777777
777777777777777777777777777777777777777777777777777777777777777777777777777777777777777777
777777777777777777777777777777777777777777774444444444444444444444444444444444444444444444
44444444444444444444444444444444444444444444444444444444444444s by setting the
cmd parameter to
I_STR, and the
arg parameter to a buffer in user space of type strioctl as shown:
if (ioctl (fd, I_STR, &strioctl) < 0) {
perror("I_STR ioctl failed");
exit();