STREAMS-UX Programmer's Guide (February 2007)

STREAMS Mechanism and System Calls
Reading From a Stream
Chapter 2
27
Return Values
Upon successful completion, read (2) and readv (2) return the actual number of bytes read from the stream it
placed in the requested buffer. This number may be less than the number of bytes requested (nbytes). In case
of failure, read (2) returns -1and sets errno, as with all standard UNIX File System I/O.
When attempting to read a stream (other than a STREAMS-based pipe) that supports non-blocking reads and
has no data currently available, read() will return the following:
•If O_NONBLOCK is set, read (2) returns -1 and set errno to EAGAIN.
•If O_NONBLOCK is clear, read (2) blocks until some data becomes available.
When attempting to read from an empty pipe, read (2) returns the following:
• If no process has the pipe open for writing, read (2) returns a 0.
• If a process has the pipe open for writing and O_NONBLOCK is set, read (2) returns -1 and errno is set to
[EAGAIN].
•If O_NDELAY is set, read (2) returns a 0.
• If some process has the pipe open for writing, and O_NDELAY and O_NONBLOCK are clear, read (2) blocks
until data is written to the file or the file is no longer open for writing.
The getmsg(2) and getpmsg(2) System Calls
The getmsg (2) and getpmsg (2) system calls read messages from a stream, and place the retrieved content
separately into user-specified control and data buffers.
Synopsis
#include <stropts.h>
int getmsg (int fd, struct strbuf *ctlptr, struct strbuf *dataptr, int *flagsp);
int getpmsg (int fd, struct strbuf *ctlptr, struct strbuf *dataptr, int *bandp, int *flagsp );
Arguments
fd STREAMS file descriptor.
ctlptr, dataptr Pointers to strbuf structures containing the retrieved control and data information
respectively.
flagsp Only messages of priority specified by flagsp are retrieved from the stream head.
bandp Only ordinary messages of band priority specified by bandp will be retrieved from the
stream head.
The user process invoking the getmsg (2) or getpmsg (2) system call uses the following strbuf structure
(defined in <sys/stropts.h>) to retrieve control and data information from the stream head:
struct strbuf
{
int maxlen; /* maximum buffer length */
int len; /* Length of message */
char *buf; /* Pointer to the buffer */
};
Reading Data and Control Messages
The getmsg (2) and getpmsg (2) will read control and data messages based on the following conditions: