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.

Note: To use the getmsg system call you must import the /lib/pse.exp file during the compile. For example, compile the system call by entering the following command:

cc -bI:/lib/pse.exp 

Failure to import this file means that the getmsg system call will be unresolved during the link edit phase.

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.

If the O_NDELAY 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 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:

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.

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.

Implementation Specifics

This system call is part of the STREAMS Kernel Extensions.

Files

Related Information

The poll subroutine, read subroutine, write subroutine.

The getpmsg system call, putmsg system call, putpmsg system call.

List of Streams Programming References and STREAMS Overview in AIX Version 4.3 Communications Programming Concepts.