source: rtems/doc/posix_users/message.t @ d2bfbaf

4.104.114.84.95
Last change on this file since d2bfbaf was d2bfbaf, checked in by Joel Sherrill <joel.sherrill@…>, on 11/16/99 at 21:56:45

Fixed spacing.

  • Property mode set to 100644
File size: 26.2 KB
Line 
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
13The message passing manager is the means to provide communication and
14synchronization capabilities using POSIX message queues.
15
16The 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
33Message queues are named objects that operate with readers and writers.
34In addition, a message queue is a priority queue of discrete messages.
35POSIX message queues offer a certain, basic amount of application access
36to, and control over, the message queue geometry that can be changed.
37
38@subsection Messages
39
40A message is a variable length buffer where information can be stored to
41support communication. The length of the message and the information
42stored in that message are user-defined and can be actual data,
43pointer(s), or empty. There is a maximum acceptable length for a message
44that is associated with each message queue.
45
46@subsection Message Queues
47
48Message queues are named objects similar to the pipes of POSIX. They are
49a means of communicating data between multiple processes and for passing
50messages among tasks and ISRs. Message queues can contain a variable
51number of messages from 0 to an upper limit that is user defined. The
52maximum length of the message can be set on a per message queue basis.
53Normally messages are sent and received from the message queue in FIFO
54order. However, messages can also be prioritized and a priority queue
55established for the passing of messages. Synchronization is needed when a
56task waits for a message to arrive at a queue. Also, a task may poll a
57queue for the arrival of a message.
58
59The message queue descriptor mqd_t mq represents the message queue. It is
60passed as an argument to all of the message queue functions.
61
62@subsection Building a Message Queue Attribute Set
63
64The mq_attr structure is used to define the characteristics of the message
65queue.
66
67@example
68@group
69typedef 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
78All of these attributes are set when the message queue is created using
79mq_open. The mq_flags field is not used in the creation of a message
80queue, it is only used by mq_setattr and mq_getattr. The structure
81mq_attr is passed as an argument to mq_setattr and mq_getattr.
82
83The mq_flags contain information affecting the behavior of the message
84queue. The O_NONBLOCK mq_flag is the only flag that is defined. In
85mq_setattr, the mq_flag can be set to dynamically change the blocking and
86non-blocking behavior of the message queue. If the non-block flag is set
87then the message queue is non-blocking, and requests to send and receive
88messages do not block waiting for resources. For a blocking message
89queue, a request to send might have to wait for an empty message queue,
90and a request to receive might have to wait for a message to arrive on the
91queue. Both mq_maxmsg and mq_msgsize affect the sizing of the message
92queue. mq_maxmsg specifies how many messages the queue can hold at any
93one time. mq_msgsize specifies the size of any one message on the queue.
94If either of these limits is exceeded, an error message results.
95
96Upon return from mq_getattr, the mq_curmsgs is set according to the
97current state of the message queue. This specifies the number of messages
98currently on the queue.
99
100@subsection Notification of a Message on the Queue
101
102Every message queue has the ability to notify one (and only one) process
103whenever the queue's state changes from empty (0 messages) to nonempty.
104This means that the process does not have to block or constantly poll
105while it waits for a message. By calling mq_notify, you can attach a
106notification request to a message queue. When a message is received by an
107empty queue, if there are no processes blocked and waiting for the
108message, then the queue notifies the requesting process of a message
109arrival. There is only one signal sent by the message queue, after that
110the notification request is de-registered and another process can attach
111its notification request. After receipt of a notification, a process must
112re-register if it wishes to be notified again.
113
114If there is a process blocked and waiting for the message, that process
115gets the message, and notification is not sent. It is also possible for
116another process to receive the message after the notification is sent but
117before the notified process has sent its receive request.
118
119Only one process can have a notification request attached to a message
120queue at any one time. If another process attempts to register a
121notification request, it fails. You can de-register for a message queue
122by passing a NULL to mq_notify, this removes any notification request
123attached to the queue. Whenever the message queue is closed, all
124notification attachments are removed.
125
126@section Operations
127
128@subsection Opening or Creating a Message Queue
129
130If the message queue already exists, mq_open() opens it, if the message
131queue does not exist, mq_open() creates it. When a message queue is
132created, the geometry of the message queue is contained in the attribute
133structure that is passed in as an argument. This includes mq_msgsize that
134dictates the maximum size of a single message, and the mq_maxmsg that
135dictates the maximum number of messages the queue can hold at one time.
136The blocking or non-blocking behavior of the queue can also specified.
137
138@subsection Closing a Message Queue
139
140The mq_close() function is used to close the connection made to a message
141queue that was made during mq_open. The message queue itself and the
142messages on the queue are persistent and remain after the queue is closed.
143
144@subsection Removing a Message Queue
145
146The mq_unlink() function removes the named message queue. If the message
147queue is not open when mq_unlink is called, then the queue is immediately
148eliminated. Any messages that were on the queue are lost, and the queue
149can not be opened again. If processes have the queue open when mq_unlink
150is called, the removal of the queue is delayed until the last process
151using the queue has finished. However, the name of the message queue is
152removed so that no other process can open it.
153
154@subsection Sending a Message to a Message Queue
155
156The mq_send() function adds the message in priority order to the message
157queue. Each message has an assigned a priority. The highest priority
158message is be at the front of the queue.
159
160The maximum number of messages that a message queue may accept is
161specified at creation by the mq_maxmsg field of the attribute structure.
162If this amount is exceeded, the behavior of the process is determined
163according to what oflag was used when the message queue was opened. If
164the queue was opened with O_NONBLOCK flag set, the process does not block,
165and an error is returned. If the O_NONBLOCK flag was not set, the process
166does block and wait for space on the queue.
167
168@subsection Receiving a Message from a Message Queue
169
170The mq_receive() function is used to receive the oldest of the highest
171priority message(s) from the message queue specified by mqdes. The
172messages are received in FIFO order within the priorities. The received
173message's priority is stored in the location referenced by the msg_prio.
174If the msg_prio is a NULL, the priority is discarded. The message is
175removed and stored in an area pointed to by msg_ptr whose length is of
176msg_len. The msg_len must be at least equal to the mq_msgsize attribute
177of the message queue.
178
179The blocking behavior of the message queue is set by O_NONBLOCK at mq_open
180or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is
181a blocking queue, the process does block and wait on an empty queue. If
182this a non-blocking queue, the process does not block. Upon successful
183completion, mq_receive returns the length of the selected message in bytes
184and the message is removed from the queue.
185
186@subsection Notification of Receipt of a Message on an Empty Queue
187
188The mq_notify() function registers the calling process to be notified of
189message arrival at an empty message queue. Every message queue has the
190ability to notify one (and only one) process whenever the queue's state
191changes from empty (0 messages) to nonempty. This means that the process
192does not have to block or constantly poll while it waits for a message.
193By calling mq_notify, a notification request is attached to a message
194queue. When a message is received by an empty queue, if there are no
195processes blocked and waiting for the message, then the queue notifies the
196requesting process of a message arrival. There is only one signal sent by
197the message queue, after that the notification request is de-registered
198and another process can attach its notification request. After receipt of
199a notification, a process must re-register if it wishes to be notified
200again.
201
202If there is a process blocked and waiting for the message, that process
203gets the message, and notification is not sent. Only one process can have
204a notification request attached to a message queue at any one time. If
205another process attempts to register a notification request, it fails.
206You can de-register for a message queue by passing a NULL to mq_notify,
207this removes any notification request attached to the queue. Whenever the
208message queue is closed, all notification attachments are removed.
209
210@subsection Setting the Attributes of a Message Queue
211
212The mq_setattr() function is used to set attributes associated with the
213open message queue description referenced by the message queue descriptor
214specified by mqdes. The *omqstat represents the old or previous
215attributes. If omqstat is non-NULL, the function mq_setattr() stores, in
216the location referenced by omqstat, the previous message queue attributes
217and the current queue status. These values are the same as would be
218returned by a call to mq_getattr() at that point.
219
220There is only one mq_attr.mq_flag that can be altered by this call. This
221is the flag that deals with the blocking and non-blocking behavior of the
222message queue. If the flag is set then the message queue is non-blocking,
223and requests to send or receive do not block while waiting for resources.
224If the flag is not set, then message send and receive may involve waiting
225for an empty queue or waiting for a message to arrive.
226
227@subsection Getting the Attributes of a Message Queue
228
229The mq_getattr() function is used to get status information and attributes
230of the message queue associated with the message queue descriptor. The
231results are returned in the mq_attr structure referenced by the mqstat
232argument. All of these attributes are set at create time, except the
233blocking/non-blocking behavior of the message queue which can be
234dynamically set by using mq_setattr. The attribute mq_curmsg is set to
235reflect the number of messages on the queue at the time that mq_getattr
236was called.
237
238@section Directives
239
240This section details the message passing manager's directives. A
241subsection is dedicated to each of this manager's directives and describes
242the 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
258mqd_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
269requested in oflags were denied, or the message does not exist and
270permission 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
275the 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
278to 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.
283This is a process limit error.
284
285@code{ENFILE} - The system has run out of resources to support more open
286message queues. This is a system error.
287
288@code{ENAMETOOLONG} - mq_name is too long.
289
290@subheading DESCRIPTION:
291
292The mq_open () function establishes the connection between a process and a
293message queue with a message queue descriptor. If the message queue
294already exists, mq_open opens it, if the message queue does not exist,
295mq_open creates it. Message queues can have multiple senders and
296receivers. If mq_open is successful, the function returns a message queue
297descriptor. Otherwise, the function returns a -1 and sets 'errno' to
298indicate the error.
299
300The name of the message queue is used as an argument. For the best of
301portability, the name of the message queue should begin with a "/" and no
302other "/" should be in the name. Different systems interpret the name in
303different ways.
304
305The oflags contain information on how the message is opened if the queue
306already exists. This may be O_RDONLY for read only, O_WRONLY for write
307only, of O_RDWR, for read and write.
308
309In addition, the oflags contain information needed in the creation of a
310message queue. @code{O_NONBLOCK} - If the non-block flag is set then the
311message queue is non-blocking, and requests to send and receive messages
312do not block waiting for resources. If the flag is not set then the
313message queue is blocking, and a request to send might have to wait for an
314empty message queue. Similarly, a request to receive might have to wait
315for a message to arrive on the queue. @code{O_CREAT} - This call specifies
316that the call the mq_open is to create a new message queue. In this case
317the mode and attribute arguments of the function call are utilized. The
318message queue is created with a mode similar to the creation of a file,
319read and write permission creator, group, and others.
320
321The geometry of the message queue is contained in the attribute structure.
322This includes mq_msgsize that dictates the maximum size of a single
323message, and the mq_maxmsg that dictates the maximum number of messages
324the queue can hold at one time. If a NULL is used in the mq_attr
325argument, then the message queue is created with implementation defined
326defaults. @code{O_EXCL} - is always set if O_CREAT flag is set. If the
327message queue already exists, O_EXCL causes an error message to be
328returned, otherwise, the new message queue fails and appends to the
329existing one.
330
331@subheading NOTES:
332
333The mq_open () function does not add or remove messages from the queue.
334When a new message queue is being created, the mq_flag field of the
335attribute 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
351int 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
359queue
360
361@subheading DESCRIPTION:
362
363The mq_close function removes the association between the message queue
364descriptor, mqdes, and its message queue. If mq_close() is successfully
365completed, the function returns a value of zero; otherwise, the function
366returns a value of -1 and sets errno to indicate the error.
367
368@subheading NOTES:
369
370If the process had successfully attached a notification request to the
371message queue via mq_notify, this attachment is removed, and the message
372queue is available for another process to attach for notification.
373mq_close has no effect on the contents of the message queue, all the
374messages 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
390int 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
401The mq_unlink() function removes the named message queue. If the message
402queue is not open when mq_unlink is called, then the queue is immediately
403eliminated. Any messages that were on the queue are lost, and the queue
404can not be opened again. If processes have the queue open when mq_unlink
405is called, the removal of the queue is delayed until the last process
406using the queue has finished. However, the name of the message queue is
407removed so that no other process can open it. Upon successful completion,
408the function returns a value of zero. Otherwise, the named message queue
409is 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
414Calls to mq_open() to re-create the message queue may fail until the
415message queue is actually removed. However, the mq_unlink() call need not
416block 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>
431int 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
449The mq_send() function adds the message pointed to by the argument msg_ptr
450to the message queue specified by mqdes. Each message is assigned a
451priority , from 0 to MQ_PRIO_MAX. MQ_PRIO_MAX is defined in <limits.h> and
452must be at least 32. Messages are added to the queue in order of their
453priority. The highest priority message is at the front of the queue.
454
455The maximum number of messages that a message queue may accept is
456specified at creation by the mq_maxmsg field of the attribute structure.
457If this amount is exceeded, the behavior of the process is determined
458according to what oflag was used when the message queue was opened. If
459the queue was opened with O_NONBLOCK flag set, then the EAGAIN error is
460returned. If the O_NONBLOCK flag was not set, the process blocks and
461waits for space on the queue, unless it is interrupted by a signal.
462
463Upon successful completion, the mq_send () function returns a value of
464zero. Otherwise, no message is enqueued, the function returns -1, and
465errno is set to indicate the error.
466
467@subheading NOTES:
468
469If the specified message queue is not full, mq_send inserts the message at
470the 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
486size_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
503The mq_receive function is used to receive the oldest of the highest
504priority message(s) from the message queue specified by mqdes. The
505messages are received in FIFO order within the priorities. The received
506message's priority is stored in the location referenced by the msg_prio.
507If the msg_prio is a NULL, the priority is discarded. The message is
508removed and stored in an area pointed to by msg_ptr whose length is of
509msg_len. The msg_len must be at least equal to the mq_msgsize attribute
510of the message queue.
511
512The blocking behavior of the message queue is set by O_NONBLOCK at mq_open
513or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is
514a blocking queue, the process blocks and waits on an empty queue. If this
515a non-blocking queue, the process does not block.
516
517Upon successful completion, mq_receive returns the length of the selected
518message in bytes and the message is removed from the queue. Otherwise, no
519message is removed from the queue, the function returns a value of -1, and
520sets errno to indicate the error.
521
522@subheading NOTES:
523
524If the size of the buffer in bytes, specified by the msg_len argument, is
525less than the mq_msgsize attribute of the message queue, the function
526fails 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
542int 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
555If the argument notification is not NULL, this function registers the
556calling process to be notified of message arrival at an empty message
557queue associated with the specified message queue descriptor, mqdes.
558
559Every message queue has the ability to notify one (and only one) process
560whenever the queue's state changes from empty (0 messages) to nonempty.
561This means that the process does not have to block or constantly poll
562while it waits for a message. By calling mq_notify, a notification
563request is attached to a message queue. When a message is received by an
564empty queue, if there are no processes blocked and waiting for the
565message, then the queue notifies the requesting process of a message
566arrival. There is only one signal sent by the message queue, after that
567the notification request is de-registered and another process can attach
568its notification request. After receipt of a notification, a process must
569re-register if it wishes to be notified again.
570
571If there is a process blocked and waiting for the message, that process
572gets the message, and notification is not be sent. Only one process can
573have a notification request attached to a message queue at any one time.
574If another process attempts to register a notification request, it fails.
575You can de-register for a message queue by passing a NULL to mq_notify;
576this removes any notification request attached to the queue. Whenever the
577message queue is closed, all notification attachments are removed.
578
579Upon successful completion, mq_notify returns a value of zero; otherwise,
580the function returns a value of -1 and sets errno to indicate the error.
581
582@subheading NOTES:
583
584It 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
600int 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
614The mq_setattr function is used to set attributes associated with the open
615message queue description referenced by the message queue descriptor
616specified by mqdes. The *omqstat represents the old or previous
617attributes. If omqstat is non-NULL, the function mq_setattr() stores, in
618the location referenced by omqstat, the previous message queue attributes
619and the current queue status. These values are the same as would be
620returned by a call to mq_getattr() at that point.
621
622There is only one mq_attr.mq_flag which can be altered by this call.
623This is the flag that deals with the blocking and non-blocking behavior of
624the message queue. If the flag is set then the message queue is
625non-blocking, and requests to send or receive do not block while waiting
626for resources. If the flag is not set, then message send and receive may
627involve waiting for an empty queue or waiting for a message to arrive.
628
629Upon successful completion, the function returns a value of zero and the
630attributes of the message queue have been changed as specified.
631Otherwise, the message queue attributes is unchanged, and the function
632returns a value of -1 and sets errno to indicate the error.
633
634@subheading NOTES:
635
636All 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>
651int 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,
660open message queue.
661
662@subheading DESCRIPTION:
663
664The mqdes argument specifies a message queue descriptor. The mq_getattr
665function is used to get status information and attributes of the message
666queue associated with the message queue descriptor. The results are
667returned in the mq_attr structure referenced by the mqstat argument. All
668of these attributes are set at create time, except the
669blocking/non-blocking behavior of the message queue which can be
670dynamically set by using mq_setattr. The attribute mq_curmsg is set to
671reflect the number of messages on the queue at the time that mq_getattr
672was called.
673
674Upon successful completion, the mq_getattr function returns zero.
675Otherwise, the function returns -1 and sets errno to indicate the error.
676
677@subheading NOTES:
678
Note: See TracBrowser for help on using the repository browser.