'\" et

.TH GETMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"

.SH PROLOG

This manual page is part of the POSIX Programmer's Manual.

The Linux implementation of this interface may differ (consult

the corresponding Linux manual page for details of Linux behavior),

or the interface may not be implemented on Linux.

.SH NAME

getmsg,

getpmsg

\(em receive next message from a STREAMS file (\fBSTREAMS\fP)

.SH SYNOPSIS

.LP

.nf

#include <stropts.h>

.P

int getmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP,

    struct strbuf *restrict \fIdataptr\fP, int *restrict \fIflagsp\fP);

int getpmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP,

    struct strbuf *restrict \fIdataptr\fP, int *restrict \fIbandp\fP,

    int *restrict \fIflagsp\fP);

.fi

.SH DESCRIPTION

The

\fIgetmsg\fR()

function shall retrieve the contents of a message located at the head

of the STREAM head read queue associated with a STREAMS file and place

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 shall be placed into separate buffers, as described below. The

semantics of each part are defined by the originator of the message.

.P

The

\fIgetpmsg\fR()

function shall be equivalent to

\fIgetmsg\fR(),

except that it provides finer control over the priority of the messages

received. Except where noted, all requirements on

\fIgetmsg\fR()

also pertain to

\fIgetpmsg\fR().

.P

The

.IR fildes

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

.P

The

.IR ctlptr

and

.IR dataptr

arguments each point to a

.BR strbuf

structure, in which the

.IR buf

member points to a buffer in which the data or control information is

to be placed, and the

.IR maxlen

member indicates the maximum number of bytes this buffer can hold. On

return, the

.IR len

member shall contain the number of bytes of data or control information

actually received. The

.IR len

member shall be set to 0 if there is a zero-length control or data part

and

.IR len

