I_FDINSERT streamio Operation

Purpose

Creates a message from user-specified buffers, adds information about another stream and sends the message downstream.

Description

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.

Error Codes

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.