NAME

getmsg, getpmsg - receive next message from a STREAMS file

 SYNOPSIS

#include <stropts.h>

int getmsg(int fildes, struct strbuf *ctlptr, struct strbuf *dataptr,
    int *flagsp);
int getpmsg(int fildes, struct strbuf *ctlptr, struct strbuf *dataptr,
    int *bandp, int *flagsp);

 DESCRIPTION

The getmsg() function retrieves the contents of a message located at the head of the STREAM head read queue associated with a STREAMS file and places the contents into one or more buffers. The message contains 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 originator of the message.

The getpmsg() function does the same thing as getmsg(), but provides finer control over the priority of the messages received. Except where noted, all requirements on getmsg() also pertain to getpmsg().

The fildes argument specifies a file descriptor referencing a STREAMS-based file.

The ctlptr and dataptr arguments each point to a strbuf structure, in which the buf member points to a buffer in which the data or control information is to be placed, and the maxlen member indicates the maximum number of bytes this buffer can hold. On return, the len member contains the number of bytes of data or control information actually received. The len member is set to 0 if there is a zero-length control or data part and len is set to -1 if no data or control information is present in the message.

When getmsg() is called, flagsp should point to an integer that indicates the type of message the process is able to receive. This is described further below.

The ctlptr argument is used to hold the control part of the message, and dataptr is used to hold the data part of the message. If ctlptr (or dataptr) is a null pointer or the maxlen member is -1, the control (or data) part of the message is not processed and is left on the STREAM head read queue, and if the ctlptr (or dataptr) is not a null pointer, len is set to -1. If the maxlen member 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 member is set to 0 and there are more than 0 bytes of control (or data) information, that information is left on the read queue and len is set to 0. If the maxlen member in ctlptr (or dataptr) is less than 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.

By default, getmsg() processes the first available message on the STREAM head read queue. However, a process may choose to retrieve only high-priority messages by setting the integer pointed to by flagsp to RS_HIPRI. In this case, getmsg() will only process the next message if it is a high-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.

For getpmsg(), the flags are different. The flagsp argument points to a bitmask with the following mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND and MSG_ANY. Like getmsg(), getpmsg() processes the first available message on the STREAM head read queue. A process may choose to retrieve only high-priority messages by setting the integer pointed to by flagsp to MSG_HIPRI and the integer pointed to by bandp to 0. In this case, getpmsg() will only process the next message if it is a high-priority message. In a similar manner, a process may choose to retrieve a message from a particular priority band by setting the integer pointed to by flagsp to MSG_BAND and the integer pointed to by bandp to the priority band of interest. In this case, getpmsg() will only process the next message if it is in a priority band equal to, or greater than, the integer pointed to by bandp, or if it is a high-priority message. If a process just wants to get the first message off the queue, the integer pointed to by flagsp should be set to MSG_ANY and the integer pointed to by bandp should be set to 0. On return, if the message retrieved was a high-priority message, the integer pointed to by flagsp will be set to MSG_HIPRI and the integer pointed to by bandp will be set to 0. Otherwise, the integer pointed to by flagsp will be set to MSG_BAND and the integer pointed to by bandp will be set to the priority band of the message.

If O_NONBLOCK is not set, getmsg() and getpmsg() will block until a message of the type specified by flagsp is available at the front of the STREAM head read queue. If O_NONBLOCK is set and a message of the specified type is not present at the front of the read queue, getmsg() and getpmsg() fail and set errno to [EAGAIN].

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

 RETURN VALUE

Upon successful completion, getmsg() and getpmsg() return a non-negative value. A value of 0 indicates that a full message was read successfully. A return value of MORECTL indicates that more control information is waiting for retrieval. A return value of MOREDATA indicates that more data is waiting for retrieval. A return value of the bitwise logical OR of MORECTL and MOREDATA indicates that both types of information remain. Subsequent getmsg() and getpmsg() calls retrieve the remainder of the message. However, if a message of higher priority has come in on the STREAM head read queue, the next call to getmsg() or getpmsg() retrieves that higher-priority message before retrieving the remainder of the previous 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() and getpmsg() 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() or getpmsg() retrieves the higher-priority message before retrieving the remainder of the message that was put back.

Upon failure, getmsg() and getpmsg() return -1 and set errno to indicate the error.

 ERRORS

The getmsg() and getpmsg() functions will fail if:

[EAGAIN]

The O_NONBLOCK flag is set and no messages are available.

[EBADF]

The fildes argument is not a valid file descriptor open for reading.

[EBADMSG]

The queued message to be read is not valid for getmsg() or getpmsg() or a pending file descriptor is at the STREAM head.

[EINTR]

A signal was caught during getmsg() or getpmsg().

[EINVAL]

An illegal value was specified by flagsp, or the STREAM or multiplexer referenced by fildes is linked (directly or indirectly) downstream from a multiplexer.

[ENOSTR]

A STREAM is not associated with fildes.

In addition, getmsg() and getpmsg() will fail if the STREAM head had processed an asynchronous error before the call. In this case, the value of errno does not reflect the result of getmsg() or getpmsg() but reflects the prior error.

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

poll(), putmsg(), read(), write(), <stropts.h>, STREAMS overview.