getmsg(2)

NAME

getmsg, getpmsg - receive next message from a stream

SYNOPSIS

#include <stropts.h>

int getmsg(fd, ctlbuf, databuf, options);
int fd;
struct strbuf *ctlbuf;
struct strbuf *databuf;
long *options;
int getpmsg(fd, ctlbuf, databuf, band, options);
int fd;
struct strbuf *ctlbuf;
struct strbuf *databuf;
int *band;
long *options;

DESCRIPTION

getmsg() and getpmsg() retrieve the contents of messages. These messages are located at the stream head read queue associated with a STREAMS file. Messages must contain a control part and/or a data part. The control and data parts of the message are placed into separate user-specified buffers, pointed at by ctlbuf and databuf respectively. The open stream specifies the format and semantics of the message’s control and data parts. getpmsg() provides better control over the priority of messages received. Except where specified, all information about getmsg() also applies to the getpmsg().

Parameters

The following parameters are used as indicated:

fd Specifies a file descriptor that references an open stream.

ctlbuf Points to a strbuf structure that holds the control part of the message. The strbuf structure is described below.

databuf Points to a strbuf structure that holds the data part of the message. The strbuf structure is described below.

band Points to an integer that indicates the priority band of the message that the user is able to retrieve.

options Points to an integer that indicates the type of message the user is able to retrieve.

The ctlbuf and databuf parameters each point to a strbuf structure which contains three members. This structure is defined in <stropts.h> as:

struct strbuf {
    int maxlen;     /* maximum buffer length */
    int len;        /* length of data */
    char *buf       /* ptr to buffer */
};

The members are:

maxlen Specifies the maximum number of bytes buf can hold.

buf Points to the buffer where the control or data information is to reside.

len On return, contains the number of bytes of control or data information that has actually been received. The len parameter is set to 0 (zero) if there is a zero-length data or control part; otherwise, len is set to −1 if no control or data information is contained in the message.

The members of this structure are also affected by the following.

• If the maxlen field is set to 0 (zero) and the control or data part is of zero-length, that zero-length part is deleted from the read queue of the stream head, and len is set to 0 (zero).

• If the maxlen field is set to 0 (zero) and if the size of the control or data part is greater than 0 (zero), that part remains on the read queue and len is set to 0 (zero).

• If the maxlen field for either the ctlbuf or databuf structure is less than the size of the control or data part of the message, maxlen bytes are retrieved and the rest of the message remains on the stream head read queue. A non-zero value is then returned.

• If the maxlen member is −1, or if ctlbuf or databuf is a null pointer, getmsg() does not process the control or the data part of the message. The unprocessesd part or parts remain on the stream head queue.

• If ctlbuf or databuf is not a null pointer and if the read queue at the stream head has no corresponding message control or data part, len is set to −1.

One of the major differences between getmsg() and getpmsg(), in addition to the band parameter, is how the options parameter is used to collect messages. getmsg() processes messages as follows:

• By default, getmsg() processes the first message available on the stream head queue.

• If the options parameter is set to 0 (zero) any available message is retrieved. On return, the integer pointed to by the options parameter is set to RS_HIPRI if a high-priority message was retrieved; otherwise, a value of 0 (zero) is returned.

• If the options parameter is set to RS_HIPRI, getmsg() retrieves only high-priority messages. getmsg() then only processes the next message if it is a high-priority message.

The getpmsg() options parameter points to a bit mask with the mutually-exclusive options MSG_HIPRI, MSG_BAND, and MSG_ANY defined. The getpmsg() function processes messages as follows:

• By default, getpmsg() processes the first available message on the stream head read queue.

• If the integer pointed at by the options parameter is set to MSG_HIPRI, and the integer pointed to by the band parameter is set to 0 (zero), getpmsg() retrieves the next message only if it is a high-priority message.

• If the integer pointed to by the options parameter is set to MSG_BAND, and the integer pointed to by the band parameter is set to the desired priority band, getpmsg() retrieves the next message if it is a high-priority message, or if its priority band is greater than or equal to the integer pointed to by band.

• If the integer pointed to by the options parameter is set to MSG_ANY, and the integer pointed to by the band parameter is set to 0 (zero), getpmsg() retrieves only the first message off the queue. When getpmsg() returns, it then sets the options and band parameters according to the type of message that was retrieved. If the message was not a high-priority one, the integer pointed to by the options parameter is set to MSG_BAND and the integer pointed to by band is set to the band of the message. If the message was a high-priority one, the integer pointed to by the options is set to MSG_HIPRI and the integer pointed to by band is set to 0 (zero).

If the O_NDELAY or O_NONBLOCK options are set and a message of the specified type is not present at the front of the read queue, the getmsg() function fails. If the O_NDELAY or O_NONBLOCK options are not set for the read() operation, the getmsg() function blocks until a message is available at the front of the stream head read queue. This message’s type is specified by options.

If the stream from which the messages are being retrieved experiences a hangup, getmsg() does not fail. Instead, it continues as usual until the read queue of the stream head is empty. Subsequent calls return a value of 0 (zero) in the len fields for the ctlbuf and databuf structures.

RETURN VALUE

Upon successful completion, getmsg() and getmsg() returns a positive bitmask value containing any combination of the following:

0 Zero indicates that a full message was successfully read.

MORECTL Indicates that more control information is waiting for retrieval.

MOREDATA Indicates that more data is waiting for retrieval.

If MORECTL or MOREDATA is set, then subsequent calls to getmsg() retrieve the rest of the message. Note, however, that higher-priority messages, although they may arrive later on the queue, take a higher precedence. In other words, if a message comes in later on the read queue, the next call to the getmsg() function retrieves that higher-priority message first. The rest of the earlier partial message is retrieved afterwards.

ERRORS

Upon failure, the getmsg() function returns a value of −1, and sets errno to indicate an error.

getmsg() and getpmsg() both fail if a STREAMS error message is delivered to the stream head read queue before the call. In this instance, the STREAMS error message contains the value of the returned error.

In addition, if any of the following conditions occurs, getmsg() sets errno to the corresponding value:

[EAGAIN] The O_NDELAY or O_NONBLOCK option is set, and no messages are currently available.

[EBADF] The fd parameter is not a valid file descriptor open for reading.

[EBADMSG] The message on the read queue is not a control or data message.

[EFAULT] An illegal address has been specified in ctlbuf or databuf.

[EINTR] The getmsg() or getpmsg() function was interrupted by a signal that was caught.

[EINVAL] An illegal value was specified by the options parameter, or the stream referenced by fd is linked under a multiplexor.

[ENOSTR] A stream is not associated with the fd parameter.

NOTES

For portability purposes, it is recommended that O_NONBLOCK be used instead of O_NDELAY.

Museum

Related Articles