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