getmsg.2 (2010 09)

g
getmsg(2) getmsg(2)
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 *band,
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 max-
imum 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 pro-
cess 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 members 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 informa-
tion 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 on-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 other-
wise.
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 message 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 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
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1