| blob | 5b79c58d162207d91ddf1558d8de833404302d20 |
1 '\" te
2 .\" Copyright 1989 AT&T. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH GETMSG 2 "Nov 1, 2001"
7 .SH NAME
8 getmsg, getpmsg \- get next message off a stream
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <stropts.h>
14 \fBint\fR \fBgetmsg\fR(\fBint\fR \fIfildes\fR, \fBstruct strbuf *restrict\fR \fIctlptr\fR,
15 \fBstruct strbuf *restrict\fR \fIdataptr\fR, \fBint *restrict\fR \fIflagsp\fR);
16 .fi
18 .LP
19 .nf
20 \fBint\fR \fBgetpmsg\fR(\fBint\fR \fIfildes\fR, \fBstruct strbuf *restrict\fR \fIctlptr\fR,
21 \fBstruct strbuf *restrict\fR \fIdataptr\fR, \fBint *restrict\fR \fIbandp\fR,
22 \fBint *restrict\fR \fIflagsp\fR);
23 .fi
25 .SH DESCRIPTION
26 .sp
27 .LP
28 The \fBgetmsg()\fR function retrieves the contents of a message (see
29 \fBIntro\fR(2)) located at the stream head read queue from a STREAMS file, and
30 places the contents into user specified buffer(s). The message must contain
31 either a data part, a control part, or both. The data and control parts of the
32 message are placed into separate buffers, as described below. The semantics of
33 each part is defined by the STREAMS module that generated the message.
34 .sp
35 .LP
36 The \fBgetpmsg()\fR function behaved like \fBgetmsg()\fR, but provides finer
37 control over the priority of the messages received. Except where noted, all
38 information pertaining to \fBgetmsg()\fR also pertains to \fBgetpmsg()\fR.
39 .sp
40 .LP
41 The \fIfildes\fR argument specifies a file descriptor referencing an open
42 stream. The \fIctlptr\fR and \fIdataptr\fR arguments each point to a
43 \fBstrbuf\fR structure, which contains the following members:
44 .sp
45 .in +2
46 .nf
47 int maxlen; /* maximum buffer length */
48 int len; /* length of data */
49 char *buf; /* ptr to buffer */
50 .fi
51 .in -2
53 .sp
54 .LP
55 The \fBbuf\fR member points to a buffer into which the data or control
56 information is to be placed, and the \fBmaxlen\fR member indicates the maximum
57 number of bytes this buffer can hold. On return, the \fBlen\fR member contains
58 the number of bytes of data or control information actually received; 0 if
59 there is a zero-length control or data part; or \(mi1 if no data or control
60 information is present in the message. The \fIflagsp\fR argument should point
61 to an integer that indicates the type of message the user is able to receive,
62 as described below.
63 .sp
64 .LP
65 The \fIctlptr\fR argument holds the control part from the message and the
66 \fIdataptr\fR argument holds the data part from the message. If \fIctlptr\fR
67 (or \fIdataptr\fR) is \fINULL\fR or the \fBmaxlen\fR member is \(mi1, the
68 control (or data) part of the message is not processed and is left on the
69 stream head read queue. If \fIctlptr\fR (or \fIdataptr\fR) is not \fINULL\fR
70 and there is no corresponding control (or data) part of the messages on the
71 stream head read queue, \fBlen\fR is set to \(mi1. If the \fBmaxlen\fR member
72 is set to 0 and there is a zero-length control (or data) part, that
73 zero-length part is removed from the read queue and \fBlen\fR is set to 0. If
74 the \fBmaxlen\fR member is set to 0 and there are more than zero bytes of
75 control (or data) information, that information is left on the read queue and
76 \fBlen\fR is set to 0. If the \fBmaxlen\fR member in \fIctlptr\fR or
77 \fIdataptr\fR is less than, respectively, the control or data part of the
78 message, \fBmaxlen\fR bytes are retrieved. In this case, the remainder of the
79 message is left on the stream head read queue and a non-zero return value is
80 provided, as described below under \fBRETURN VALUES\fR.
81 .sp
82 .LP
83 By default, \fBgetmsg()\fR processes the first available message on the stream
84 head read queue. A user may, however, choose to retrieve only high priority
85 messages by setting the integer pointed to by \fIflagsp\fR to \fBRS_HIPRI\fR.
86 In this case, \fBgetmsg()\fR processes the next message only if it is a high
87 priority message.
88 .sp
89 .LP
90 If the integer pointed to by \fIflagsp\fR is 0, \fBgetmsg()\fR retrieves any
91 message available on the stream head read queue. In this case, on return, the
92 integer pointed to by \fIflagsp\fR will be set to \fBRS_HIPRI\fR if a high
93 priority message was retrieved, or to 0 otherwise.
94 .sp
95 .LP
96 For \fBgetpmsg()\fR, the \fIflagsp\fR argument points to a bitmask with the
97 following mutually-exclusive flags defined: \fBMSG_HIPRI\fR, \fBMSG_BAND\fR,
98 and \fBMSG_ANY\fR. Like \fBgetmsg()\fR, \fBgetpmsg()\fR processes the first
99 available message on the stream head read queue. A user may choose to retrieve
100 only high-priority messages by setting the integer pointed to by \fIflagsp\fR
101 to \fBMSG_HIPRI\fR and the integer pointed to by \fIbandp\fR to 0. In this
102 case, \fBgetpmsg()\fR will only process the next message if it is a
103 high-priority message. In a similar manner, a user may choose to retrieve a
104 message from a particular priority band by setting the integer pointed to by
105 \fIflagsp\fR to \fBMSG_BAND\fR and the integer pointed to by \fIbandp\fR to the
106 priority band of interest. In this case, \fBgetpmsg()\fR will only process the
107 next message if it is in a priority band equal to, or greater than, the integer
108 pointed to by \fIbandp\fR, or if it is a high-priority message. If a user just
109 wants to get the first message off the queue, the integer pointed to by
110 \fIflagsp\fR should be set to \fBMSG_ANY\fR and the integer pointed to by
111 \fIbandp\fR should be set to 0. On return, if the message retrieved was a
112 high-priority message, the integer pointed to by \fIflagsp\fR will be set to
113 \fBMSG_HIPRI\fR and the integer pointed to by \fIbandp\fR will be set to 0.
114 Otherwise, the integer pointed to by \fIflagsp\fR will be set to \fBMSG_BAND\fR
115 and the integer pointed to by \fIbandp\fR will be set to the priority band of
116 the message.
117 .sp
118 .LP
119 If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear, \fBgetmsg()\fR blocks until a
120 message of the type specified by \fIflagsp\fR is available on the stream head
121 read queue. If \fBO_NDELAY\fR or \fBO_NONBLOCK\fR has been set and a message
122 of the specified type is not present on the read queue, \fBgetmsg()\fR fails
123 and sets \fBerrno\fR to \fBEAGAIN\fR.
124 .sp
125 .LP
126 If a hangup occurs on the stream from which messages are to be retrieved,
127 \fBgetmsg()\fR continues to operate normally, as described above, until the
128 stream head read queue is empty. Thereafter, it returns 0 in the \fBlen\fR
129 member of \fIctlptr\fR and \fIdataptr\fR.
130 .SH RETURN VALUES
131 .sp
132 .LP
133 Upon successful completion, a non-negative value is returned. A return value of
134 \fB0\fR indicates that a full message was read successfully. A return value of
135 \fBMORECTL\fR indicates that more control information is waiting for retrieval.
136 A return value of \fBMOREDATA\fR indicates that more data are waiting for
137 retrieval. A return value of \fBMORECTL\fR | \fBMOREDATA\fR indicates that both
138 types of information remain. Subsequent \fBgetmsg()\fR calls retrieve the
139 remainder of the message. However, if a message of higher priority has been
140 received by the stream head read queue, the next call to \fBgetmsg()\fR will
141 retrieve that higher priority message before retrieving the remainder of the
142 previously received partial message.
143 .SH ERRORS
144 .sp
145 .LP
146 The \fBgetmsg()\fR and \fBgetpmsg()\fR functions will fail if:
147 .sp
148 .ne 2
149 .na
150 \fB\fBEAGAIN\fR\fR
151 .ad
152 .RS 11n
153 The \fBO_NDELAY\fR or \fBO_NONBLOCK\fR flag is set and no messages are
154 available.
155 .RE
157 .sp
158 .ne 2
159 .na
160 \fB\fBEBADF\fR\fR
161 .ad
162 .RS 11n
163 The \fIfildes\fR argument is not a valid file descriptor open for reading.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fBEBADMSG\fR\fR
170 .ad
171 .RS 11n
172 Queued message to be read is not valid for \fBgetmsg\fR.
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fBEFAULT\fR\fR
179 .ad
180 .RS 11n
181 The \fIctlptr\fR, \fIdataptr\fR, \fIbandp\fR, or \fIflagsp\fR argument points
182 to an illegal address.
183 .RE
185 .sp
186 .ne 2
187 .na
188 \fB\fBEINTR\fR\fR
189 .ad
190 .RS 11n
191 A signal was caught during the execution of the \fBgetmsg\fR function.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fBEINVAL\fR\fR
198 .ad
199 .RS 11n
200 An illegal value was specified in \fIflagsp\fR, or the stream referenced by
201 \fIfildes\fR is linked under a multiplexor.
202 .RE
204 .sp
205 .ne 2
206 .na
207 \fB\fBENOSTR\fR\fR
208 .ad
209 .RS 11n
210 A stream is not associated with \fIfildes\fR.
211 .RE
213 .sp
214 .LP
215 The \fBgetmsg()\fR function can also fail if a STREAMS error message had been
216 received at the stream head before the call to \fBgetmsg()\fR. The error
217 returned is the value contained in the STREAMS error message.
218 .SH ATTRIBUTES
219 .sp
220 .LP
221 See \fBattributes\fR(5) for descriptions of the following attributes:
222 .sp
224 .sp
225 .TS
226 box;
227 c | c
228 l | l .
229 ATTRIBUTE TYPE ATTRIBUTE VALUE
230 _
231 Interface Stability Standard
232 .TE
234 .SH SEE ALSO
235 .sp
236 .LP
237 \fBIntro\fR(2), \fBpoll\fR(2), \fBputmsg\fR(2), \fBread\fR(2), \fBwrite\fR(2),
238 \fBattributes\fR(5), \fBstandards\fR(5)
239 .sp
240 .LP
241 \fISTREAMS Programming Guide\fR