STREAMS-UX Programmer's Guide (February 2007)

STREAMS IOCTL Commands
Overview
Appendix A
145
I_PEEK
Allows the user process to look (peek) at the contents of the first message on the stream head read queue.
This is done without taking the message off the queue. The I_PEEK IOCTL operates the same way as the
getmsg() function, except that it does not remove the message. The arg parameter points to a strpeek
structure (in the <stropts.h> header file) with the following members:
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
The strbuf structure pointed to by ctlbuf and databuf has the following members:
int maxlen;
int len;
char *buf
The maxlen field of the strbuf structure must specify the number of bytes of control or data information to be
retrieved. The flags field can be set to RS_HIPRI or 0 (zero). If this field is set to RS_HIPRI, the I_PEEK IOCTL
looks for a high priority message on the queue. If the field is set to 0, the I_PEEK IOCTL looks at the first
message on the queue.
The I_PEEK returns a 1 if a message was retrieved, and returns a value of 0 (zero) if no message was found; it
does not wait for a message. Upon successful completion, ctlbuf specifies control information in the control
buffer, databuf specifies data information in the data buffer, and flags contains RS_HIPRI or 0 (zero).
On failure, errno is set to one of the following values:
[EINVAL] The flags parameter is an illegal value.
[EFAULT] The arg points, or ctrlbuf or databuf is, outside the allocated address space.
[EBADMSG] Message to be looked at is not valid for the I_PEEK command.
I_PLINK
Connects two streams, where fildes is the file descriptor of the stream connected to the multiplexing driver,
and arg is the file descriptor of the stream connected to another driver. The stream designated by arg is
connected via a persistent link below the multiplexing river. The I_PLINK requires the multiplexing driver to
send an acknowledgement message to the stream head regarding the linking operation. This call creates a
persistent link which can exist even if the file descriptor associated with the upper stream to the multiplexing
driver is closed. This call returns a multiplexor ID number (an identifier that may be used to disconnect the
multiplexor, see I_PUNLINK) on success and -1 on failure.
On failure, errno is set to one of the following values:
[ENXIO] A hangup was received on the stream referred to by the fildes parameter.
[ETIME] A timeout occurred before an acknowledgement message was received at the stream head.
[EAGAIN] Temporarily unable to allocate storage to perform the linking operation.
[EBADF] The arg is not a valid open file descriptor.
[EINVAL] The stream referred to by fildes does not support multiplexing.
[EINVAL] The file referred to by arg is not a stream or is already linked under a multiplexing driver.
[EINVAL] The link operation would cause a “cycle” in the resulting multiplexing configuration. In
other words, the driver referred to by arg is linked into the configuration at multiple places.