1GETMSG(3P)                 POSIX Programmer's Manual                GETMSG(3P)
2
3
4

PROLOG

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
11

NAME

13       getmsg, getpmsg — receive next message from a STREAMS file (STREAMS)
14

SYNOPSIS

16       #include <stropts.h>
17
18       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

DESCRIPTION

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
33       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
38       The  fildes argument specifies a file descriptor referencing a STREAMS-
39       based file.
40
41       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
50       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
54       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
70       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
79       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
101       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
107       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

RETURN VALUE

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
125       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
133       Upon  failure,  getmsg() and getpmsg() shall return −1 and set errno to
134       indicate the error.
135

ERRORS

137       The getmsg() and getpmsg() functions shall fail if:
138
139       EAGAIN The O_NONBLOCK flag is set and no messages are available.
140
141       EBADF  The fildes argument is not a  valid  file  descriptor  open  for
142              reading.
143
144       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
148       EINTR  A signal was caught during getmsg() or getpmsg().
149
150       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
154       ENOSTR A STREAM is not associated with fildes.
155
156       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
161       The following sections are informative.
162

EXAMPLES

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
171           #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
181           ctrl.buf = ctrlbuf;
182           ctrl.maxlen = sizeof(ctrlbuf);
183
184           data.buf = databuf;
185           data.maxlen = sizeof(databuf);
186
187           ret = getmsg (fd, &ctrl, &data, &flags);
188
189   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
193           #include <stropts.h>
194           ...
195
196           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
205           ctrl.buf = ctrlbuf;
206           ctrl.maxlen = sizeof(ctrlbuf);
207
208           data.buf = databuf;
209           data.maxlen = sizeof(databuf);
210
211           ret = getpmsg (fd, &ctrl, &data, &band, &flags);
212

APPLICATION USAGE

214       None.
215

RATIONALE

217       None.
218

FUTURE DIRECTIONS

220       The getmsg() and getpmsg() functions may be removed in  a  future  ver‐
221       sion.
222

SEE ALSO

224       Section 2.6, STREAMS, poll(), putmsg(), read(), write()
225
226       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
240       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 .
244
245
246
247IEEE/The Open Group                  2013                           GETMSG(3P)
Impressum