HPUX getmsg[2]
getmsg in anderen Kapiteln des hpux Handbuch:
getmsg.3c
getmsg(2) 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.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: October 1992
getmsg(2) getmsg(2)
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.
o 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).
o 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).
o 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.
o 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.
o If ctlbuf or databuf is not a null pointer and if the read
queue at the stream head has no corresponding message control
Hewlett-Packard Company - 2 - HP-UX Release 9.0: October 1992
getmsg(2) getmsg(2)
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:
o By default, getmsg() processes the first message available on
the stream head queue.
o 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.
o 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:
o By default, getpmsg() processes the first available message on
the stream head read queue.
o 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.
o 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.
o 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).
Hewlett-Packard Company - 3 - HP-UX Release 9.0: October 1992
getmsg(2) getmsg(2)
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.
Hewlett-Packard Company - 4 - HP-UX Release 9.0: October 1992
getmsg(2) getmsg(2)
[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.
SEE ALSO
poll(2), putmsg(2), read(2), write(2), streamio(7).
Hewlett-Packard Company - 5 - HP-UX Release 9.0: October 1992