svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
getmsg(2)
getmsg(2) System Calls getmsg(2)
NAME
getmsg, getpmsg - get next message off a stream
SYNOPSIS
#include <stropts.h>
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 In‐
tro(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 con‐
trol parts of the message are placed into separate buffers, as de‐
scribed below. The semantics of each part is defined by the STREAMS
module that generated the message.
The getpmsg() function behaves like getmsg(), but provides finer con‐
trol 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 struc‐
ture, which contain 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 infor‐
mation is to be placed, and the maxlen member indicates the maximum
number of bytes this buffer can hold. On return, the len member con‐
tains the number of bytes of data or control information actually re‐
ceived; 0 if there is a zero-length control or data part, or −1 if no
data or control 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.
The ctlptr argument holds the control part from the message and the
dataptr argument holds the data part from the message. If ctlptr (or
dataptr) is NULL or the maxlen member is −1, the control (or data) part
of the message is not processed and is left on the stream head read
queue. If ctlptr (or dataptr) is not NULL and there is no corresponding
control (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 con‐
trol 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 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
RS_HIPRI. 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 mes‐
sage available on the stream head read queue. In this case, on return,
the integer pointed to by flagsp will be set to RS_HIPRI if a high pri‐
ority message was retrieved, or to 0 otherwise.
For getpmsg(), the flagsp argument points to a bitmask with the follow‐
ing 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 user may choose to retrieve only high-prior‐
ity messages 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 it is a high-priority message. In a
similar manner, a user may choose to retrieve a message from a particu‐
lar priority band by setting the integer pointed to by flagsp to
MSG_BAND 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 message off the queue, the integer pointed to by
flagsp should be set to MSG_ANY and the integer pointed to by bandp
should be set to 0. On return, if the message retrieved was a high-pri‐
ority message, the integer pointed to by flagsp will be set to
MSG_HIPRI and the integer pointed to by bandp will be set to 0. Other‐
wise, the integer pointed to by flagsp will be set to MSG_BAND and the
integer pointed to by bandp will be set to the priority band of the
message.
If O_NDELAY and O_NONBLOCK are clear, getmsg() blocks until a message
of the type specified by flagsp is available on the stream head read
queue. If O_NDELAY or O_NONBLOCK 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 re‐
trieved, 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 re‐
turn value of MORECTL indicates that more control information is wait‐
ing for retrieval. A return value of MOREDATA indicates that more data
are waiting for retrieval. A return value of MORECTL | MOREDATA indi‐
cates that both types of information remain. Subsequent getmsg() calls
retrieve the remainder of the message. However, 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 retriev‐
ing the remainder of the previously received partial message.
ERRORS
The getmsg() and getpmsg() functions will fail if:
EADI The user-specified buffer for the data part of a message is
enabled for ADI, and an ADI version mismatch is detected
while the system writes data to the buffer. For more infor‐
mation, see the adi(3C) man page.
EAGAIN The O_NDELAY or O_NONBLOCK flag is set and no messages are
available.
EBADF The fildes argument is not a valid file descriptor open for
reading.
EBADMSG Queued message to be read is not valid for getmsg.
EFAULT The ctlptr, dataptr, bandp, or flagsp argument points to an
illegal address.
EINTR A signal was caught during the execution of the getmsg func‐
tion.
EINVAL An illegal value was specified in flagsp, or the stream ref‐
erenced 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 message has been
received at the stream head before the call to getmsg(). The error re‐
turned is the value contained in the STREAMS error message.
ATTRIBUTES
See attributes(7) for description of the following attribute:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ StandardSee stan‐
dards(7).
SEE ALSO
Intro(2), poll(2), putmsg(2), read(2), write(2), attributes(7), stan‐
dards(7)
STREAMS Programming Guide
HISTORY
The getmsg() function has been included in all Sun and Oracle releases
of Solaris.
The getpmsg() function has been included in Solaris since the Solaris
2.0 release.
Oracle Solaris 11.4 30 Jan 2023 getmsg(2)