System Calls getmsg(2)
NAME
getmsg, getpmsg - get next message off a stream
SYNOPSIS
#include
int getmsg(int fildes, struct strbuf *restrict ctlptr,
struct strbuf *restrict dataptr, int *restrict flagsp);
int getpmsg(int fildes, struct strbuf *restrict ctlptr,
struct strbuf *restrict dataptr, int *restrict bandp,
int *restrict flagsp);
DESCRIPTION
The getmsg() function retrieves the contents of a message
(see Intro(2)) located at the stream head read queue from
a STREAMS file, and places the contents into user specified
buffer(s). The message must contain 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 STREAMS
module that generated the message.
The getpmsg() function behaved like getmsg(), but provides
finer control over the priority of the messages received.
Except where noted, all information pertaining to getmsg()
also pertains to getpmsg().
The fildes argument specifies a file descriptor referencing
an open stream. The ctlptr and dataptr arguments each point
to a strbuf structure, which contains the following members:
int maxlen; /* maximum buffer length */
int len; /* length of data */
char *buf; /* ptr to buffer */
The buf member points to a buffer into 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; 0 if there is
a zero-length control or data part; or -1 if no data or con-
trol information is present in the message. The flagsp argu-
ment should point to an integer that indicates the type of
message the user is able to receive, as described below.
SunOS 5.11 Last change: 1 Nov 2001 1
System Calls getmsg(2)
The ctlptr argument holds the control part from the message
and the dataptr argument holds the data part from the mes-
sage. If ctlptr (or dataptr) is NUL or the maxlen member is
-1, the control (or data) part of the message is not pro-
cessed and is left on the stream head read queue. If ctlptr
(or dataptr) is not NUL and there is no corresponding con-
trol (or data) part of the messages on the stream head read
queue, 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 zero 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,
respectively, the control or data part of the message, max-
len 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, as described below under
RETURN VALUES.
By default, getmsg() processes the first available message
on the stream head read queue. A user may, however, choose
to retrieve only high priority messages by setting the
integer pointed to by flagsp to RSHIPRI. In this case,
getmsg() processes the next message only if it is a high
priority message.
If the integer pointed to by flagsp is 0, getmsg() retrieves
any message available on the stream head read queue. In this
case, on return, the integer pointed to by flagsp will be
set to RSHIPRI if a high priority message was retrieved,
or to 0 otherwise.
For getpmsg(), the flagsp argument points to a bitmask with
the following mutually-exclusive flags defined: MSGHIPRI,
MSGBAND, and MSGANY. Like getmsg(), getpmsg() processes
the first available message on the stream head read queue. A
user may choose to retrieve only high-priority messages by
setting the integer pointed to by flagsp to MSGHIPRI 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 user may
choose to retrieve a message from a particular priority band
by setting the integer pointed to by flagsp to MSGBAND 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 user just wants to get the first
SunOS 5.11 Last change: 1 Nov 2001 2
System Calls getmsg(2)
message off the queue, the integer pointed to by flagsp
should be set to MSGANY 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 MSGHIPRI and the integer pointed to by bandp
will be set to 0. Otherwise, the integer pointed to by
flagsp will be set to MSGBAND and the integer pointed to by
bandp will be set to the priority band of the message.
If ONDELAY and ONONBLOCK are clear, getmsg() blocks until
a message of the type specified by flagsp is available on
the stream head read queue. If ONDELAY or ONONBLOCK has
been set and a message of the specified type is not present
on the read queue, getmsg() fails and sets errno to EAGAIN.
If a hangup occurs on the stream from which messages are to
be retrieved, getmsg() continues to operate normally, as
described above, until the stream head read queue is empty.
Thereafter, it returns 0 in the len member of ctlptr and
dataptr.
RETURN VALUES
Upon successful completion, a non-negative value is
returned. A return 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 are wait-
ing for retrieval. A return value of MORECTL MOREDATA
indicates that both types of information remain. Subsequent
getmsg() calls retrieve the remainder of the message. How-
ever, if a message of higher priority has been received by
the stream head read queue, the next call to getmsg() will
retrieve that higher priority message before retrieving the
remainder of the previously received partial message.
ERORS
The getmsg() and getpmsg() functions will fail if:
EAGAIN The ONDELAY or ONONBLOCK flag is set and no
messages are available.
EBADF The fildes argument is not a valid file descrip-
tor open for reading.
EBADMSG Queued message to be read is not valid for
getmsg.
SunOS 5.11 Last change: 1 Nov 2001 3
System Calls getmsg(2)
EFAULT The ctlptr, dataptr, bandp, or flagsp argument
points to an illegal address.
EINTR A signal was caught during the execution of the
getmsg function.
EINVAL An illegal value was specified in flagsp, or the
stream referenced by fildes is linked under a
multiplexor.
ENOSTR A stream is not associated with fildes.
The getmsg() function can also fail if a STREAMS error mes-
sage had been received at the stream head before the call to
getmsg(). The error returned is the value contained in the
STREAMS error message.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
SEE ALSO
Intro(2), poll(2), putmsg(2), read(2), write(2), attri-
butes(5), standards(5)
STREAMS Programming Guide
SunOS 5.11 Last change: 1 Nov 2001 4
|
