getmsg.2 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

getmsg(2) getmsg(2)

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,orifitisahigh-priority

message. If a process just wants to get the ﬁrst message off the queue, 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 ﬂagsp will be set to

MSG_HIPRI

and the integer pointed to by bandp will be set to 0. Otherwise, the

integer pointed to by ﬂagsp will be set to

MSG_BAND and the integer pointed to by bandp will be set to

the priority band of the message.

O_NONBLOCK is not set, getmsg() and

getpmsg() will block until a message of the type speciﬁed

by ﬂagsp is available at the front of the stream head read queue. If O_NONBLOCK is set and a message of

the speciﬁed 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 indi-

cates 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 mes-

sage. 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 previously-received partial message.

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 ﬂag is set and no messages are available.

[EBADF] The ﬁldes argument is not a valid ﬁle descriptor open for reading.

[EBADMSG] The queued message to be read is not valid for

getmsg() or getpmsg() or a

pending ﬁle descriptor is at the stream head.

[EINTR] A signal was caught during

getmsg() or getpmsg().

[EINVAL] An illegal value was speciﬁed by ﬂagsp , or the stream or multiplexor referenced by

ﬁldes is linked (directly or indirectly) downstream from a multiplexor.

[ENOSTR] A stream is not associated with ﬁldes .