getmsg System Call

Purpose

Gets the next message off a stream.

Syntax

#include <stropts.h>

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

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:

• The control part of the message is not processed. Thus, it is left on the stream-head read queue.
• The len field is set to -1.

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

• The zero-length part is removed from the read queue.
• The len field is set to 0.

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

• The information is left on the read queue.
• The len field is set to 0.

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:

• The maxlen bytes are retrieved.
• The remainder of the message is left on the stream-head read queue.
• A nonzero return value is provided.

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:

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:

• The number of bytes of control information or data actually received
• 0 if there is a zero-length control or data part
• -1 if no control information or data is present in the message.

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:

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