shall be set to \(mi1 if no data or control information is present in

the message.

.P

When

\fIgetmsg\fR()

is called,

.IR flagsp

should point to an integer that indicates the type of message the

process is able to receive. This is described further below.

.P

The

.IR ctlptr

argument is used to hold the control part of the message, and

.IR dataptr

is used to hold the data part of the message. If

.IR ctlptr

(or

.IR dataptr )

is a null pointer or the

.IR maxlen

member is \(mi1, the control (or data) part of the message shall not be

processed and shall be left on the STREAM head read queue, and if the

.IR ctlptr

(or

.IR dataptr )

is not a null pointer,

.IR len

shall be set to \(mi1. If the

.IR maxlen

member is set to 0 and there is a zero-length control (or data) part,

that zero-length part shall be removed from the read queue and

.IR len

shall be set to 0. If the

.IR maxlen

member is set to 0 and there are more than 0 bytes of control (or data)

information, that information shall be left on the read queue and

.IR len

shall be set to 0. If the

.IR maxlen

member in

.IR ctlptr

(or

.IR dataptr )

is less than the control (or data) part of the message,

.IR maxlen

bytes shall be retrieved. In this case, the remainder of the message

shall be left on the STREAM head read queue and a non-zero return value

shall be provided.

.P

By default,

\fIgetmsg\fR()

shall process 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

.IR flagsp

to RS_HIPRI. In this case,

\fIgetmsg\fR()

shall only process the next message if it is a high-priority message.

When the integer pointed to by

.IR flagsp

is 0, any available message shall be retrieved. In this case, on

return, the integer pointed to by

.IR flagsp

shall be set to RS_HIPRI if a high-priority message was retrieved, or 0

otherwise.

.P

For

\fIgetpmsg\fR(),

the flags are different. The

.IR flagsp

argument points to a bitmask with the following mutually-exclusive

flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY.

Like

\fIgetmsg\fR(),

\fIgetpmsg\fR()

shall process 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

.IR flagsp

to MSG_HIPRI and the integer pointed to by

.IR bandp

to 0. In this case,

\fIgetpmsg\fR()

shall 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

.IR flagsp

to MSG_BAND and the integer pointed to by

.IR bandp

to the priority band of interest. In this case,

\fIgetpmsg\fR()

shall only process the next message if it is in a priority band equal

to, or greater than, the integer pointed to by

.IR bandp ,

or if it is a high-priority message. If a process wants to get the

first message off the queue, the integer pointed to by

.IR flagsp

should be set to MSG_ANY and the integer pointed to by

.IR bandp

should be set to 0. On return, if the message retrieved was a

high-priority message, the integer pointed to by

.IR flagsp

shall be set to MSG_HIPRI and the integer pointed to by

.IR bandp

shall be set to 0. Otherwise, the integer pointed to by

.IR flagsp

shall be set to MSG_BAND and the integer pointed to by

.IR bandp

shall be set to the priority band of the message.

.P

If O_NONBLOCK is not set,

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

shall block until a message of the type specified by

.IR 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,

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

shall fail and set

.IR errno

to

.BR [EAGAIN] .

.P

If a hangup occurs on the STREAM from which messages are retrieved,

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

shall continue to operate normally, as described above, until the

STREAM head read queue is empty. Thereafter, they shall return 0 in the

.IR len

members of

.IR ctlptr

and

.IR dataptr .

.SH "RETURN VALUE"

Upon successful completion,

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

shall 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

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

calls shall 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

\fIgetmsg\fR()

or

\fIgetpmsg\fR()

shall retrieve that higher-priority message before retrieving the

remainder of the previous message.

.P

If the high priority control part of the message is consumed, the

message shall be placed back on the queue as a normal message of band

0. Subsequent

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

calls shall retrieve the remainder of the message. If, however, a

priority message arrives or already exists on the STREAM head, the

subsequent call to

\fIgetmsg\fR()

or

\fIgetpmsg\fR()

shall retrieve the higher-priority message before retrieving the

remainder of the message that was put back.

.P

Upon failure,

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

shall return \(mi1 and set

.IR errno

to indicate the error.

.SH ERRORS

The

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

functions shall fail if:

.TP

.BR EAGAIN

The O_NONBLOCK flag is set and no messages are available.

.TP

.BR EBADF

The

.IR fildes

argument is not a valid file descriptor open for reading.

.TP

.BR EBADMSG

The queued message to be read is not valid for

\fIgetmsg\fR()

or

\fIgetpmsg\fR()

or a pending file descriptor is at the STREAM head.

.TP

.BR EINTR

A signal was caught during

\fIgetmsg\fR()

or

\fIgetpmsg\fR().

.TP

.BR EINVAL

An illegal value was specified by

.IR flagsp ,

or the STREAM or multiplexer referenced by

.IR fildes

is linked (directly or indirectly) downstream from a multiplexer.

.TP

.BR ENOSTR

A STREAM is not associated with

.IR fildes .

.P

In addition,

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

shall fail if the STREAM head had processed an asynchronous error

before the call. In this case, the value of

.IR errno

does not reflect the result of

\fIgetmsg\fR()

or

\fIgetpmsg\fR()

but reflects the prior error.

.LP

.IR "The following sections are informative."

.SH EXAMPLES

.SS "Getting Any Message"

.P

In the following example, the value of

.IR fd

is assumed to refer to an open STREAMS file. The call to

\fIgetmsg\fR()

retrieves any available message on the associated STREAM-head read

queue, returning control and data information to the buffers pointed to

by

.IR ctrlbuf

and

.IR databuf ,

respectively.

.sp

.RS 4

.nf

\fB

#include <stropts.h>

\&...

int fd;

char ctrlbuf[128];

char databuf[512];

struct strbuf ctrl;

struct strbuf data;

int flags = 0;

int ret;

.P

ctrl.buf = ctrlbuf;

ctrl.maxlen = sizeof(ctrlbuf);

.P

data.buf = databuf;

data.maxlen = sizeof(databuf);

.P

ret = getmsg (fd, &ctrl, &data, &flags);

.fi \fR

.P

.RE

.SS "Getting the First Message off the Queue"

.P

In the following example, the call to

\fIgetpmsg\fR()

retrieves the first available message on the associated STREAM-head

read queue.

.sp

.RS 4

.nf

\fB

#include <stropts.h>

\&...

.P

int fd;

char ctrlbuf[128];

char databuf[512];

struct strbuf ctrl;

struct strbuf data;

int band = 0;

int flags = MSG_ANY;

int ret;

.P

ctrl.buf = ctrlbuf;

ctrl.maxlen = sizeof(ctrlbuf);

.P

data.buf = databuf;

data.maxlen = sizeof(databuf);

.P

ret = getpmsg (fd, &ctrl, &data, &band, &flags);

.fi \fR

.P

.RE

.SH "APPLICATION USAGE"

None.

.SH RATIONALE

None.

.SH "FUTURE DIRECTIONS"

The

\fIgetmsg\fR()

and

\fIgetpmsg\fR()

functions may be removed in a future version.

.SH "SEE ALSO"

.IR "Section 2.6" ", " "STREAMS",

.IR "\fIpoll\fR\^(\|)",

.IR "\fIputmsg\fR\^(\|)",

.IR "\fIread\fR\^(\|)",

.IR "\fIwrite\fR\^(\|)"

.P

The Base Definitions volume of POSIX.1\(hy2008,

.IR "\fB<stropts.h>\fP"

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 7, Copyright (C) 2013 by the Institute of

Electrical and Electronics Engineers, Inc and The Open Group.

(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the

event of any discrepancy between this version and the original IEEE and

The Open Group Standard, the original IEEE and The Open Group Standard

is the referee document. The original Standard can be obtained online at

http://www.unix.org/online.html .

Any typographical or formatting errors that appear

in this page are most likely

to have been introduced during the conversion of the source files to

man page format. To report such errors, see

https://www.kernel.org/doc/man-pages/reporting_bugs.html .