STREAMS-UX Programmer's Guide (February 2007)

STREAMS IOCTL Commands
Overview
Appendix A
140
I_CANPUT
Checks if a certain band is writable. The arg parameter is set to the priority band in question. The return
value is 0, if the priority band arg is flow controlled. The return value is 1, if the band is writable, or -1 on
error.
On failure, errno may be set to the following value:
[EINVAL] arg has an illegal value.
I_CKBAND
This command is used to check if the message of a given priority band exists on the stream head read queue.
This returns 1 if a message of a given priority exists or -1 on error. The arg should be an integer containing
the value of the priority band in question.
On failure, errno may be set to the following value:
[EINVAL] arg has an illegal value.
I_FDINSERT
This command causes the stream head to create a message from user specified buffer(s), add information
about another stream and send the message downstream. The message contains a control part and an
optional data part. The data and control parts to be sent are distinguished by placement in separate buffers,
as described:
The arg points to a strfdinsert structure which contains the following members:
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
int fildes;
int offset;
ctlbuf The len field in the strbuf structure of the ctlbuf field (see putmsg (2)) must be set to the
size of a pointer plus the number of bytes of control information to be sent with the message.
databuf The len field in the strbuf structure of the databuf field (see putmsg (2)) must be set to the
number of bytes of data information to be sent with the message or zero if no data part is to
be sent.
flags This field specifies the type of message to be created. An ordinary (non-priority) message is
created if the flags are set to 0, a high priority message is created if flags is set to RS_HIPRI.
For normal messages, I_FDINSERT will block if the stream head write queue is full due to
internal flow control conditions. For high priority messages, I_FDINSERT does not block on
this condition. For normal messages, I_FDINSERT does not block when the write queue is
full and the O_NONBLOCK is set. Instead, it fails and sets errno to EAGAIN.
fildes The strfdinsert structure specifies the file descriptor of the other stream.
offset Specifies the number of bytes beyond the beginning of the control buffer where I_FDINSERT
will store a pointer, must be word-aligned. This pointer will be the address of the read queue
structure of the driver for the streams corresponding to fildes in the strfdinsert
structure.
I_FDINSERT also blocks, unless prevented by the lack of internal resources, waiting for the availability of
message blocks, regardless of priority or whether O_NONBLOCK has been specified. No partial message is sent.