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