I_FDINSERT streamio Operation

AIX Version 4.3 Communications Technical Reference, Volume 2

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:

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.

Error Codes

If unsuccessful, the errno global variable is set to one of the following values:

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.

Implementation Specifics

This operation is part of STREAMS Kernel Extensions.

Related Information

The streamio operations.

Understanding STREAMS Messages in AIX Version 4.3 Communications Programming Concepts.