Penguin
Recent Changes
Annotated edit history of msgrcv(2) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 MSGOP
2 !!!MSGOP
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 ERRORS
8 NOTES
9 CONFORMING TO
10 NOTE
11 SEE ALSO
12 ----
13 !!NAME
14
15
16 msgop - message operations
17 !!SYNOPSIS
18
19
20 __# include
21 ____int msgsnd ( int__ ''msqid''__, struct msgbuf *__''msgp''__, size_t__ ''msgsz''__, int__ ''msgflg'' __)__
22
23
24 __ssize_t msgrcv ( int__ ''msqid''__, struct msgbuf
25 *__''msgp''__, size_t__ ''msgsz''__, long__
26 ''msgtyp''__, int__ ''msgflg''
27 __)__
28 !!DESCRIPTION
29
30
31 To send or receive a message, the calling process allocates
32 a structure that looks like the following
33
34
35 __struct msgbuf {
36 long mtype;__ /* message type, must be __
37 char mtext[[1];__ /* message data */__
38 };__
39
40
41 but with an array __mtext__ of size ''msgsz'', a
42 non-negative integer value. The structure member
43 __mtype__ must have a strictly positive integer value
44 that can be used by the receiving process for message
45 selection (see the section about
46 __msgrcv__).
47
48
49 The calling process must have write access permissions to
50 send and read access permissions to receive a message on the
51 queue.
52
53
54 The __msgsnd__ system call enqueues a copy of the message
55 pointed to by the ''msgp'' argument on the message queue
56 whose identifier is specified by the value of the
57 ''msqid'' argument.
58
59
60 The argument ''msgflg'' specifies the system call
61 behaviour if enqueuing the new message will require more
62 than __msg_qbytes__ in the queue. Asserting
63 __IPC_NOWAIT__ the message will not be sent and the
64 system call fails returning with __errno__ set to
65 __EAGAIN__. Otherwise the process is suspended until the
66 condition for the suspension no longer exists (in which case
67 the message is sent and the system call succeeds), or the
68 queue is removed (in which case the system call fails with
69 __errno__ set to __EIDRM__), or the process receives a
70 signal that has to be caught (in which case the system call
71 fails with __errno__ set to __EINTR__).
72
73
74 Upon successful completion the message queue data structure
75 is updated as follows:
76
77
78 __msg_lspid__ is set to the process-ID of the calling
79 process.
80
81
82 __msg_qnum__ is incremented by 1.
83
84
85 __msg_stime__ is set to the current time.
86
87
88 The system call __msgrcv__ reads a message from the
89 message queue specified by ''msqid'' into the
90 __msgbuf__ pointed to by the ''msgp'' argument
91 removing from the queue, on success, the read
92 message.
93
94
95 The argument ''msgsz'' specifies the maximum size in
96 bytes for the member __mtext__ of the structure pointed
97 to by the ''msgp'' argument. If the message text has
98 length greater than ''msgsz'', then if the ''msgflg''
99 argument asserts __MSG_NOERROR__, the message text will
100 be truncated (and the truncated part will be lost),
101 otherwise the message isn't removed from the queue and the
102 system call fails returning with __errno__ set to
103 __E2BIG__.
104
105
106 The argument ''msgtyp'' specifies the type of message
107 requested as follows:
108
109
110 If ''msgtyp'' is __0__, then the message on the
111 queue's front is read.
112
113
114 If ''msgtyp'' is greater than __0__, then the first
115 message on the queue of type ''msgtyp'' is read if
116 __MSG_EXCEPT__ isn't asserted by the ''msgflg''
117 argument, otherwise the first message on the queue of type
118 not equal to ''msgtyp'' will be read.
119
120
121 If ''msgtyp'' is less than __0__, then the first
122 message on the queue with the lowest type less than or equal
123 to the absolute value of ''msgtyp'' will be
124 read.
125
126
127 The ''msgflg'' argument asserts none, one or more (or-ing
128 them) among the following flags:
129
130
131 __IPC_NOWAIT__ For immediate return if no message of the
132 requested type is on the queue. The system call fails with
133 errno set to __ENOMSG__.
134
135
136 __MSG_EXCEPT__ Used with ''msgtyp'' greater than
137 __0__ to read the first message on the queue with message
138 type that differs from ''msgtyp''.
139
140
141 __MSG_NOERROR__ To truncate the message text if longer
142 than ''msgsz'' bytes.
143
144
145 If no message of the requested type is available and
146 __IPC_NOWAIT__ isn't asserted in ''msgflg'', the
147 calling process is blocked until one of the following
148 conditions occurs:
149
150
151 A message of the desired type is placed on the
152 queue.
153
154
155 The message queue is removed from the system. In such a case
156 the system call fails with __errno__ set to
157 __EIDRM__.
158
159
160 The calling process receives a signal that has to be caught.
161 In such a case the system call fails with __errno__ set
162 to __EINTR__.
163
164
165 Upon successful completion the message queue data structure
166 is updated as follows:
167
168
169 __msg_lrpid__ is set to the process-ID of the calling
170 process.
171
172
173 __msg_qnum__ is decremented by 1.
174
175
176 __msg_rtime__ is set to the current time.
177 !!RETURN VALUE
178
179
180 On a failure both functions return __-1__ with
181 __errno__ indicating the error, otherwise __msgsnd__
182 returns __0__ and __msgrvc__ returns the number of
183 bytes actually copied into the __mtext__
184 array.
185 !!ERRORS
186
187
188 When __msgsnd__ fails, at return __errno__ will be set
189 to one among the following values:
190
191
192 __EAGAIN__
193
194
195 The message can't be sent due to the __msg_qbytes__ limit
196 for the queue and __IPC_NOWAIT__ was asserted in
197 ''mgsflg''.
198
199
200 __EACCES__
201
202
203 The calling process has no write access permissions on the
204 message queue.
205
206
207 __EFAULT__
208
209
210 The address pointed to by ''msgp'' isn't
211 accessible.
212
213
214 __EIDRM__
215
216
217 The message queue was removed.
218
219
220 __EINTR__
221
222
223 Sleeping on a full message queue condition, the process
224 received a signal that had to be caught.
225
226
227 __EINVAL__
228
229
230 Invalid ''msqid'' value, or nonpositive ''mtype''
231 value, or invalid ''msgsz'' value (less than 0 or greater
232 than the system value __MSGMAX__).
233
234
235 __ENOMEM__
236
237
238 The system has not enough memory to make a copy of the
239 supplied __msgbuf__.
240
241
242 When __msgrcv__ fails, at return __errno__ will be set
243 to one among the following values:
244
245
246 __E2BIG__
247
248
249 The message text length is greater than ''msgsz'' and
250 __MSG_NOERROR__ isn't asserted in
251 ''msgflg''.
252
253
254 __EACCES__
255
256
257 The calling process has no read access permissions on the
258 message queue.
259
260
261 __EFAULT__
262
263
264 The address pointed to by ''msgp'' isn't
265 accessible.
266
267
268 __EIDRM__
269
270
271 While the process was sleeping to receive a message, the
272 message queue was removed.
273
274
275 __EINTR__
276
277
278 While the process was sleeping to receive a message, the
279 process received a signal that had to be
280 caught.
281
282
283 __EINVAL__
284
285
286 Illegal ''msgqid'' value, or ''msgsz'' less than
287 __0__.
288
289
290 __ENOMSG__
291
292
293 __IPC_NOWAIT__ was asserted in ''msgflg'' and no
294 message of the requested type existed on the message
295 queue.
296 !!NOTES
297
298
299 The followings are system limits affecting a __msgsnd__
300 system call:
301
302
303 __MSGMAX__
304
305
306 Maximum size for a message text: the implementation set this
307 value to 4080 bytes.
308
309
310 __MSGMNB__
311
312
313 Default maximum size in bytes of a message queue: policy
314 dependent. The super-user can increase the size of a message
315 queue beyond __MSGMNB__ by a __msgctl__ system
316 call.
317
318
319 The implementation has no intrinsic limits for the system
320 wide maximum number of message headers (__MSGTQL__) and
321 for the system wide maximum size in bytes of the message
322 pool (__MSGPOOL__).
323 !!CONFORMING TO
324
325
326 SVr4, SVID.
327 !!NOTE
328
329
330 The pointer argument is declared as ''struct msgbuf *''
331 with libc4, libc5, glibc 2.0, glibc 2.1. It is declared as
332 ''void *'' (''const void *'' for ''msgsnd()'') with
333 glibc 2.2, following the SUSv2.
334 !!SEE ALSO
335
336
337 ipc(5), msgctl(2), msgget(2),
338 msgrcv(2), msgsnd(2)
339 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.