man3p/getmsg.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "GETMSG" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" getmsg
   4 .SH NAME
   5 getmsg, getpmsg \- receive next message from a STREAMS file (\fBSTREAMS\fP)
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <stropts.h>
   9 .br
  10 .sp
  11 int getmsg(int\fP \fIfildes\fP\fB, struct strbuf *restrict\fP \fIctlptr\fP\fB,
  12 .br
  13 \ \ \ \ \ \  struct strbuf *restrict\fP \fIdataptr\fP\fB, int *restrict\fP
  14 \fIflagsp\fP\fB);
  15 .br
  16 int getpmsg(int\fP \fIfildes\fP\fB, struct strbuf *restrict\fP \fIctlptr\fP\fB,
  17 .br
  18 \ \ \ \ \ \  struct strbuf *restrict\fP \fIdataptr\fP\fB, int *restrict\fP
  19 \fIbandp\fP\fB,
  20 .br
  21 \ \ \ \ \ \  int *restrict\fP \fIflagsp\fP\fB); \fP
  22 \fB
  23 .br
  24 \fP
  25 .SH DESCRIPTION
  26 .LP
  27 The \fIgetmsg\fP() function shall retrieve the contents of a message
  28 located at the head of the STREAM head read queue
  29 associated with a STREAMS file and place the contents into one or
  30 more buffers. The message contains either a data part, a control
  31 part, or both. The data and control parts of the message shall be
  32 placed into separate buffers, as described below. The semantics
  33 of each part are defined by the originator of the message.
  34 .LP
  35 The \fIgetpmsg\fP() function shall be equivalent to \fIgetmsg\fP(),
  36 except that it provides finer control over the priority of
  37 the messages received. Except where noted, all requirements on \fIgetmsg\fP()
  38 also pertain to \fIgetpmsg\fP().
  39 .LP
  40 The \fIfildes\fP argument specifies a file descriptor referencing
  41 a STREAMS-based file.
  42 .LP
  43 The \fIctlptr\fP and \fIdataptr\fP arguments each point to a \fBstrbuf\fP
  44 structure, in which the \fIbuf\fP member points to
  45 a buffer in which the data or control information is to be placed,
  46 and the \fImaxlen\fP member indicates the maximum number of
  47 bytes this buffer can hold. On return, the \fIlen\fP member shall
  48 contain the number of bytes of data or control information
  49 actually received. The \fIlen\fP member shall be set to 0 if there
  50 is a zero-length control or data part and \fIlen\fP shall be
  51 set to -1 if no data or control information is present in the message.
  52 .LP
  53 When \fIgetmsg\fP() is called, \fIflagsp\fP should point to an integer
  54 that indicates the type of message the process is able
  55 to receive. This is described further below.
  56 .LP
  57 The \fIctlptr\fP argument is used to hold the control part of the
  58 message, and \fIdataptr\fP is used to hold the data part of
  59 the message. If \fIctlptr\fP (or \fIdataptr\fP) is a null pointer
  60 or the \fImaxlen\fP member is -1, the control (or data) part
  61 of the message shall not be processed and shall be left on the STREAM
  62 head read queue, and if the \fIctlptr\fP (or \fIdataptr\fP)
  63 is not a null pointer, \fIlen\fP shall be set to -1. If the \fImaxlen\fP
  64 member is set to 0 and there is a zero-length control
  65 (or data) part, that zero-length part shall be removed from the read
  66 queue and \fIlen\fP shall be set to 0. If the \fImaxlen\fP
  67 member is set to 0 and there are more than 0 bytes of control (or
  68 data) information, that information shall be left on the read
  69 queue and \fIlen\fP shall be set to 0. If the \fImaxlen\fP member
  70 in \fIctlptr\fP (or \fIdataptr\fP) is less than the control
  71 (or data) part of the message, \fImaxlen\fP bytes shall be retrieved.
  72 In this case, the remainder of the message shall be left on
  73 the STREAM head read queue and a non-zero return value shall be provided.
  74 .LP
  75 By default, \fIgetmsg\fP() shall process the first available message
  76 on the STREAM head read queue. However, a process may
  77 choose to retrieve only high-priority messages by setting the integer
  78 pointed to by \fIflagsp\fP to RS_HIPRI. In this case,
  79 \fIgetmsg\fP() shall only process the next message if it is a high-priority
  80 message. When the integer pointed to by \fIflagsp\fP
  81 is 0, any available message shall be retrieved. In this case, on return,
  82 the integer pointed to by \fIflagsp\fP shall be set to
  83 RS_HIPRI if a high-priority message was retrieved, or 0 otherwise.
  84 .LP
  85 For \fIgetpmsg\fP(), the flags are different. The \fIflagsp\fP argument
  86 points to a bitmask with the following
  87 mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY.
  88 Like \fIgetmsg\fP(), \fIgetpmsg\fP() shall process the first
  89 available message on the STREAM head read queue. A process may choose
  90 to retrieve only high-priority messages by setting the
  91 integer pointed to by \fIflagsp\fP to MSG_HIPRI and the integer pointed
  92 to by \fIbandp\fP to 0. In this case, \fIgetpmsg\fP()
  93 shall only process the next message if it is a high-priority message.
  94 In a similar manner, a process may choose to retrieve a
  95 message from a particular priority band by setting the integer pointed
  96 to by \fIflagsp\fP to MSG_BAND and the integer pointed to
  97 by \fIbandp\fP to the priority band of interest. In this case, \fIgetpmsg\fP()
  98 shall only process the next message if it is in a
  99 priority band equal to, or greater than, the integer pointed to by
 100 \fIbandp\fP, or if it is a high-priority message. If a process
 101 wants to get the first message off the queue, the integer pointed
 102 to by \fIflagsp\fP should be set to MSG_ANY and the integer
 103 pointed to by \fIbandp\fP should be set to 0. On return, if the message
 104 retrieved was a high-priority message, the integer pointed
 105 to by \fIflagsp\fP shall be set to MSG_HIPRI and the integer pointed
 106 to by \fIbandp\fP shall be set to 0. Otherwise, the integer
 107 pointed to by \fIflagsp\fP shall be set to MSG_BAND and the integer
 108 pointed to by \fIbandp\fP shall be set to the priority band
 109 of the message.
 110 .LP
 111 If O_NONBLOCK is not set, \fIgetmsg\fP() and \fIgetpmsg\fP() shall
 112 block until a message of the type specified by
 113 \fIflagsp\fP is available at the front of the STREAM head read queue.
 114 If O_NONBLOCK is set and a message of the specified type is
 115 not present at the front of the read queue, \fIgetmsg\fP() and \fIgetpmsg\fP()
 116 shall fail and set \fIerrno\fP to [EAGAIN].
 117 .LP
 118 If a hangup occurs on the STREAM from which messages are retrieved,
 119 \fIgetmsg\fP() and \fIgetpmsg\fP() shall continue to
 120 operate normally, as described above, until the STREAM head read queue
 121 is empty. Thereafter, they shall return 0 in the \fIlen\fP
 122 members of \fIctlptr\fP and \fIdataptr\fP.
 123 .SH RETURN VALUE
 124 .LP
 125 Upon successful completion, \fIgetmsg\fP() and \fIgetpmsg\fP() shall
 126 return a non-negative value. A value of 0 indicates that
 127 a full message was read successfully. A return value of MORECTL indicates
 128 that more control information is waiting for retrieval. A
 129 return value of MOREDATA indicates that more data is waiting for retrieval.
 130 A return value of the bitwise-logical OR of MORECTL and
 131 MOREDATA indicates that both types of information remain. Subsequent
 132 \fIgetmsg\fP() and \fIgetpmsg\fP() calls shall retrieve the
 133 remainder of the message. However, if a message of higher priority
 134 has come in on the STREAM head read queue, the next call to
 135 \fIgetmsg\fP() or \fIgetpmsg\fP() shall retrieve that higher-priority
 136 message before retrieving the remainder of the previous
 137 message.
 138 .LP
 139 If the high priority control part of the message is consumed, the
 140 message shall be placed back on the queue as a normal message
 141 of band 0. Subsequent \fIgetmsg\fP() and \fIgetpmsg\fP() calls shall
 142 retrieve the remainder of the message. If, however, a
 143 priority message arrives or already exists on the STREAM head, the
 144 subsequent call to \fIgetmsg\fP() or \fIgetpmsg\fP() shall
 145 retrieve the higher-priority message before retrieving the remainder
 146 of the message that was put back.
 147 .LP
 148 Upon failure, \fIgetmsg\fP() and \fIgetpmsg\fP() shall return -1 and
 149 set \fIerrno\fP to indicate the error.
 150 .SH ERRORS
 151 .LP
 152 The \fIgetmsg\fP() and \fIgetpmsg\fP() functions shall fail if:
 153 .TP 7
 154 .B EAGAIN
 155 The O_NONBLOCK flag is set and no messages are available.
 156 .TP 7
 157 .B EBADF
 158 The \fIfildes\fP argument is not a valid file descriptor open for
 159 reading.
 160 .TP 7
 161 .B EBADMSG
 162 The queued message to be read is not valid for \fIgetmsg\fP() or \fIgetpmsg\fP()
 163 or a pending file descriptor is at the
 164 STREAM head.
 165 .TP 7
 166 .B EINTR
 167 A signal was caught during \fIgetmsg\fP() or \fIgetpmsg\fP().
 168 .TP 7
 169 .B EINVAL
 170 An illegal value was specified by \fIflagsp\fP, or the STREAM or multiplexer
 171 referenced by \fIfildes\fP is linked (directly
 172 or indirectly) downstream from a multiplexer.
 173 .TP 7
 174 .B ENOSTR
 175 A STREAM is not associated with \fIfildes\fP.
 176 .sp
 177 .LP
 178 In addition, \fIgetmsg\fP() and \fIgetpmsg\fP() shall fail if the
 179 STREAM head had processed an asynchronous error before the
 180 call. In this case, the value of \fIerrno\fP does not reflect the
 181 result of \fIgetmsg\fP() or \fIgetpmsg\fP() but reflects the
 182 prior error.
 183 .LP
 184 \fIThe following sections are informative.\fP
 185 .SH EXAMPLES
 186 .SS Getting Any Message
 187 .LP
 188 In the following example, the value of \fIfd\fP is assumed to refer
 189 to an open STREAMS file. The call to \fIgetmsg\fP()
 190 retrieves any available message on the associated STREAM-head read
 191 queue, returning control and data information to the buffers
 192 pointed to by \fIctrlbuf\fP and \fIdatabuf\fP, respectively.
 193 .sp
 194 .RS
 195 .nf
 196
 197 \fB#include <stropts.h>
 198 \&...
 199 int fd;
 200 char ctrlbuf[128];
 201 char databuf[512];
 202 struct strbuf ctrl;
 203 struct strbuf data;
 204 int flags = 0;
 205 int ret;
 206 .sp
 207
 208 ctrl.buf = ctrlbuf;
 209 ctrl.maxlen = sizeof(ctrlbuf);
 210 .sp
 211
 212 data.buf = databuf;
 213 data.maxlen = sizeof(databuf);
 214 .sp
 215
 216 ret = getmsg (fd, &ctrl, &data, &flags);
 217 \fP
 218 .fi
 219 .RE
 220 .SS Getting the First Message off the Queue
 221 .LP
 222 In the following example, the call to \fIgetpmsg\fP() retrieves the
 223 first available message on the associated STREAM-head read
 224 queue.
 225 .sp
 226 .RS
 227 .nf
 228
 229 \fB#include <stropts.h>
 230 \&...
 231 .sp
 232
 233 int fd;
 234 char ctrlbuf[128];
 235 char databuf[512];
 236 struct strbuf ctrl;
 237 struct strbuf data;
 238 int band = 0;
 239 int flags = MSG_ANY;
 240 int ret;
 241 .sp
 242
 243 ctrl.buf = ctrlbuf;
 244 ctrl.maxlen = sizeof(ctrlbuf);
 245 .sp
 246
 247 data.buf = databuf;
 248 data.maxlen = sizeof(databuf);
 249 .sp
 250
 251 ret = getpmsg (fd, &ctrl, &data, &band, &flags);
 252 \fP
 253 .fi
 254 .RE
 255 .SH APPLICATION USAGE
 256 .LP
 257 None.
 258 .SH RATIONALE
 259 .LP
 260 None.
 261 .SH FUTURE DIRECTIONS
 262 .LP
 263 None.
 264 .SH SEE ALSO
 265 .LP
 266 \fISTREAMS\fP , \fIpoll\fP() , \fIputmsg\fP() , \fIread\fP() , \fIwrite\fP()
 267 , the Base
 268 Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<stropts.h>\fP
 269 .SH COPYRIGHT
 270 Portions of this text are reprinted and reproduced in electronic form
 271 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 272 -- Portable Operating System Interface (POSIX), The Open Group Base
 273 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 274 Electrical and Electronics Engineers, Inc and The Open Group. In the
 275 event of any discrepancy between this version and the original IEEE and
 276 The Open Group Standard, the original IEEE and The Open Group Standard
 277 is the referee document. The original Standard can be obtained online at
 278 http://www.opengroup.org/unix/online.html .