Creates a message from user-specified buffers, adds information about another stream and sends the message downstream.
The I_FDINSERT operation creates a message from user-specified buffers, adds information about another stream, and sends the message downstream. The message contains a control part and an optional data part. The data and control parts transmitted are identified by their placement in separate buffers. The arg parameter points to a strfdinsert structure that contains the following elements:
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
int fildes;
int offset;The len field in the strbuf structure must be set to the size of a pointer plus the number of bytes of control information sent with the message. The fildes field in the strfdinsert structure specifies the file descriptor of the other stream. The offset field, which must be word-aligned, specifies the number of bytes beyond the beginning of the control buffer to store a pointer. This pointer will be the address of the read queue structure of the driver for the stream corresponding to the fildes field in the strfdinsert structure. The len field in the strbuf structure of the databuf field must be set to the number of bytes of data information sent with the message or to 0 if no data part is sent.
The flags field specifies the type of message created. There are two valid values for the flags field:
| Value | Description |
|---|---|
| 0 | Creates a nonpriority message. |
| RS_HIPRI | Creates a priority message. |
For nonpriority messages, the I_FDINSERT operation blocks if the stream write queue is full due to internal flow-control conditions. For priority messages, the I_FDINSERT operation does not block on this condition. For nonpriority messages, the I_FDINSERT operation does not block when the write queue is full and the O_NDELAY flag is set. Instead, the operation fails and sets the errno global variable to EAGAIN.
The I_FDINSERT operation also blocks unless prevented by lack of internal resources, while it is waiting for the availability of message blocks in the stream, regardless of priority or whether the O_NDELAY flag has been specified. No partial message is sent.
This operation is part of STREAMS Kernel Extensions.
If unsuccessful, the errno global variable is set to one of the following values:
| Value | Description |
|---|---|
| EAGAIN | A nonpriority message was specified, the O_NDELAY flag is set, and the stream write queue is full due to internal flow-control conditions. |
| ENOSR | Buffers could not be allocated for the message that was to be created due to insufficient STREAMS memory resources. |
| EFAULT | The arg parameter points to an area outside the allocated address space, or the buffer area specified in the ctlbuf or databuf field is outside this space. |
| EINVAL | One of the following conditions has occurred:
The fildes field in the strfdinsert structure is not a valid, open stream file descriptor. The size of a pointer plus the value of the offset field is greater than the len field for the buffer specified through the ctlptr field. The offset parameter does not specify a properly aligned location in the data buffer. An undefined value is stored in the flags parameter. |
| ENXIO | Hangup received on the fildes parameter of the ioctl call or the fildes field in the strfdinsert structure. |
| ERANGE | The len field for the buffer specified through the databuf field does not fall within the range specified by the maximum and minimum packet sizes of the topmost stream module; or the len field for the buffer specified through the databuf field is larger than the maximum configured size of the data part of a message; or the len field for the buffer specified through the ctlbuf field is larger than the maximum configured size of the control part of a message. |
The I_FDINSERT operation is also unsuccessful if an error message is received by the stream head corresponding to the fildes field in the strfdinsert structure. In this case, the errno global variable is set to the value in the message.