1GETMSG(3P) POSIX Programmer's Manual GETMSG(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 getmsg, getpmsg — receive next message from a STREAMS file (STREAMS)
14
16 #include <stropts.h>
17 int getmsg(int fildes, struct strbuf *restrict ctlptr,
19 struct strbuf *restrict dataptr, int *restrict flagsp);
20 int getpmsg(int fildes, struct strbuf *restrict ctlptr,
21 struct strbuf *restrict dataptr, int *restrict bandp,
22 int *restrict flagsp);
23
25 The getmsg() function shall retrieve the contents of a message located
26 at the head of the STREAM head read queue associated with a STREAMS
27 file and place the contents into one or more buffers. The message con‐
28 tains either a data part, a control part, or both. The data and control
29 parts of the message shall be placed into separate buffers, as
30 described below. The semantics of each part are defined by the origina‐
31 tor of the message.
32 The getpmsg() function shall be equivalent to getmsg(), except that it
34 provides finer control over the priority of the messages received.
35 Except where noted, all requirements on getmsg() also pertain to
36 getpmsg().
37 The fildes argument specifies a file descriptor referencing a STREAMS-
39 based file.
40 The ctlptr and dataptr arguments each point to a strbuf structure, in
42 which the buf member points to a buffer in which the data or control
43 information is to be placed, and the maxlen member indicates the maxi‐
44 mum number of bytes this buffer can hold. On return, the len member
45 shall contain the number of bytes of data or control information actu‐
46 ally received. The len member shall be set to 0 if there is a zero-
47 length control or data part and len shall be set to −1 if no data or
48 control information is present in the message.
49 When getmsg() is called, flagsp should point to an integer that indi‐
51 cates the type of message the process is able to receive. This is
52 described further below.
53 The ctlptr argument is used to hold the control part of the message,
55 and dataptr is used to hold the data part of the message. If ctlptr (or
56 dataptr) is a null pointer or the maxlen member is −1, the control (or
57 data) part of the message shall not be processed and shall be left on
58 the STREAM head read queue, and if the ctlptr (or dataptr) is not a
59 null pointer, len shall be set to −1. If the maxlen member is set to 0
60 and there is a zero-length control (or data) part, that zero-length
61 part shall be removed from the read queue and len shall be set to 0. If
62 the maxlen member is set to 0 and there are more than 0 bytes of con‐
63 trol (or data) information, that information shall be left on the read
64 queue and len shall be set to 0. If the maxlen member in ctlptr (or
65 dataptr) is less than the control (or data) part of the message, maxlen
66 bytes shall be retrieved. In this case, the remainder of the message
67 shall be left on the STREAM head read queue and a non-zero return value
68 shall be provided.
69 By default, getmsg() shall process the first available message on the
71 STREAM head read queue. However, a process may choose to retrieve only
72 high-priority messages by setting the integer pointed to by flagsp to
73 RS_HIPRI. In this case, getmsg() shall only process the next message if
74 it is a high-priority message. When the integer pointed to by flagsp
75 is 0, any available message shall be retrieved. In this case, on
76 return, the integer pointed to by flagsp shall be set to RS_HIPRI if a
77 high-priority message was retrieved, or 0 otherwise.
78 For getpmsg(), the flags are different. The flagsp argument points to a
80 bitmask with the following mutually-exclusive flags defined: MSG_HIPRI,
81 MSG_BAND, and MSG_ANY. Like getmsg(), getpmsg() shall process the
82 first available message on the STREAM head read queue. A process may
83 choose to retrieve only high-priority messages by setting the integer
84 pointed to by flagsp to MSG_HIPRI and the integer pointed to by bandp
85 to 0. In this case, getpmsg() shall only process the next message if it
86 is a high-priority message. In a similar manner, a process may choose
87 to retrieve a message from a particular priority band by setting the
88 integer pointed to by flagsp to MSG_BAND and the integer pointed to by
89 bandp to the priority band of interest. In this case, getpmsg() shall
90 only process the next message if it is in a priority band equal to, or
91 greater than, the integer pointed to by bandp, or if it is a high-pri‐
92 ority message. If a process wants to get the first message off the
93 queue, the integer pointed to by flagsp should be set to MSG_ANY and
94 the integer pointed to by bandp should be set to 0. On return, if the
95 message retrieved was a high-priority message, the integer pointed to
96 by flagsp shall be set to MSG_HIPRI and the integer pointed to by bandp
97 shall be set to 0. Otherwise, the integer pointed to by flagsp shall be
98 set to MSG_BAND and the integer pointed to by bandp shall be set to the
99 priority band of the message.
100 If O_NONBLOCK is not set, getmsg() and getpmsg() shall block until a
102 message of the type specified by flagsp is available at the front of
103 the STREAM head read queue. If O_NONBLOCK is set and a message of the
104 specified type is not present at the front of the read queue, getmsg()
105 and getpmsg() shall fail and set errno to [EAGAIN].
106 If a hangup occurs on the STREAM from which messages are retrieved,
108 getmsg() and getpmsg() shall continue to operate normally, as described
109 above, until the STREAM head read queue is empty. Thereafter, they
110 shall return 0 in the len members of ctlptr and dataptr.
111
113 Upon successful completion, getmsg() and getpmsg() shall return a non-
114 negative value. A value of 0 indicates that a full message was read
115 successfully. A return value of MORECTL indicates that more control
116 information is waiting for retrieval. A return value of MOREDATA indi‐
117 cates that more data is waiting for retrieval. A return value of the
118 bitwise-logical OR of MORECTL and MOREDATA indicates that both types of
119 information remain. Subsequent getmsg() and getpmsg() calls shall
120 retrieve the remainder of the message. However, if a message of higher
121 priority has come in on the STREAM head read queue, the next call to
122 getmsg() or getpmsg() shall retrieve that higher-priority message
123 before retrieving the remainder of the previous message.
124 If the high priority control part of the message is consumed, the mes‐
126 sage shall be placed back on the queue as a normal message of band 0.
127 Subsequent getmsg() and getpmsg() calls shall retrieve the remainder of
128 the message. If, however, a priority message arrives or already exists
129 on the STREAM head, the subsequent call to getmsg() or getpmsg() shall
130 retrieve the higher-priority message before retrieving the remainder of
131 the message that was put back.
132 Upon failure, getmsg() and getpmsg() shall return −1 and set errno to
134 indicate the error.
135
137 The getmsg() and getpmsg() functions shall fail if:
138 EAGAIN The O_NONBLOCK flag is set and no messages are available.
140 EBADF The fildes argument is not a valid file descriptor open for
142 reading.
143 EBADMSG
145 The queued message to be read is not valid for getmsg() or
146 getpmsg() or a pending file descriptor is at the STREAM head.
147 EINTR A signal was caught during getmsg() or getpmsg().
149 EINVAL An illegal value was specified by flagsp, or the STREAM or mul‐
151 tiplexer referenced by fildes is linked (directly or indirectly)
152 downstream from a multiplexer.
153 ENOSTR A STREAM is not associated with fildes.
155 In addition, getmsg() and getpmsg() shall fail if the STREAM head had
157 processed an asynchronous error before the call. In this case, the
158 value of errno does not reflect the result of getmsg() or getpmsg() but
159 reflects the prior error.
160 The following sections are informative.
162
164 Getting Any Message
165 In the following example, the value of fd is assumed to refer to an
166 open STREAMS file. The call to getmsg() retrieves any available message
167 on the associated STREAM-head read queue, returning control and data
168 information to the buffers pointed to by ctrlbuf and databuf, respec‐
169 tively.
170 #include <stropts.h>
172 ...
173 int fd;
174 char ctrlbuf[128];
175 char databuf[512];
176 struct strbuf ctrl;
177 struct strbuf data;
178 int flags = 0;
179 int ret;
180 ctrl.buf = ctrlbuf;
182 ctrl.maxlen = sizeof(ctrlbuf);
183 data.buf = databuf;
185 data.maxlen = sizeof(databuf);
186 ret = getmsg (fd, &ctrl, &data, &flags);
188 Getting the First Message off the Queue
190 In the following example, the call to getpmsg() retrieves the first
191 available message on the associated STREAM-head read queue.
192 #include <stropts.h>
194 ...
195 int fd;
197 char ctrlbuf[128];
198 char databuf[512];
199 struct strbuf ctrl;
200 struct strbuf data;
201 int band = 0;
202 int flags = MSG_ANY;
203 int ret;
204 ctrl.buf = ctrlbuf;
206 ctrl.maxlen = sizeof(ctrlbuf);
207 data.buf = databuf;
209 data.maxlen = sizeof(databuf);
210 ret = getpmsg (fd, &ctrl, &data, &band, &flags);
212
214 None.
215
217 None.
218
220 The getmsg() and getpmsg() functions may be removed in a future ver‐
221 sion.
222
224 Section 2.6, STREAMS, poll(), putmsg(), read(), write()
225 The Base Definitions volume of POSIX.1‐2008, <stropts.h>
227
229 Portions of this text are reprinted and reproduced in electronic form
230 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
231 -- Portable Operating System Interface (POSIX), The Open Group Base
232 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
233 cal and Electronics Engineers, Inc and The Open Group. (This is
234 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
235 event of any discrepancy between this version and the original IEEE and
236 The Open Group Standard, the original IEEE and The Open Group Standard
237 is the referee document. The original Standard can be obtained online
238 at http://www.unix.org/online.html .
239 Any typographical or formatting errors that appear in this page are
241 most likely to have been introduced during the conversion of the source
242 files to man page format. To report such errors, see https://www.ker‐
243 nel.org/doc/man-pages/reporting_bugs.html .
244IEEE/The Open Group 2013 GETMSG(3P)