1getmsg(2) System Calls getmsg(2)
2
6 getmsg, getpmsg - get next message off a stream
7
9 #include <stropts.h>
10 int getmsg(int fildes, struct strbuf *restrict ctlptr,
12 struct strbuf *restrict dataptr, int *restrict flagsp);
13 int getpmsg(int fildes, struct strbuf *restrict ctlptr,
16 struct strbuf *restrict dataptr, int *restrict bandp,
17 int *restrict flagsp);
18
21 The getmsg() function retrieves the contents of a message (see
22 Intro(2)) located at the stream head read queue from a STREAMS file,
23 and places the contents into user specified buffer(s). The message must
24 contain either a data part, a control part, or both. The data and con‐
25 trol parts of the message are placed into separate buffers, as
26 described below. The semantics of each part is defined by the STREAMS
27 module that generated the message.
28 The getpmsg() function behaved like getmsg(), but provides finer con‐
31 trol over the priority of the messages received. Except where noted,
32 all information pertaining to getmsg() also pertains to getpmsg().
33 The fildes argument specifies a file descriptor referencing an open
36 stream. The ctlptr and dataptr arguments each point to a strbuf struc‐
37 ture, which contains the following members:
38 int maxlen; /* maximum buffer length */
40 int len; /* length of data */
41 char *buf; /* ptr to buffer */
42 The buf member points to a buffer into which the data or control infor‐
46 mation is to be placed, and the maxlen member indicates the maximum
47 number of bytes this buffer can hold. On return, the len member con‐
48 tains the number of bytes of data or control information actually
49 received; 0 if there is a zero-length control or data part; or −1 if no
50 data or control information is present in the message. The flagsp argu‐
51 ment should point to an integer that indicates the type of message the
52 user is able to receive, as described below.
53 The ctlptr argument holds the control part from the message and the
56 dataptr argument holds the data part from the message. If ctlptr (or
57 dataptr) is NULL or the maxlen member is −1, the control (or data)
58 part of the message is not processed and is left on the stream head
59 read queue. If ctlptr (or dataptr) is not NULL and there is no corre‐
60 sponding control (or data) part of the messages on the stream head read
61 queue, len is set to −1. If the maxlen member is set to 0 and there is
62 a zero-length control (or data) part, that zero-length part is removed
63 from the read queue and len is set to 0. If the maxlen member is set to
64 0 and there are more than zero bytes of control (or data) information,
65 that information is left on the read queue and len is set to 0. If the
66 maxlen member in ctlptr or dataptr is less than, respectively, the
67 control or data part of the message, maxlen bytes are retrieved. In
68 this case, the remainder of the message is left on the stream head read
69 queue and a non-zero return value is provided, as described below under
70 RETURN VALUES.
71 By default, getmsg() processes the first available message on the
74 stream head read queue. A user may, however, choose to retrieve only
75 high priority messages by setting the integer pointed to by flagsp to
76 RS_HIPRI. In this case, getmsg() processes the next message only if it
77 is a high priority message.
78 If the integer pointed to by flagsp is 0, getmsg() retrieves any mes‐
81 sage available on the stream head read queue. In this case, on return,
82 the integer pointed to by flagsp will be set to RS_HIPRI if a high
83 priority message was retrieved, or to 0 otherwise.
84 For getpmsg(), the flagsp argument points to a bitmask with the follow‐
87 ing mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY.
88 Like getmsg(), getpmsg() processes the first available message on the
89 stream head read queue. A user may choose to retrieve only high-prior‐
90 ity messages by setting the integer pointed to by flagsp to MSG_HIPRI
91 and the integer pointed to by bandp to 0. In this case, getpmsg() will
92 only process the next message if it is a high-priority message. In a
93 similar manner, a user may choose to retrieve a message from a particu‐
94 lar priority band by setting the integer pointed to by flagsp to
95 MSG_BAND and the integer pointed to by bandp to the priority band of
96 interest. In this case, getpmsg() will only process the next message if
97 it is in a priority band equal to, or greater than, the integer pointed
98 to by bandp, or if it is a high-priority message. If a user just wants
99 to get the first message off the queue, the integer pointed to by
100 flagsp should be set to MSG_ANY and the integer pointed to by bandp
101 should be set to 0. On return, if the message retrieved was a high-pri‐
102 ority message, the integer pointed to by flagsp will be set to
103 MSG_HIPRI and the integer pointed to by bandp will be set to 0. Other‐
104 wise, the integer pointed to by flagsp will be set to MSG_BAND and the
105 integer pointed to by bandp will be set to the priority band of the
106 message.
107 If O_NDELAY and O_NONBLOCK are clear, getmsg() blocks until a message
110 of the type specified by flagsp is available on the stream head read
111 queue. If O_NDELAY or O_NONBLOCK has been set and a message of the
112 specified type is not present on the read queue, getmsg() fails and
113 sets errno to EAGAIN.
114 If a hangup occurs on the stream from which messages are to be
117 retrieved, getmsg() continues to operate normally, as described above,
118 until the stream head read queue is empty. Thereafter, it returns 0 in
119 the len member of ctlptr and dataptr.
120
122 Upon successful completion, a non-negative value is returned. A return
123 value of 0 indicates that a full message was read successfully. A
124 return value of MORECTL indicates that more control information is
125 waiting for retrieval. A return value of MOREDATA indicates that more
126 data are waiting for retrieval. A return value of MORECTL | MOREDATA
127 indicates that both types of information remain. Subsequent getmsg()
128 calls retrieve the remainder of the message. However, if a message of
129 higher priority has been received by the stream head read queue, the
130 next call to getmsg() will retrieve that higher priority message before
131 retrieving the remainder of the previously received partial message.
132
134 The getmsg() and getpmsg() functions will fail if:
135 EAGAIN The O_NDELAY or O_NONBLOCK flag is set and no messages are
137 available.
138 EBADF The fildes argument is not a valid file descriptor open for
141 reading.
142 EBADMSG Queued message to be read is not valid for getmsg.
145 EFAULT The ctlptr, dataptr, bandp, or flagsp argument points to an
148 illegal address.
149 EINTR A signal was caught during the execution of the getmsg func‐
152 tion.
153 EINVAL An illegal value was specified in flagsp, or the stream ref‐
156 erenced by fildes is linked under a multiplexor.
157 ENOSTR A stream is not associated with fildes.
160 The getmsg() function can also fail if a STREAMS error message had been
164 received at the stream head before the call to getmsg(). The error
165 returned is the value contained in the STREAMS error message.
166
168 See attributes(5) for descriptions of the following attributes:
169 ┌─────────────────────────────┬─────────────────────────────┐
174 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
175 ├─────────────────────────────┼─────────────────────────────┤
176 │Interface Stability │Standard │
177 └─────────────────────────────┴─────────────────────────────┘
178
180 Intro(2), poll(2), putmsg(2), read(2), write(2), attributes(5), stan‐
181 dards(5)
182 STREAMS Programming Guide
185SunOS 5.11 1 Nov 2001 getmsg(2)