I_PEEK streamio Operation

This operation is part of STREAMS Kernel Extensions.

Purpose

Allows a user to retrieve the information in the first message on the stream-head read queue without taking the message off the queue.

Description

The I_PEEK operation allows a user to retrieve the information in the first message on the stream-head read queue without taking the message off the queue. The arg parameter points to a strpeek structure that contains the following elements:

struct strbuf ctlbuff;
struct strbuf databuf;
long flags;

The maxlen field in the strbuf structures of the ctlbuf and databuf fields must be set to the number of bytes of control information or data information, respectively, to retrieve. If the user sets the flags field to RS_HIPRI, the I_PEEK operation looks for a priority message only on the stream-head read queue.

The I_PEEK operation returns a value of 1 if a message was retrieved, and returns a value of 0 if no message was found on the stream-head read queue, or if the RS_HIPRI flag was set in the flags field and a priority message was not present on the stream-head read queue. It does not wait for a message to arrive.

On return, the fields contain the following data:

Data Description
ctlbuf Specifies information in the control buffer.
databuf Specifies information in the data buffer.
flags Contains the value of 0 or RS_HIPRI.

Error Codes

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

Value Description
EFAULT The arg parameter points, or the buffer area specified in the ctlbuf or databuf field is outside the allocated address space.
EBADMSG Queued message is not valid for the I_PEEK operation.