1 | @c |
---|
2 | @c COPYRIGHT(c) 1988-1998. |
---|
3 | @c On-Line Applications Research Corporation(OAR). |
---|
4 | @c All rights reserved. |
---|
5 | @c |
---|
6 | @c $Id$ |
---|
7 | @c |
---|
8 | |
---|
9 | @chapter Message Passing Manager |
---|
10 | |
---|
11 | @section Introduction |
---|
12 | |
---|
13 | The message passing manager is the means to provide communication and |
---|
14 | synchronization capabilities using POSIX message queues. |
---|
15 | |
---|
16 | The directives provided by the message passing manager are: |
---|
17 | |
---|
18 | @itemize @bullet |
---|
19 | @item @code{mq_open} - Open a Message Queue |
---|
20 | @item @code{mq_close} - Close a Message Queue |
---|
21 | @item @code{mq_unlink} - Remove a Message Queue |
---|
22 | @item @code{mq_send} - Send a Message to a Message Queue |
---|
23 | @item @code{mq_receive} - Receive a Message from a Message Queue |
---|
24 | @item @code{mq_notify} - Notify Process that a Message is Available |
---|
25 | @item @code{mq_setattr} - Set Message Queue Attributes |
---|
26 | @item @code{mq_getattr} - Get Message Queue Attributes |
---|
27 | @end itemize |
---|
28 | |
---|
29 | @section Background |
---|
30 | |
---|
31 | @subsection Theory |
---|
32 | |
---|
33 | Message queues are named objects that operate with readers and writers. |
---|
34 | In addition, a message queue is a priority queue of discrete messages. |
---|
35 | POSIX message queues offer a certain, basic amount of application access |
---|
36 | to, and control over, the message queue geometry that can be changed. |
---|
37 | |
---|
38 | @subsection Messages |
---|
39 | |
---|
40 | A message is a variable length buffer where information can be stored to |
---|
41 | support communication. The length of the message and the information |
---|
42 | stored in that message are user-defined and can be actual data, |
---|
43 | pointer(s), or empty. There is a maximum acceptable length for a message |
---|
44 | that is associated with each message queue. |
---|
45 | |
---|
46 | @subsection Message Queues |
---|
47 | |
---|
48 | Message queues are named objects similar to the pipes of POSIX. They are |
---|
49 | a means of communicating data between multiple processes and for passing |
---|
50 | messages among tasks and ISRs. Message queues can contain a variable |
---|
51 | number of messages from 0 to an upper limit that is user defined. The |
---|
52 | maximum length of the message can be set on a per message queue basis. |
---|
53 | Normally messages are sent and received from the message queue in FIFO |
---|
54 | order. However, messages can also be prioritized and a priority queue |
---|
55 | established for the passing of messages. Synchronization is needed when a |
---|
56 | task waits for a message to arrive at a queue. Also, a task may poll a |
---|
57 | queue for the arrival of a message. |
---|
58 | |
---|
59 | @findex mqd_t |
---|
60 | The message queue descriptor @code{mqd_t} represents the message queue. It is |
---|
61 | passed as an argument to all of the message queue functions. |
---|
62 | |
---|
63 | @subsection Building a Message Queue Attribute Set |
---|
64 | |
---|
65 | The mq_attr structure is used to define the characteristics of the message |
---|
66 | queue. |
---|
67 | |
---|
68 | @findex mq_attr |
---|
69 | @example |
---|
70 | @group |
---|
71 | typedef struct mq_attr@{ |
---|
72 | long mq_flags; |
---|
73 | long mq_maxmsg; |
---|
74 | long mq_msgsize; |
---|
75 | long mq_curmsgs; |
---|
76 | @}; |
---|
77 | @end group |
---|
78 | @end example |
---|
79 | |
---|
80 | All of these attributes are set when the message queue is created using |
---|
81 | mq_open. The mq_flags field is not used in the creation of a message |
---|
82 | queue, it is only used by mq_setattr and mq_getattr. The structure |
---|
83 | mq_attr is passed as an argument to mq_setattr and mq_getattr. |
---|
84 | |
---|
85 | The mq_flags contain information affecting the behavior of the message |
---|
86 | queue. The O_NONBLOCK mq_flag is the only flag that is defined. In |
---|
87 | mq_setattr, the mq_flag can be set to dynamically change the blocking and |
---|
88 | non-blocking behavior of the message queue. If the non-block flag is set |
---|
89 | then the message queue is non-blocking, and requests to send and receive |
---|
90 | messages do not block waiting for resources. For a blocking message |
---|
91 | queue, a request to send might have to wait for an empty message queue, |
---|
92 | and a request to receive might have to wait for a message to arrive on the |
---|
93 | queue. Both mq_maxmsg and mq_msgsize affect the sizing of the message |
---|
94 | queue. mq_maxmsg specifies how many messages the queue can hold at any |
---|
95 | one time. mq_msgsize specifies the size of any one message on the queue. |
---|
96 | If either of these limits is exceeded, an error message results. |
---|
97 | |
---|
98 | Upon return from mq_getattr, the mq_curmsgs is set according to the |
---|
99 | current state of the message queue. This specifies the number of messages |
---|
100 | currently on the queue. |
---|
101 | |
---|
102 | @subsection Notification of a Message on the Queue |
---|
103 | |
---|
104 | Every message queue has the ability to notify one (and only one) process |
---|
105 | whenever the queue's state changes from empty (0 messages) to nonempty. |
---|
106 | This means that the process does not have to block or constantly poll |
---|
107 | while it waits for a message. By calling mq_notify, you can attach a |
---|
108 | notification request to a message queue. When a message is received by an |
---|
109 | empty queue, if there are no processes blocked and waiting for the |
---|
110 | message, then the queue notifies the requesting process of a message |
---|
111 | arrival. There is only one signal sent by the message queue, after that |
---|
112 | the notification request is de-registered and another process can attach |
---|
113 | its notification request. After receipt of a notification, a process must |
---|
114 | re-register if it wishes to be notified again. |
---|
115 | |
---|
116 | If there is a process blocked and waiting for the message, that process |
---|
117 | gets the message, and notification is not sent. It is also possible for |
---|
118 | another process to receive the message after the notification is sent but |
---|
119 | before the notified process has sent its receive request. |
---|
120 | |
---|
121 | Only one process can have a notification request attached to a message |
---|
122 | queue at any one time. If another process attempts to register a |
---|
123 | notification request, it fails. You can de-register for a message queue |
---|
124 | by passing a NULL to mq_notify, this removes any notification request |
---|
125 | attached to the queue. Whenever the message queue is closed, all |
---|
126 | notification attachments are removed. |
---|
127 | |
---|
128 | @subsection POSIX Interpretation Issues |
---|
129 | |
---|
130 | There is one significant point of interpretation related to |
---|
131 | the RTEMS implementation of POSIX message queues: |
---|
132 | |
---|
133 | @cite{What happens to threads already blocked on a message queue when the |
---|
134 | mode of that same message queue is changed from blocking to non-blocking?} |
---|
135 | |
---|
136 | |
---|
137 | The RTEMS POSIX implementation decided to unblock all waiting tasks |
---|
138 | with an @code{EAGAIN} status just as if a non-blocking version of |
---|
139 | the same operation had returned unsatisfied. This case is not |
---|
140 | discussed in the POSIX standard and other implementations may have |
---|
141 | chosen alternative behaviors. |
---|
142 | |
---|
143 | @section Operations |
---|
144 | |
---|
145 | @subsection Opening or Creating a Message Queue |
---|
146 | |
---|
147 | If the message queue already exists, mq_open() opens it, if the message |
---|
148 | queue does not exist, mq_open() creates it. When a message queue is |
---|
149 | created, the geometry of the message queue is contained in the attribute |
---|
150 | structure that is passed in as an argument. This includes mq_msgsize that |
---|
151 | dictates the maximum size of a single message, and the mq_maxmsg that |
---|
152 | dictates the maximum number of messages the queue can hold at one time. |
---|
153 | The blocking or non-blocking behavior of the queue can also specified. |
---|
154 | |
---|
155 | @subsection Closing a Message Queue |
---|
156 | |
---|
157 | The mq_close() function is used to close the connection made to a message |
---|
158 | queue that was made during mq_open. The message queue itself and the |
---|
159 | messages on the queue are persistent and remain after the queue is closed. |
---|
160 | |
---|
161 | @subsection Removing a Message Queue |
---|
162 | |
---|
163 | The mq_unlink() function removes the named message queue. If the message |
---|
164 | queue is not open when mq_unlink is called, then the queue is immediately |
---|
165 | eliminated. Any messages that were on the queue are lost, and the queue |
---|
166 | can not be opened again. If processes have the queue open when mq_unlink |
---|
167 | is called, the removal of the queue is delayed until the last process |
---|
168 | using the queue has finished. However, the name of the message queue is |
---|
169 | removed so that no other process can open it. |
---|
170 | |
---|
171 | @subsection Sending a Message to a Message Queue |
---|
172 | |
---|
173 | The mq_send() function adds the message in priority order to the message |
---|
174 | queue. Each message has an assigned a priority. The highest priority |
---|
175 | message is be at the front of the queue. |
---|
176 | |
---|
177 | The maximum number of messages that a message queue may accept is |
---|
178 | specified at creation by the mq_maxmsg field of the attribute structure. |
---|
179 | If this amount is exceeded, the behavior of the process is determined |
---|
180 | according to what oflag was used when the message queue was opened. If |
---|
181 | the queue was opened with O_NONBLOCK flag set, the process does not block, |
---|
182 | and an error is returned. If the O_NONBLOCK flag was not set, the process |
---|
183 | does block and wait for space on the queue. |
---|
184 | |
---|
185 | @subsection Receiving a Message from a Message Queue |
---|
186 | |
---|
187 | The mq_receive() function is used to receive the oldest of the highest |
---|
188 | priority message(s) from the message queue specified by mqdes. The |
---|
189 | messages are received in FIFO order within the priorities. The received |
---|
190 | message's priority is stored in the location referenced by the msg_prio. |
---|
191 | If the msg_prio is a NULL, the priority is discarded. The message is |
---|
192 | removed and stored in an area pointed to by msg_ptr whose length is of |
---|
193 | msg_len. The msg_len must be at least equal to the mq_msgsize attribute |
---|
194 | of the message queue. |
---|
195 | |
---|
196 | The blocking behavior of the message queue is set by O_NONBLOCK at mq_open |
---|
197 | or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is |
---|
198 | a blocking queue, the process does block and wait on an empty queue. If |
---|
199 | this a non-blocking queue, the process does not block. Upon successful |
---|
200 | completion, mq_receive returns the length of the selected message in bytes |
---|
201 | and the message is removed from the queue. |
---|
202 | |
---|
203 | @subsection Notification of Receipt of a Message on an Empty Queue |
---|
204 | |
---|
205 | The mq_notify() function registers the calling process to be notified of |
---|
206 | message arrival at an empty message queue. Every message queue has the |
---|
207 | ability to notify one (and only one) process whenever the queue's state |
---|
208 | changes from empty (0 messages) to nonempty. This means that the process |
---|
209 | does not have to block or constantly poll while it waits for a message. |
---|
210 | By calling mq_notify, a notification request is attached to a message |
---|
211 | queue. When a message is received by an empty queue, if there are no |
---|
212 | processes blocked and waiting for the message, then the queue notifies the |
---|
213 | requesting process of a message arrival. There is only one signal sent by |
---|
214 | the message queue, after that the notification request is de-registered |
---|
215 | and another process can attach its notification request. After receipt of |
---|
216 | a notification, a process must re-register if it wishes to be notified |
---|
217 | again. |
---|
218 | |
---|
219 | If there is a process blocked and waiting for the message, that process |
---|
220 | gets the message, and notification is not sent. Only one process can have |
---|
221 | a notification request attached to a message queue at any one time. If |
---|
222 | another process attempts to register a notification request, it fails. |
---|
223 | You can de-register for a message queue by passing a NULL to mq_notify, |
---|
224 | this removes any notification request attached to the queue. Whenever the |
---|
225 | message queue is closed, all notification attachments are removed. |
---|
226 | |
---|
227 | @subsection Setting the Attributes of a Message Queue |
---|
228 | |
---|
229 | The mq_setattr() function is used to set attributes associated with the |
---|
230 | open message queue description referenced by the message queue descriptor |
---|
231 | specified by mqdes. The *omqstat represents the old or previous |
---|
232 | attributes. If omqstat is non-NULL, the function mq_setattr() stores, in |
---|
233 | the location referenced by omqstat, the previous message queue attributes |
---|
234 | and the current queue status. These values are the same as would be |
---|
235 | returned by a call to mq_getattr() at that point. |
---|
236 | |
---|
237 | There is only one mq_attr.mq_flag that can be altered by this call. This |
---|
238 | is the flag that deals with the blocking and non-blocking behavior of the |
---|
239 | message queue. If the flag is set then the message queue is non-blocking, |
---|
240 | and requests to send or receive do not block while waiting for resources. |
---|
241 | If the flag is not set, then message send and receive may involve waiting |
---|
242 | for an empty queue or waiting for a message to arrive. |
---|
243 | |
---|
244 | @subsection Getting the Attributes of a Message Queue |
---|
245 | |
---|
246 | The mq_getattr() function is used to get status information and attributes |
---|
247 | of the message queue associated with the message queue descriptor. The |
---|
248 | results are returned in the mq_attr structure referenced by the mqstat |
---|
249 | argument. All of these attributes are set at create time, except the |
---|
250 | blocking/non-blocking behavior of the message queue which can be |
---|
251 | dynamically set by using mq_setattr. The attribute mq_curmsg is set to |
---|
252 | reflect the number of messages on the queue at the time that mq_getattr |
---|
253 | was called. |
---|
254 | |
---|
255 | @section Directives |
---|
256 | |
---|
257 | This section details the message passing manager's directives. A |
---|
258 | subsection is dedicated to each of this manager's directives and describes |
---|
259 | the calling sequence, related constants, usage, and status codes. |
---|
260 | |
---|
261 | @c |
---|
262 | @c |
---|
263 | @c |
---|
264 | @page |
---|
265 | @subsection mq_open - Open a Message Queue |
---|
266 | |
---|
267 | @findex mq_open |
---|
268 | @cindex open a message queue |
---|
269 | |
---|
270 | @subheading CALLING SEQUENCE: |
---|
271 | |
---|
272 | @example |
---|
273 | #include <mqueue.h> |
---|
274 | |
---|
275 | mqd_t mq_open( |
---|
276 | const char *name, |
---|
277 | int oflag, |
---|
278 | mode_t mode, |
---|
279 | struct mq_attr *attr |
---|
280 | ); |
---|
281 | @end example |
---|
282 | |
---|
283 | @subheading STATUS CODES: |
---|
284 | |
---|
285 | @code{EACCES} - Either the message queue exists and the permissions |
---|
286 | requested in oflags were denied, or the message does not exist and |
---|
287 | permission to create one is denied. |
---|
288 | |
---|
289 | @code{EEXIST} - You tried to create a message queue that already exists. |
---|
290 | |
---|
291 | @code{EINVAL} - An inappropriate name was given for the message queue, or |
---|
292 | the values of mq-maxmsg or mq_msgsize were less than 0. |
---|
293 | |
---|
294 | @code{ENOENT} - The message queue does not exist, and you did not specify |
---|
295 | to create it. |
---|
296 | |
---|
297 | @code{EINTR} - The call to mq_open was interrupted by a signal. |
---|
298 | |
---|
299 | @code{EMFILE} - The process has too many files or message queues open. |
---|
300 | This is a process limit error. |
---|
301 | |
---|
302 | @code{ENFILE} - The system has run out of resources to support more open |
---|
303 | message queues. This is a system error. |
---|
304 | |
---|
305 | @code{ENAMETOOLONG} - mq_name is too long. |
---|
306 | |
---|
307 | @subheading DESCRIPTION: |
---|
308 | |
---|
309 | The mq_open () function establishes the connection between a process and a |
---|
310 | message queue with a message queue descriptor. If the message queue |
---|
311 | already exists, mq_open opens it, if the message queue does not exist, |
---|
312 | mq_open creates it. Message queues can have multiple senders and |
---|
313 | receivers. If mq_open is successful, the function returns a message queue |
---|
314 | descriptor. Otherwise, the function returns a -1 and sets 'errno' to |
---|
315 | indicate the error. |
---|
316 | |
---|
317 | The name of the message queue is used as an argument. For the best of |
---|
318 | portability, the name of the message queue should begin with a "/" and no |
---|
319 | other "/" should be in the name. Different systems interpret the name in |
---|
320 | different ways. |
---|
321 | |
---|
322 | The oflags contain information on how the message is opened if the queue |
---|
323 | already exists. This may be O_RDONLY for read only, O_WRONLY for write |
---|
324 | only, of O_RDWR, for read and write. |
---|
325 | |
---|
326 | In addition, the oflags contain information needed in the creation of a |
---|
327 | message queue. @code{O_NONBLOCK} - If the non-block flag is set then the |
---|
328 | message queue is non-blocking, and requests to send and receive messages |
---|
329 | do not block waiting for resources. If the flag is not set then the |
---|
330 | message queue is blocking, and a request to send might have to wait for an |
---|
331 | empty message queue. Similarly, a request to receive might have to wait |
---|
332 | for a message to arrive on the queue. @code{O_CREAT} - This call specifies |
---|
333 | that the call the mq_open is to create a new message queue. In this case |
---|
334 | the mode and attribute arguments of the function call are utilized. The |
---|
335 | message queue is created with a mode similar to the creation of a file, |
---|
336 | read and write permission creator, group, and others. |
---|
337 | |
---|
338 | The geometry of the message queue is contained in the attribute structure. |
---|
339 | This includes mq_msgsize that dictates the maximum size of a single |
---|
340 | message, and the mq_maxmsg that dictates the maximum number of messages |
---|
341 | the queue can hold at one time. If a NULL is used in the mq_attr |
---|
342 | argument, then the message queue is created with implementation defined |
---|
343 | defaults. @code{O_EXCL} - is always set if O_CREAT flag is set. If the |
---|
344 | message queue already exists, O_EXCL causes an error message to be |
---|
345 | returned, otherwise, the new message queue fails and appends to the |
---|
346 | existing one. |
---|
347 | |
---|
348 | @subheading NOTES: |
---|
349 | |
---|
350 | The mq_open () function does not add or remove messages from the queue. |
---|
351 | When a new message queue is being created, the mq_flag field of the |
---|
352 | attribute structure is not used. |
---|
353 | |
---|
354 | @c |
---|
355 | @c |
---|
356 | @c |
---|
357 | @page |
---|
358 | @subsection mq_close - Close a Message Queue |
---|
359 | |
---|
360 | @findex mq_close |
---|
361 | @cindex close a message queue |
---|
362 | |
---|
363 | @subheading CALLING SEQUENCE: |
---|
364 | |
---|
365 | @example |
---|
366 | #include <mqueue.h> |
---|
367 | |
---|
368 | int mq_close( |
---|
369 | mqd_t mqdes |
---|
370 | ); |
---|
371 | @end example |
---|
372 | |
---|
373 | @subheading STATUS CODES: |
---|
374 | |
---|
375 | @code{EINVAL} - The descriptor does not represent a valid open message |
---|
376 | queue |
---|
377 | |
---|
378 | @subheading DESCRIPTION: |
---|
379 | |
---|
380 | The mq_close function removes the association between the message queue |
---|
381 | descriptor, mqdes, and its message queue. If mq_close() is successfully |
---|
382 | completed, the function returns a value of zero; otherwise, the function |
---|
383 | returns a value of -1 and sets errno to indicate the error. |
---|
384 | |
---|
385 | @subheading NOTES: |
---|
386 | |
---|
387 | If the process had successfully attached a notification request to the |
---|
388 | message queue via mq_notify, this attachment is removed, and the message |
---|
389 | queue is available for another process to attach for notification. |
---|
390 | mq_close has no effect on the contents of the message queue, all the |
---|
391 | messages that were in the queue remain in the queue. |
---|
392 | |
---|
393 | @c |
---|
394 | @c |
---|
395 | @c |
---|
396 | @page |
---|
397 | @subsection mq_unlink - Remove a Message Queue |
---|
398 | |
---|
399 | @findex mq_unlink |
---|
400 | @cindex remove a message queue |
---|
401 | |
---|
402 | @subheading CALLING SEQUENCE: |
---|
403 | |
---|
404 | @example |
---|
405 | #include <mqueue.h> |
---|
406 | |
---|
407 | int mq_unlink( |
---|
408 | const char *name |
---|
409 | ); |
---|
410 | @end example |
---|
411 | |
---|
412 | @subheading STATUS CODES: |
---|
413 | |
---|
414 | @code{EINVAL} - The descriptor does not represent a valid message queue |
---|
415 | |
---|
416 | @subheading DESCRIPTION: |
---|
417 | |
---|
418 | The mq_unlink() function removes the named message queue. If the message |
---|
419 | queue is not open when mq_unlink is called, then the queue is immediately |
---|
420 | eliminated. Any messages that were on the queue are lost, and the queue |
---|
421 | can not be opened again. If processes have the queue open when mq_unlink |
---|
422 | is called, the removal of the queue is delayed until the last process |
---|
423 | using the queue has finished. However, the name of the message queue is |
---|
424 | removed so that no other process can open it. Upon successful completion, |
---|
425 | the function returns a value of zero. Otherwise, the named message queue |
---|
426 | is not changed by this function call, and the function returns a value of |
---|
427 | -1 and sets errno to indicate the error. |
---|
428 | |
---|
429 | @subheading NOTES: |
---|
430 | |
---|
431 | Calls to mq_open() to re-create the message queue may fail until the |
---|
432 | message queue is actually removed. However, the mq_unlink() call need not |
---|
433 | block until all references have been closed; it may return immediately. |
---|
434 | |
---|
435 | @c |
---|
436 | @c |
---|
437 | @c |
---|
438 | @page |
---|
439 | @subsection mq_send - Send a Message to a Message Queue |
---|
440 | |
---|
441 | @findex mq_send |
---|
442 | @cindex send a message to a message queue |
---|
443 | |
---|
444 | @subheading CALLING SEQUENCE: |
---|
445 | |
---|
446 | @example |
---|
447 | #include<mqueue.h> |
---|
448 | int mq_send( |
---|
449 | mqd_t mqdes, |
---|
450 | const char *msg_ptr, |
---|
451 | size_t msg_len, |
---|
452 | unsigned int msg_prio |
---|
453 | ); |
---|
454 | @end example |
---|
455 | |
---|
456 | @subheading STATUS CODES: |
---|
457 | |
---|
458 | @code{EBADF} - The descriptor does not represent a valid message queue, or the queue was opened for read only O_RDONLY |
---|
459 | @code{EINVAL} - The value of msg_prio was greater than the MQ_PRIO_MAX. |
---|
460 | @code{EMSGSIZE} - The msg_len is greater than the mq_msgsize attribute of the message queue |
---|
461 | @code{EAGAIN} - The message queue is non-blocking, and there is no room on the queue for another message as specified by the mq_maxmsg. |
---|
462 | @code{EINTR} - The message queue is blocking. While the process was waiting for free space on the queue, a signal arrived that interrupted the wait. |
---|
463 | |
---|
464 | @subheading DESCRIPTION: |
---|
465 | |
---|
466 | The mq_send() function adds the message pointed to by the argument msg_ptr |
---|
467 | to the message queue specified by mqdes. Each message is assigned a |
---|
468 | priority , from 0 to MQ_PRIO_MAX. MQ_PRIO_MAX is defined in <limits.h> and |
---|
469 | must be at least 32. Messages are added to the queue in order of their |
---|
470 | priority. The highest priority message is at the front of the queue. |
---|
471 | |
---|
472 | The maximum number of messages that a message queue may accept is |
---|
473 | specified at creation by the mq_maxmsg field of the attribute structure. |
---|
474 | If this amount is exceeded, the behavior of the process is determined |
---|
475 | according to what oflag was used when the message queue was opened. If |
---|
476 | the queue was opened with O_NONBLOCK flag set, then the EAGAIN error is |
---|
477 | returned. If the O_NONBLOCK flag was not set, the process blocks and |
---|
478 | waits for space on the queue, unless it is interrupted by a signal. |
---|
479 | |
---|
480 | Upon successful completion, the mq_send () function returns a value of |
---|
481 | zero. Otherwise, no message is enqueued, the function returns -1, and |
---|
482 | errno is set to indicate the error. |
---|
483 | |
---|
484 | @subheading NOTES: |
---|
485 | |
---|
486 | If the specified message queue is not full, mq_send inserts the message at |
---|
487 | the position indicated by the msg_prio argument. |
---|
488 | |
---|
489 | @c |
---|
490 | @c |
---|
491 | @c |
---|
492 | @page |
---|
493 | @subsection mq_receive - Receive a Message from a Message Queue |
---|
494 | |
---|
495 | @findex mq_receive |
---|
496 | @cindex receive a message from a message queue |
---|
497 | |
---|
498 | @subheading CALLING SEQUENCE: |
---|
499 | |
---|
500 | @example |
---|
501 | #include <mqueue.h> |
---|
502 | |
---|
503 | size_t mq_receive( |
---|
504 | mqd_t mqdes, |
---|
505 | char *msg_ptr, |
---|
506 | size_t msg_len, |
---|
507 | unsigned int *msg_prio |
---|
508 | ); |
---|
509 | @end example |
---|
510 | |
---|
511 | @subheading STATUS CODES: |
---|
512 | |
---|
513 | @code{EBADF} - The descriptor does not represent a valid message queue, or the queue was opened for write only O_WRONLY |
---|
514 | @code{EMSGSIZE} - The msg_len is less than the mq_msgsize attribute of the message queue |
---|
515 | @code{EAGAIN} - The message queue is non-blocking, and the queue is empty |
---|
516 | @code{EINTR} - The message queue is blocking. While the process was waiting for a message to arrive on the queue, a signal arrived that interrupted the wait. |
---|
517 | |
---|
518 | @subheading DESCRIPTION: |
---|
519 | |
---|
520 | The mq_receive function is used to receive the oldest of the highest |
---|
521 | priority message(s) from the message queue specified by mqdes. The |
---|
522 | messages are received in FIFO order within the priorities. The received |
---|
523 | message's priority is stored in the location referenced by the msg_prio. |
---|
524 | If the msg_prio is a NULL, the priority is discarded. The message is |
---|
525 | removed and stored in an area pointed to by msg_ptr whose length is of |
---|
526 | msg_len. The msg_len must be at least equal to the mq_msgsize attribute |
---|
527 | of the message queue. |
---|
528 | |
---|
529 | The blocking behavior of the message queue is set by O_NONBLOCK at mq_open |
---|
530 | or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is |
---|
531 | a blocking queue, the process blocks and waits on an empty queue. If this |
---|
532 | a non-blocking queue, the process does not block. |
---|
533 | |
---|
534 | Upon successful completion, mq_receive returns the length of the selected |
---|
535 | message in bytes and the message is removed from the queue. Otherwise, no |
---|
536 | message is removed from the queue, the function returns a value of -1, and |
---|
537 | sets errno to indicate the error. |
---|
538 | |
---|
539 | @subheading NOTES: |
---|
540 | |
---|
541 | If the size of the buffer in bytes, specified by the msg_len argument, is |
---|
542 | less than the mq_msgsize attribute of the message queue, the function |
---|
543 | fails and returns an error |
---|
544 | |
---|
545 | @c |
---|
546 | @c |
---|
547 | @c |
---|
548 | @page |
---|
549 | @subsection mq_notify - Notify Process that a Message is Available |
---|
550 | |
---|
551 | @findex mq_notify |
---|
552 | @cindex notify process that a message is available |
---|
553 | |
---|
554 | @subheading CALLING SEQUENCE: |
---|
555 | |
---|
556 | @example |
---|
557 | #include <mqueue.h> |
---|
558 | |
---|
559 | int mq_notify( |
---|
560 | mqd_t mqdes, |
---|
561 | const struct sigevent *notification |
---|
562 | ); |
---|
563 | @end example |
---|
564 | |
---|
565 | @subheading STATUS CODES: |
---|
566 | |
---|
567 | @code{EBADF} - The descriptor does not refer to a valid message queue |
---|
568 | @code{EBUSY} - A notification request is already attached to the queue |
---|
569 | |
---|
570 | @subheading DESCRIPTION: |
---|
571 | |
---|
572 | If the argument notification is not NULL, this function registers the |
---|
573 | calling process to be notified of message arrival at an empty message |
---|
574 | queue associated with the specified message queue descriptor, mqdes. |
---|
575 | |
---|
576 | Every message queue has the ability to notify one (and only one) process |
---|
577 | whenever the queue's state changes from empty (0 messages) to nonempty. |
---|
578 | This means that the process does not have to block or constantly poll |
---|
579 | while it waits for a message. By calling mq_notify, a notification |
---|
580 | request is attached to a message queue. When a message is received by an |
---|
581 | empty queue, if there are no processes blocked and waiting for the |
---|
582 | message, then the queue notifies the requesting process of a message |
---|
583 | arrival. There is only one signal sent by the message queue, after that |
---|
584 | the notification request is de-registered and another process can attach |
---|
585 | its notification request. After receipt of a notification, a process must |
---|
586 | re-register if it wishes to be notified again. |
---|
587 | |
---|
588 | If there is a process blocked and waiting for the message, that process |
---|
589 | gets the message, and notification is not be sent. Only one process can |
---|
590 | have a notification request attached to a message queue at any one time. |
---|
591 | If another process attempts to register a notification request, it fails. |
---|
592 | You can de-register for a message queue by passing a NULL to mq_notify; |
---|
593 | this removes any notification request attached to the queue. Whenever the |
---|
594 | message queue is closed, all notification attachments are removed. |
---|
595 | |
---|
596 | Upon successful completion, mq_notify returns a value of zero; otherwise, |
---|
597 | the function returns a value of -1 and sets errno to indicate the error. |
---|
598 | |
---|
599 | @subheading NOTES: |
---|
600 | |
---|
601 | It is possible for another process to receive the message after the notification is sent but before the notified process has sent its receive request. |
---|
602 | |
---|
603 | @c |
---|
604 | @c |
---|
605 | @c |
---|
606 | @page |
---|
607 | @subsection mq_setattr - Set Message Queue Attributes |
---|
608 | |
---|
609 | @findex mq_setattr |
---|
610 | @cindex set message queue attributes |
---|
611 | |
---|
612 | @subheading CALLING SEQUENCE: |
---|
613 | |
---|
614 | @example |
---|
615 | #include <mqueue.h> |
---|
616 | |
---|
617 | int mq_setattr( |
---|
618 | mqd_t mqdes, |
---|
619 | const struct mq_attr *mqstat, |
---|
620 | struct mq_attr *omqstat |
---|
621 | ); |
---|
622 | @end example |
---|
623 | |
---|
624 | @subheading STATUS CODES: |
---|
625 | |
---|
626 | @code{EBADF} - The message queue descriptor does not refer to a valid, open queue. |
---|
627 | @code{EINVAL} - The mq_flag value is invalid. |
---|
628 | |
---|
629 | @subheading DESCRIPTION: |
---|
630 | |
---|
631 | The mq_setattr function is used to set attributes associated with the open |
---|
632 | message queue description referenced by the message queue descriptor |
---|
633 | specified by mqdes. The *omqstat represents the old or previous |
---|
634 | attributes. If omqstat is non-NULL, the function mq_setattr() stores, in |
---|
635 | the location referenced by omqstat, the previous message queue attributes |
---|
636 | and the current queue status. These values are the same as would be |
---|
637 | returned by a call to mq_getattr() at that point. |
---|
638 | |
---|
639 | There is only one mq_attr.mq_flag which can be altered by this call. |
---|
640 | This is the flag that deals with the blocking and non-blocking behavior of |
---|
641 | the message queue. If the flag is set then the message queue is |
---|
642 | non-blocking, and requests to send or receive do not block while waiting |
---|
643 | for resources. If the flag is not set, then message send and receive may |
---|
644 | involve waiting for an empty queue or waiting for a message to arrive. |
---|
645 | |
---|
646 | Upon successful completion, the function returns a value of zero and the |
---|
647 | attributes of the message queue have been changed as specified. |
---|
648 | Otherwise, the message queue attributes is unchanged, and the function |
---|
649 | returns a value of -1 and sets errno to indicate the error. |
---|
650 | |
---|
651 | @subheading NOTES: |
---|
652 | |
---|
653 | All other fields in the mq_attr are ignored by this call. |
---|
654 | |
---|
655 | @c |
---|
656 | @c |
---|
657 | @c |
---|
658 | @page |
---|
659 | @subsection mq_getattr - Get Message Queue Attributes |
---|
660 | |
---|
661 | @findex mq_getattr |
---|
662 | @cindex get message queue attributes |
---|
663 | |
---|
664 | @subheading CALLING SEQUENCE: |
---|
665 | |
---|
666 | @example |
---|
667 | #include <mqueue.h> |
---|
668 | int mq_getattr( |
---|
669 | mqd_t mqdes, |
---|
670 | struct mq_attr *mqstat |
---|
671 | ); |
---|
672 | @end example |
---|
673 | |
---|
674 | @subheading STATUS CODES: |
---|
675 | |
---|
676 | @code{EBADF} - The message queue descriptor does not refer to a valid, |
---|
677 | open message queue. |
---|
678 | |
---|
679 | @subheading DESCRIPTION: |
---|
680 | |
---|
681 | The mqdes argument specifies a message queue descriptor. The mq_getattr |
---|
682 | function is used to get status information and attributes of the message |
---|
683 | queue associated with the message queue descriptor. The results are |
---|
684 | returned in the mq_attr structure referenced by the mqstat argument. All |
---|
685 | of these attributes are set at create time, except the |
---|
686 | blocking/non-blocking behavior of the message queue which can be |
---|
687 | dynamically set by using mq_setattr. The attribute mq_curmsg is set to |
---|
688 | reflect the number of messages on the queue at the time that mq_getattr |
---|
689 | was called. |
---|
690 | |
---|
691 | Upon successful completion, the mq_getattr function returns zero. |
---|
692 | Otherwise, the function returns -1 and sets errno to indicate the error. |
---|
693 | |
---|
694 | @subheading NOTES: |
---|
695 | |
---|