GETMSG(2)

NAME
getmsg - get next message from a stream

SYNOPSIS
#include <stropts.h>

int getmsg(fd, ctlptr, dataptr, flags)
int fd;
struct strbuf *ctlptr;
struct strbuf *dataptr;
int *flags;

DESCRIPTION

getmsg() retrieves the contents of a message (see intro(2)) located at the stream head read queue from a STREAMS file, and places the contents into user specified buffer(s). The message must contain either a data part, a control part or both. The data and control parts of the message are placed into separate buffers, as described below. The semantics of each part is defined by the STREAMS module that generated the message.

fd specifies a file descriptor referencing an open stream. ctlptr and dataptr each point to a strbuf structure that contains the following members:

    int maxlen;	/* maximum buffer length */
    int len;  	/* length of data */
    char *buf;	/* ptr to buffer */

where buf points to a buffer in which the data or control information is to be placed, and maxlen indicates the maximum number of bytes this buffer can hold. On return, len contains the number of bytes of data or control information actually received, or is 0 if there is a zero-length control or data part, or is -1 if no data or control information is present in the message. flags may be set to the values 0 or RS_HIPRI and is used as described below.

ctlptr is used to hold the control part from the message and dataptr is used to hold the data part from the message. If ctlptr (or dataptr) is a NULL pointer or the maxlen field is -1, the control (or data) part of the message is not processed and is left on the stream head read queue and len is set to -1. If the maxlen field is set to 0 and there is a zero-length control (or data) part, that zero-length part is removed from the read queue and len is set to 0. If the maxlen field is set to 0 and there are more than zero bytes of control (or data) information, that information is left on the read queue and len is set to 0. If the maxlen field in ctlptr or dataptr is less than, respectively, the control or data part of the message, maxlen bytes are retrieved. In this case, the remainder of the message is left on the stream head read queue and a non-zero return value is provided, as described below under RETURN VALUES. If information is retrieved from a priority message, flags is set to RS_HIPRI on return.

By default, getmsg() processes the first priority or non-priority message available on the stream head read queue. However, a process may choose to retrieve only priority messages by setting flags to RS_HIPRI. In this case, getmsg() will only process the next message if it is a priority message.

If O_NDELAY has not been set, getmsg() blocks until a message, of the type(s) specified by flags (priority or either), is available on the stream head read queue. If O_NDELAY has been set and a message of the specified type(s) is not present on the read queue, getmsg() fails and sets errno to EAGAIN.

If a hangup occurs on the stream from which messages are to be retrieved, getmsg() will continue to operate normally, as described above, until the stream head read queue is empty. Thereafter, it will return 0 in the len fields of ctlptr and dataptr.

RETURN VALUES

getmsg() returns a non-negative value on success:

    0   A full message was read successfully.

    MORECTL
        More control information is waiting for retrieval. Subsequent getmsg() calls will retrieve the rest of the message.

    MOREDATA
        More data are waiting for retrieval. Subsequent getmsg() calls will retrieve the rest of the message.

    MORECTL | MOREDATA
        Both types of information remain.

On failure, getmsg() returns -1 and sets errno to indicate the error.

ERRORS

EAGAIN
    The O_NDELAY flag is set, and no messages are available.

EBADF
    fd is not a valid file descriptor open for reading.

EBADMSG
    The queued message to be read is not valid for getmsg().

EFAULT
    ctlptr, dataptr, or flags points to a location outside the allocated address space.

EINTR
    A signal was caught during the getmsg() system call.

EINVAL
    An illegal value was specified in flags.

    The stream referenced by fd is linked under a multiplexor.

ENOSTR
    A stream is not associated with fd.

A getmsg() can also fail if a STREAMS error message had been received at the stream head before the call to getmsg(). The error returned is the value contained in the STREAMS error message.

SEE ALSO
intro(2), poll(2), putmsg(2), read(2V), write(2V)