STREAMS-UX Programmer's Guide (February 2007)

Message Types
Ordinary Messages
Appendix C
241
Where ic_cmd describes the command intended for module or driver, ic_timout specifies the number of
seconds that the I_STR request will wait for an acknowledgement before timing out. ic_dp points to the data
buffer, and ic_len is the length of the data buffer passed in and, on return from the call, it contains the
length of the data (if any) in the being returned to the user.
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 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 */
For an I_STR IOCTL, ioc_cmd corresponds to ic_cmd of the strioctl structure. The ioc_cr points to a
credentials structure (see <sys/cred.h>) defining the process’s permissions. The ioc_cnt is the number of
data bytes, if any, contained in the message and corresponds to ic_len. The ioc_id is an internally
generated identifier used by stream head to match each M_IOCTL message sent downstream, with responses
that come upstream to the stream head. An M_IOCACK or M_IOCNACK response message completes the IOCTL
processing.
For I_STR IOCTL, the user supplied data to be sent to the module or driver is attached as zero or more
M_DATA messages and is linked to the initial M_IOCTL message block. The ioc_cnt is copied from ic_len. If
there is no data, ioc_cnt is zero.
When the stream head does not recognize an IOCTL command, it creates a transparent M_IOCTL message.
The M_IOCTL message for transparent processing consists of an M_IOCTL message block followed by one
M_DATA message block containing the address of the third argument to the ioctl() system call. The form of
the iocblk structure is same as previously noted. However, ioc_cmd is set to the user-specified IOCTL
command and ioc_cnt is set to a special constant TRANSPARENT defined in <sys/stream.h>.
TRANSPARENT recognizes the transparent nature of the M_IOCTL message when an I_STR IOCTL may
specify a value of ioc_cmd equivalent to the user-specified IOCTL command argument of a transparent
IOCTL. The first module to recognize the IOCTL command in ioc_cmd will process the M_IOCTL message.
Intermediate modules that do not recognize the IOCTL command must pass the message on. If, the driver
does not recognize the IOCTL command, it must respond with an M_IOCNAK message to stream head.
The M_IOCACK and M_IOCNAK message types have the same format as an M_IOCTL message and contain an
iocblk structure in the first block. An M_IOCACK block may be linked to zero or more M_DATA blocks. If an
M_IOCACK or M_IOCNAK message reaches the stream head with an identifier, which does not match that of the
currently outstanding M_IOCTL message, the response message is discarded. Usually, to assure a correct
response, the replying module converts the M_IOCTL message into an M_IOCACK or M_IOCNAK message and
returns to stream head. If no data is returned, the ioc_cnt in the M_IOCACK message is set to zero. The
ioc_error is set to any return error condition by the downstream module. If this value is non-zero, it is
returned to the user in errno. A return value can be specified only with M_IOCACK message by setting
ioc_rval field. For M_IOCNAK messages stream head ignores ioc_rval field.
For I_STR IOCTL, if the module wants to send data to the user process, it must use the M_IOCACK message to
send the data by linking one or more M_DATA blocks to it and setting ioc_cnt to number of data bytes. The
stream head places the data in the address pointed to by ic_dp in the user I_STR strioctl structure.
For transparent IOCTL, if the module wants to send data to the user process, it must use an M_COPYOUT
message. The stream head will ignore any data contained in the M_IOCACK message.