getmsg System Call

Purpose

Gets the next message off a stream.

Syntax

#include <stropts.h>

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

Description

The getmsg system call retrieves from a STREAMS file the contents of a message located at the stream-head read queue, and places the contents into user-specified buffers. 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 in the "Parameters" section. The semantics of each part are defined by the STREAMS module that generated the message.

This system call is part of the STREAMS Kernel Extensions.

Parameters

Item Description
fd Specifies a file descriptor referencing an open stream.
ctlptr Holds the control part of the message.
dataptr Holds the data part of the message.
flags Indicates the type of message to be retrieved. Acceptable values are:
0
Process the next message of any type.
RS_HIPRI
Process the next message only if it is a priority message.

The ctlptr and dataptr parameters 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  */

In the strbuf structure, the maxlen field indicates the maximum number of bytes this buffer can hold, the len field contains the number of bytes of data or control information received, and the buf field points to a buffer in which the data or control information is to be placed.

If the ctlptr (or dataptr) parameter is null or the maxlen field is -1, the following events occur:

If the maxlen field is set to 0 and there is a zero-length control (or data) part, the following events occur:

If the maxlen field is set to 0 and there are more than 0 bytes of control (or data) information, the following events occur:

If the maxlen field in the ctlptr or dataptr parameter is less than, respectively, the control or data part of the message, the following events occur:

By default, the getmsg system call processes the first priority or nonpriority message available on the stream-head read queue. However, a user may choose to retrieve only priority messages by setting the flags parameter to RS_HIPRI. In this case, the getmsg system call processes the next message only if it is a priority message. When the integer pointed to by flagsp is 0, any message will be retrieved. In this case, on return, the integer pointed to by flagsp will be set to RS_HIPRI if a high-priority message was retrieved, or 0 otherwise.

If the O_NDELAY or O_NONBLOCK flag has not been set, the getmsg system call blocks until a message of the types specified by the flags parameter (priority only or either type) is available on the stream-head read queue. If the O_DELAY or O_NONBLOCK flag has been set and a message of the specified types is not present on the read queue, the getmsg system call fails and sets the errno global variable to EAGAIN.

If a hangup occurs on the stream from which messages are to be retrieved, the getmsg system call continues to operate until the stream-head read queue is empty. Thereafter, it returns 0 in the len fields of both the ctlptr and dataptr parameters.

Return Values

Upon successful completion, the getmsg system call returns a nonnegative value. The possible values are:

Value Description
0 Indicates that a full message was read successfully.
MORECTL Indicates that more control information is waiting for retrieval.
MOREDATA Indicates that more data is waiting for retrieval.
MORECTL|.MOREDATA Indicates that both types of information remain. Subsequent getmsg calls retrieve the remainder of the message.

If the high priority control part of the message is consumed, the message will be placed back on the queue as a normal message of band 0. Subsequent getmsg system calls retrieve the remainder of the message. If, however, a priority message arrives or already exists on the STREAM head, the subsequent call to getmsg retrieves the higher-priority message before retrieving the remainder of the message that was put back.

On return, the len field contains one of the following:

If information is retrieved from a priority message, the flags parameter is set to RS_HIPRI on return.

Upon failure, getmsg returns -1 and sets errno to indicate the error.

Error Codes

The getmsg system call fails if one or more of the following is true:

Error Description
EAGAIN The O_NDELAY flag is set, and no messages are available.
EBADF The fd parameter is not a valid file descriptor open for reading.
EBADMSG Queued message to be read is not valid for the getmsg system call.
EFAULT The ctlptr, dataptr, or flags parameter 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 the flags parameter or else the stream referenced by the fd parameter is linked under a multiplexer.
ENOSTR A stream is not associated with the fd parameter.

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

Files

Item Description
/lib/pse.exp Contains the STREAMS export symbols.