Changeset 3d7e9240 in rtems


Ignore:
Timestamp:
Oct 11, 1999, 7:51:56 PM (22 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
ea7e8618
Parents:
d4e2e54b
Message:

Now build.

Location:
doc/posix_users
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • doc/posix_users/message.t

    rd4e2e54b r3d7e9240  
    11@c
    2 @c  COPYRIGHT (c) 1988-1998.
    3 @c  On-Line Applications Research Corporation (OAR).
     2@c  COPYRIGHT(c) 1988-1998.
     3@c  On-Line Applications Research Corporation(OAR).
    44@c  All rights reserved.
    55@c
     
    1111@section Introduction
    1212
    13 The
    14 message passing manager is ...
    15 
    16 The directives provided by the message passing manager are:
     13The message passing manager is the means to provide communication and synchronization capabilities using POSIX message queues.
     14
     15The directives provided by the message passing manager are:
    1716
    1817@itemize @bullet
    19 @item @code{mq_open} -
    20 @item @code{mq_close} -
    21 @item @code{mq_unlink} -
    22 @item @code{mq_send} -
    23 @item @code{mq_receive} -
    24 @item @code{mq_notify} -
    25 @item @code{mq_setattr} -
    26 @item @code{mq_getattr} -
     18@item @code{mq_open} - to begin using a message queue
     19@item @code{mq_close} - to close the queue after a message has been sent.
     20@item @code{mq_unlink} - to remove a message queue from the system entirely
     21@item @code{mq_send} - to send messages to a queue you have accessed
     22@item @code{mq_receive} - to receive messages from a queue you have accessed
     23@item @code{mq_notify} - to notify that a message is on the queue
     24@item @code{mq_setattr} - to change the blocking/non-blocking behavior of the message queue
     25@item @code{mq_getattr} - to retrieve the message queue attributes for the named queue
    2726@end itemize
    2827
    2928@section Background
    3029
    31 There is currently no text in this section.
     30@subsection Theory
     31
     32Message queues are named objects that operate with readers and writers.  In addition, a message queue is a priority queue of discrete messages.  POSIX message queues offer a certain, basic amount of application access to, and control over, the message queue geometry that can be changed.
     33
     34@subsection Messages
     35
     36A message is a variable length buffer where information can be stored to support communication.  The length of the message and the information stored in that message are user-defined and can be actual data, pointer(s), or empty.  There is a maximum acceptable length for a message that is associated with each message queue.
     37
     38@subsection Message Queues
     39
     40Message queues are named objects similar to the pipes of POSIX.  They are a means of communicating data between multiple processes and for passing messages among tasks and ISRs.  Message queues can contain a variable number of messages from 0 to an upper limit that is user defined.  The maximum length of the message can be set on a per message queue basis.  Normally messages are sent and received from the message queue in FIFO order.  However, messages can also be prioritized and a priority queue established for the passing of messages.  Synchronization is needed when a task waits for a message to arrive at a queue.  Also, a task may poll a queue for the arrival of a message.
     41The message queue descriptor mqd_t mq represents the message queue.  It is passed as an argument to all of the message queue functions.
     42
     43@subsection Building a Message Queue Attribute Set
     44
     45 The mq_attr structure is used to define the characteristics of the message queue.
     46
     47@example
     48@group
     49/*
     50 *  Create Message Queue (mq) Structure
     51 */
     52
     53typedef struct mq_attr@{
     54        long mq_flags;                  /* Message queue flags */
     55        long mq_maxmsg;                 /* Maximum number of messages for the queue */
     56        long mq_msgsize;                /* Maximum message size */
     57        long mq_curmsgs;                /* Number of messages currently queued */
     58@};
     59@end group
     60@end example
     61
     62All of these attributes are set when the message queue is created using mq_open.  The mq_flags field is not used in the creation of a message queue, it is only used by mq_setattr and mq_getattr.  The structure mq_attr is passed as an argument to mq_setattr and mq_getattr.
     63The mq_flags contain information affecting the behavior of the message queue.  The O_NONBLOCK mq_flag is the only flag that is defined.  In mq_setattr, the mq_flag can be set to dynamically change the blocking and non-blocking behavior of the message queue.  If the non-block flag is set then the message queue is non-blocking, and requests to send and receive messages do not block waiting for resources.  For a blocking message queue, a request to send might have to wait for an empty message queue, and a request to receive might have to wait for a message to arrive on the queue. Both mq_maxmsg and mq_msgsize affect the sizing of the message queue.  mq_maxmsg specifies how many messages the queue can hold at any one time.  mq_msgsize specifies the size of any one message on the queue.  If either of these limits is exceeded, an error message results.
     64Upon return from mq_getattr, the mq_curmsgs is set according to the current state of the message queue.  This specifies the number of messages currently on the queue.
     65
     66@subsection Notification of a Message on the Queue
     67
     68Every message queue has the ability to notify one (and only one) process whenever the queue's state changes from empty (0 messages) to nonempty.  This means that the process does not have to block or constantly poll while it waits for a message.  By calling mq_notify, you can attach a notification request to a message queue.  When a message is received by an empty queue, if there are no processes blocked and waiting for the message, then the queue notifies the requesting process of a message arrival.  There is only one signal sent by the message queue, after that the notification request is de-registered and another process can attach its notification request.  After receipt of a notification, a process must re-register if it wishes to be notified again.
     69If there is a process blocked and waiting for the message, that process gets the message, and notification is not sent.  It is also possible for another process to receive the message after the notification is sent but before the notified process has sent its receive request.
     70Only one process can have a notification request attached to a message queue at any one time.  If another process attempts to register a notification request, it fails.  You can de-register for a message queue by passing a NULL to mq_notify, this removes any notification request attached to the queue.  Whenever the message queue is closed, all notification attachments are removed.
    3271
    3372@section Operations
    3473
    35 There is currently no text in this section.
     74@subsection Opening or Creating a Message Queue
     75
     76If the message queue already exists, mq_open() opens it, if the message queue does not exist, mq_open() creates it.  When a message queue is created, the geometry of the message queue is contained in the attribute structure that is passed in as an argument.  This includes mq_msgsize that dictates the maximum size of a single message, and the mq_maxmsg that dictates the maximum number of messages the queue can hold at one time.  The blocking or non-blocking behavior of the queue can also specified.
     77
     78@subsection Closing a Message Queue
     79
     80The mq_close() function is used to close the connection made to a message queue that was made during mq_open.  The message queue itself and the messages on the queue are persistent and remain after the queue is closed.
     81
     82@subsection Removing a Message Queue
     83
     84The mq_unlink() function removes the named message queue.  If the message queue is not open when mq_unlink is called, then the queue is immediately eliminated.  Any messages that were on the queue are lost, and the queue can not be opened again.  If processes have the queue open when mq_unlink is called, the removal of the queue is delayed until the last process using the queue has finished.  However, the name of the message queue is removed so that no other process can open it.
     85
     86@subsection Sending a Message to a Message Queue
     87
     88The mq_send() function adds the message in priority order to the message queue.  Each message has an assigned a priority.  The highest priority message is be at the front of the queue.
     89The maximum number of messages that a message queue may accept is specified at creation by the mq_maxmsg field of the attribute structure.  If this amount is exceeded, the behavior of the process is determined according to what oflag was used when the message queue was opened.  If the queue was opened with O_NONBLOCK flag set, the process does not block, and an error is returned.  If the O_NONBLOCK flag was not set, the process does block and wait for space on the queue.
     90
     91@subsection Receiving a Message from a Message Queue
     92
     93The mq_receive() function is used to receive the oldest of the highest priority message(s) from the message queue specified by mqdes.  The messages are received in FIFO order within the priorities.  The received message's priority is stored in the location referenced by the msg_prio.  If the msg_prio is a NULL, the priority is discarded.  The message is removed and stored in an area pointed to by msg_ptr whose length is of msg_len.  The msg_len must be at least equal to the mq_msgsize attribute of the message queue.
     94The blocking behavior of the message queue is set by O_NONBLOCK at mq_open or by setting O_NONBLOCK in mq_flags in a call to mq_setattr.  If this is a blocking queue, the process does block and wait on an empty queue.  If this a non-blocking queue, the process does not block.
     95Upon successful completion, mq_receive returns the length of the selected message in bytes and the message is removed from the queue.
     96
     97@subsection Notification of Receipt of a Message on an Empty Queue
     98
     99The mq_notify() function registers the calling process to be notified of message arrival at an empty message queue.  Every message queue has the ability to notify one (and only one) process whenever the queue's state changes from empty (0 messages) to nonempty.  This means that the process does not have to block or constantly poll while it waits for a message.  By calling mq_notify, a notification request is attached to a message queue.  When a message is received by an empty queue, if there are no processes blocked and waiting for the message, then the queue notifies the requesting process of a message arrival.  There is only one signal sent by the message queue, after that the notification request is de-registered and another process can attach its notification request.  After receipt of a notification, a process must re-register if it wishes to be notified again.
     100If there is a process blocked and waiting for the message, that process gets the message, and notification is not sent.  Only one process can have a notification request attached to a message queue at any one time.  If another process attempts to register a notification request, it fails.  You can de-register for a message queue by passing a NULL to mq_notify, this removes any notification request attached to the queue.  Whenever the message queue is closed, all notification attachments are removed.
     101
     102@subsection Setting the Attributes of a Message Queue
     103
     104The mq_setattr() function is used to set attributes associated with the open message queue description referenced by the message queue descriptor specified by mqdes.  The *omqstat represents the old or previous attributes.  If omqstat is non-NULL, the function mq_setattr() stores, in the location referenced by omqstat, the previous message queue attributes and the current queue status.  These values are the same as would be returned by a call to mq_getattr() at that point.
     105There is only one mq_attr.mq_flag that can be altered by this call.  This is the flag that deals with the blocking and non-blocking behavior of the message queue.  If the flag is set then the message queue is non-blocking, and requests to send or receive do not block while waiting for resources.  If the flag is not set, then message send and receive may involve waiting for an empty queue or waiting for a message to arrive.
     106
     107@subsection Getting the Attributes of a Message Queue
     108
     109The mq_getattr() function is used to get status information and attributes of the message queue associated with the message queue descriptor.  The results are returned in the mq_attr structure referenced by the mqstat argument.  All of these attributes are set at create time, except the blocking/non-blocking behavior of the message queue which can be dynamically set by using mq_setattr.  The attribute mq_curmsg is set to reflect the number of messages on the queue at the time that mq_getattr was called.
    36110
    37111@section Directives
    38112
    39 This section details the message passing manager's directives.
    40 A subsection is dedicated to each of this manager's directives
    41 and describes the calling sequence, related constants, usage,
    42 and status codes.
    43 
    44 @page
    45 @subsection mq_open -
    46 
    47 @subheading CALLING SEQUENCE:
    48 
    49 @ifset is-C
    50 @example
    51 int mq_open(
    52 );
    53 @end example
    54 @end ifset
    55 
    56 @ifset is-Ada
    57 @end ifset
    58 
    59 @subheading STATUS CODES:
    60 
    61 @table @b
    62 @item E
    63 The
    64 
    65 @end table
    66 
    67 @subheading DESCRIPTION:
    68 
    69 @subheading NOTES:
    70 
    71 @page
    72 @subsection mq_close -
    73 
    74 @subheading CALLING SEQUENCE:
    75 
    76 @ifset is-C
    77 @example
    78 int mq_close(
    79 );
    80 @end example
    81 @end ifset
    82 
    83 @ifset is-Ada
    84 @end ifset
    85 
    86 @subheading STATUS CODES:
    87 
    88 @table @b
    89 @item E
    90 The
    91 
    92 @end table
    93 
    94 @subheading DESCRIPTION:
    95 
    96 @subheading NOTES:
    97 
    98 @page
    99 @subsection mq_unlink -
    100 
    101 @subheading CALLING SEQUENCE:
    102 
    103 @ifset is-C
    104 @example
    105 int mq_unlink(
    106 );
    107 @end example
    108 @end ifset
    109 
    110 @ifset is-Ada
    111 @end ifset
    112 
    113 @subheading STATUS CODES:
    114 
    115 @table @b
    116 @item E
    117 The
    118 
    119 @end table
    120 
    121 @subheading DESCRIPTION:
    122 
    123 @subheading NOTES:
    124 
    125 @page
    126 @subsection mq_send -
    127 
    128 @subheading CALLING SEQUENCE:
    129 
    130 @ifset is-C
    131 @example
    132 int mq_send(
    133 );
    134 @end example
    135 @end ifset
    136 
    137 @ifset is-Ada
    138 @end ifset
    139 
    140 @subheading STATUS CODES:
    141 
    142 @table @b
    143 @item E
    144 The
    145 
    146 @end table
    147 
    148 @subheading DESCRIPTION:
    149 
    150 @subheading NOTES:
    151 
    152 @page
    153 @subsection mq_receive -
    154 
    155 @subheading CALLING SEQUENCE:
    156 
    157 @ifset is-C
    158 @example
    159 int mq_receive(
    160 );
    161 @end example
    162 @end ifset
    163 
    164 @ifset is-Ada
    165 @end ifset
    166 
    167 @subheading STATUS CODES:
    168 
    169 @table @b
    170 @item E
    171 The
    172 
    173 @end table
    174 
    175 @subheading DESCRIPTION:
    176 
    177 @subheading NOTES:
    178 
    179 @page
    180 @subsection mq_notify -
    181 
    182 @subheading CALLING SEQUENCE:
    183 
    184 @ifset is-C
    185 @example
    186 int mq_notify(
    187 );
    188 @end example
    189 @end ifset
    190 
    191 @ifset is-Ada
    192 @end ifset
    193 
    194 @subheading STATUS CODES:
    195 
    196 @table @b
    197 @item E
    198 The
    199 
    200 @end table
    201 
    202 @subheading DESCRIPTION:
    203 
    204 @subheading NOTES:
    205 
    206 @page
    207 @subsection mq_setattr -
    208 
    209 @subheading CALLING SEQUENCE:
    210 
    211 @ifset is-C
    212 @example
    213 int mq_setattr(
    214 );
    215 @end example
    216 @end ifset
    217 
    218 @ifset is-Ada
    219 @end ifset
    220 
    221 @subheading STATUS CODES:
    222 
    223 @table @b
    224 @item E
    225 The
    226 
    227 @end table
    228 
    229 @subheading DESCRIPTION:
    230 
    231 @subheading NOTES:
    232 
    233 @page
    234 @subsection mq_getattr -
    235 
    236 @subheading CALLING SEQUENCE:
    237 
    238 @ifset is-C
    239 @example
    240 int mq_getattr(
    241 );
    242 @end example
    243 @end ifset
    244 
    245 @ifset is-Ada
    246 @end ifset
    247 
    248 @subheading STATUS CODES:
    249 
    250 @table @b
    251 @item E
    252 The
    253 
    254 @end table
    255 
    256 @subheading DESCRIPTION:
    257 
    258 @subheading NOTES:
    259 
     113This section details the message passing manager's directives. A subsection is dedicated to each of this manager's directives and describes the calling sequence, related constants, usage, and status codes.
     114
     115@subsection mq_open -to create or open a message queue
     116
     117@subheading CALLING SEQUENCE:
     118
     119@example
     120#include <mqueue.h>
     121mqd_t mq_open(const char *name, int oflag, mode_t mode, struct mq_attr *attr);   
     122@end example
     123
     124@subheading STATUS CODES:
     125
     126@code{EACCES} - Either the message queue exists and the permissions requested in oflags were denied, or the message does not exist and permission to create one is denied.
     127
     128@code{EEXIST} - You tried to create a message queue that already exists.
     129
     130@code{EINVAL} - An inappropriate name was given for the message queue, or the values of mq-maxmsg or mq_msgsize were less than 0.
     131
     132@code{ENOENT} - The message queue does not exist, and you did not specify to create it.
     133
     134@code{EINTR} - The call to mq_open was interrupted by a signal.
     135
     136@code{EMFILE} - The process has too many files or message queues open.  This is a process limit error.
     137
     138@code{ENFILE} - The system has run out of resources to support more open message queues.  This is a system error.
     139
     140@code{ENAMETOOLONG} - mq_name is too long.
     141
     142@subheading DESCRIPTION:
     143
     144The mq_open () function establishes the connection between a process and a message queue with a message queue descriptor.  If the message queue already exists, mq_open opens it, if the message queue does not exist, mq_open creates it.  Message queues can have multiple senders and receivers.  If mq_open is successful, the function returns a message queue descriptor.  Otherwise, the function returns a -1 and sets 'errno' to indicate the error.
     145
     146The name of the message queue is used as an argument.  For the best of portability, the name of the message queue should begin with a "/" and no other "/" should be in the name.  Different systems interpret the name in different ways.
     147
     148The oflags contain information on how the message is opened if the queue already exists.  This may be O_RDONLY for read only, O_WRONLY for write only, of O_RDWR, for read and write.
     149
     150In addition, the oflags contain information needed in the creation of a message queue.
     151@code{O_NONBLOCK} - If the non-block flag is set then the message queue is non-blocking, and requests to send and receive messages do not block waiting for resources.  If the flag is not set then the message queue is blocking, and a request to send might have to wait for an empty message queue.  Similarly, a request to receive might have to wait for a message to arrive on the queue.
     152@code{O_CREAT} - This call specifies that the call the mq_open is to create a new message queue.  In this case the mode and attribute arguments of the function call are utilized.  The message queue is created with a mode similar to the creation of a file, read and write permission creator, group, and others.
     153
     154The geometry of the message queue is contained in the attribute structure.  This includes mq_msgsize that dictates the maximum size of a single message, and the mq_maxmsg that dictates the maximum number of messages the queue can hold at one time.  If a NULL is used in the mq_attr argument, then the message queue is created with implementation defined defaults.
     155@code{O_EXCL} - is always set if O_CREAT flag is set.  If the message queue already exists, O_EXCL causes an error message to be returned, otherwise, the new message queue fails and appends to the existing one.
     156
     157@subheading NOTES:
     158
     159The mq_open () function does not add or remove messages from the queue.  When a new message queue is being created, the mq_flag field of the attribute structure is not used.
     160
     161@subsection mq_close - to close the queue after a message has been sent
     162
     163@subheading CALLING SEQUENCE:
     164
     165@example
     166#include <mqueue.h>
     167int mq_close(mqd_t mqdes);
     168@end example
     169
     170@subheading STATUS CODES:
     171
     172@code{EINVAL} - The descriptor does not represent a valid open message queue
     173
     174@subheading DESCRIPTION:
     175
     176The mq_close function removes the association between the message queue descriptor, mqdes, and its message queue. If mq_close() is successfully completed, the function returns a value of zero; otherwise, the function returns a value of -1 and sets errno to indicate the error.
     177
     178@subheading NOTES:
     179
     180If the process had successfully attached a notification request to the message queue via mq_notify, this attachment is removed, and the message queue is available for another process to attach for notification.  mq_close has no effect on the contents of the message queue, all the messages that were in the queue remain in the queue.
     181
     182@subsection mq_unlink - to remove a message queue from the system entirely
     183
     184@subheading CALLING SEQUENCE:
     185
     186@example
     187#include <mqueue.h>
     188int mq_unlink(const char *name);
     189@end example
     190
     191@subheading STATUS CODES:
     192
     193@code{EINVAL} - The descriptor does not represent a valid message queue
     194
     195@subheading DESCRIPTION:
     196
     197The mq_unlink() function removes the named message queue.  If the message queue is not open when mq_unlink is called, then the queue is immediately eliminated.  Any messages that were on the queue are lost, and the queue can not be opened again.  If processes have the queue open when mq_unlink is called, the removal of the queue is delayed until the last process using the queue has finished.  However, the name of the message queue is removed so that no other process can open it.  Upon successful completion, the function returns a value of zero.  Otherwise, the named message queue is not changed by this function call, and the function returns a value of -1 and sets errno to indicate the error.
     198
     199@subheading NOTES:
     200
     201Calls to mq_open() to re-create the message queue may fail until the message queue is actually removed.  However, the mq_unlink() call need not block until all references have been closed; it may return immediately.
     202
     203subsection mq_send - to send messages to a queue you have accessed
     204
     205@subheading CALLING SEQUENCE:
     206
     207@example
     208#include<mqueue.h>
     209int mq_send(mqd_t mqdes, const char *msg_ptr, size_t msg_len, unsigned int msg_prio);
     210@end example
     211
     212@subheading STATUS CODES:
     213
     214@code{EBADF} - The descriptor does not represent a valid message queue, or the queue was opened for read only O_RDONLY
     215@code{EINVAL} - The value of msg_prio was greater than the MQ_PRIO_MAX.
     216@code{EMSGSIZE} - The msg_len is greater than the mq_msgsize attribute of the message queue
     217@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.
     218@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.
     219
     220@subheading DESCRIPTION:
     221
     222The mq_send() function adds the message pointed to by the argument msg_ptr to the message queue specified by mqdes.  Each message is assigned a priority , from 0 to MQ_PRIO_MAX. MQ_PRIO_MAX is defined in <limits.h> and must be at least 32.  Messages are added to the queue in order of their priority.  The highest priority message is at the front of the queue.
     223The maximum number of messages that a message queue may accept is specified at creation by the mq_maxmsg field of the attribute structure.  If this amount is exceeded, the behavior of the process is determined according to what oflag was used when the message queue was opened.  If the queue was opened with O_NONBLOCK flag set, then the EAGAIN error is returned.  If the O_NONBLOCK flag was not set, the process blocks and waits for space on the queue, unless it is interrupted by a signal.
     224Upon successful completion, the mq_send () function returns a value of zero.  Otherwise, no message is enqueued, the function returns -1, and errno is set to indicate the error.
     225
     226@subheading NOTES:
     227
     228If the specified message queue is not full, mq_send inserts the message at the position indicated by the msg_prio argument.
     229
     230@subsection mq_receive - to receive messages from a queue you have accessed
     231
     232@subheading CALLING SEQUENCE:
     233
     234@example
     235#include <mqueue.h>
     236size_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len, unsigned int *msg_prio);
     237@end example
     238
     239@subheading STATUS CODES:
     240
     241@code{EBADF} - The descriptor does not represent a valid message queue, or the queue was opened for write only O_WRONLY
     242@code{EMSGSIZE} - The msg_len is less than the mq_msgsize attribute of the message queue
     243@code{EAGAIN} - The message queue is non-blocking, and the queue is empty
     244@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.
     245
     246@subheading DESCRIPTION:
     247
     248The mq_receive function is used to receive the oldest of the highest priority message(s) from the message queue specified by mqdes.  The messages are received in FIFO order within the priorities.  The received message's priority is stored in the location referenced by the msg_prio.  If the msg_prio is a NULL, the priority is discarded.  The message is removed and stored in an area pointed to by msg_ptr whose length is of msg_len.  The msg_len must be at least equal to the mq_msgsize attribute of the message queue.
     249The blocking behavior of the message queue is set by O_NONBLOCK at mq_open or by setting O_NONBLOCK in mq_flags in a call to mq_setattr.  If this is a blocking queue, the process blocks and waits on an empty queue.  If this a non-blocking queue, the process does not block.
     250Upon successful completion, mq_receive returns the length of the selected message in bytes and the message is removed from the queue.  Otherwise, no message is removed from the queue, the function returns a value of -1, and sets errno to indicate the error.
     251
     252@subheading NOTES:
     253
     254If the size of the buffer in bytes, specified by the msg_len argument, is less than the mq_msgsize attribute of the message queue, the function fails and returns an error
     255
     256@subsection mq_notify - to notify that a message is on the queue
     257
     258@subheading CALLING SEQUENCE:
     259
     260@example
     261#include <mqueue.h>
     262int mq_notify (mqd_t mqdes, const struct sigevent * notification);
     263@end example
     264
     265@subheading STATUS CODES:
     266
     267@code{EBADF} - The descriptor does not refer to a valid message queue
     268@code{EBUSY} - A notification request is already attached to the queue
     269
     270@subheading DESCRIPTION:
     271
     272If the argument notification is not NULL, this function registers the calling process to be notified of message arrival at an empty message queue associated with the specified message queue descriptor, mqdes.
     273Every message queue has the ability to notify one (and only one) process whenever the queue's state changes from empty (0 messages) to nonempty.  This means that the process does not have to block or constantly poll while it waits for a message.  By calling mq_notify, a notification request is attached to a message queue.  When a message is received by an empty queue, if there are no processes blocked and waiting for the message, then the queue notifies the requesting process of a message arrival.  There is only one signal sent by the message queue, after that the notification request is de-registered and another process can attach its notification request.  After receipt of a notification, a process must re-register if it wishes to be notified again.
     274If there is a process blocked and waiting for the message, that process gets the message, and notification is not be sent.  Only one process can have a notification request attached to a message queue at any one time.  If another process attempts to register a notification request, it fails.  You can de-register for a message queue by passing a NULL to mq_notify; this removes any notification request attached to the queue.  Whenever the message queue is closed, all notification attachments are removed.
     275Upon successful completion, mq_notify returns a value of zero; otherwise, the function returns a value of -1 and sets errno to indicate the error.
     276
     277@subheading NOTES:
     278
     279It is possible for another process to receive the message after the notification is sent but before the notified process has sent its receive request.
     280
     281@subsection mq_setattr - to change the blocking and non-blocking behavior of the message queue
     282
     283@subheading CALLING SEQUENCE:
     284
     285@example
     286#include <mqueue.h>
     287int mq_setattr(mqd_t mqdes, const struct mq_attr *mqstat, struct mq_attr *omqstat);
     288@end example
     289
     290@subheading STATUS CODES:
     291
     292@code{EBADF} - The message queue descriptor does not refer to a valid, open queue.
     293@code{EINVAL} - The mq_flag value is invalid.
     294
     295@subheading DESCRIPTION:
     296
     297The mq_setattr function is used to set attributes associated with the open message queue description referenced by the message queue descriptor specified by mqdes.  The *omqstat represents the old or previous attributes.  If omqstat is non-NULL, the function mq_setattr() stores, in the location referenced by omqstat, the previous message queue attributes and the current queue status.  These values are the same as would be returned by a call to mq_getattr() at that point.
     298There is only one mq_attr.mq_flag which can be altered by this call.  This is the flag that deals with the blocking and non-blocking behavior of the message queue.  If the flag is set then the message queue is non-blocking, and requests to send or receive do not block while waiting for resources.  If the flag is not set, then message send and receive may involve waiting for an empty queue or waiting for a message to arrive.
     299Upon successful completion, the function returns a value of zero and the attributes of the message queue have been changed as specified.  Otherwise, the message queue attributes is unchanged, and the function returns a value of -1 and sets errno to indicate the error.
     300
     301@subheading NOTES:
     302
     303All other fields in the mq_attr are ignored by this call.
     304
     305@subsection mq_getattr - retrieves the message queue attributes
     306
     307@subheading CALLING SEQUENCE:
     308
     309@example
     310#include <mqueue.h>
     311int mq_getattr(mqd_t mqdes, struct mq_attr *mqstat);
     312@end example
     313
     314@subheading STATUS CODES:
     315
     316@code{EBADF} - The message queue descriptor does not refer to a valid, open message queue.
     317
     318@subheading DESCRIPTION:
     319
     320The mqdes argument specifies a message queue descriptor.  The mq_getattr function is used to get status information and attributes of the message queue associated with the message queue descriptor.  The results are returned in the mq_attr structure referenced by the mqstat argument.  All of these attributes are set at create time, except the blocking/non-blocking behavior of the message queue which can be dynamically set by using mq_setattr.  The attribute mq_curmsg is set to reflect the number of messages on the queue at the time that mq_getattr was called.
     321Upon successful completion, the mq_getattr function returns zero.  Otherwise, the function returns -1 and sets errno to indicate the error.
     322
     323@subheading NOTES:
     324
  • doc/posix_users/posix_users.texi

    rd4e2e54b r3d7e9240  
    120120* Language-Specific Services for the C Programming Language Manager::
    121121* System Databases Manager::
    122 * Semaphores Manager::
     122* Semaphore Manager::
    123123* Mutex Manager::
    124124* Condition Variable Manager::
  • doc/posix_users/semaphores.t

    rd4e2e54b r3d7e9240  
    11@c
    2 @c  COPYRIGHT (c) 1988-1998.
    3 @c  On-Line Applications Research Corporation (OAR).
     2@c  COPYRIGHT(c) 1988-1998.
     3@c  On-Line Applications Research Corporation(OAR).
    44@c  All rights reserved.
    55@c
     
    77@c
    88
    9 @chapter Semaphores Manager
     9@chapter Semaphore Manager
    1010
    1111@section Introduction
    1212
    13 The
    14 semaphore manager is ...
     13The semaphore manager provides functions to allocate, delete, and control
     14semaphores. This manager is based on the POSIX 1003.1 standard.
    1515
    1616The directives provided by the semaphore manager are:
    1717
    1818@itemize @bullet
    19 @item @code{sem_init} -
    20 @item @code{sem_destroy} -
    21 @item @code{sem_open} -
    22 @item @code{sem_close} -
    23 @item @code{sem_unlink} -
    24 @item @code{sem_wait} -
    25 @item @code{sem_trywait} -
    26 @item @code{sem_post} -
    27 @item @code{sem_getvalue} -
     19@item @code{sem_init} - Initialize an unnamed semaphore
     20@item @code{sem_destroy} - Destroy an unnamed semaphore
     21@item @code{sem_open} - Open a named semaphore
     22@item @code{sem_close} - Close a named semaphore
     23@item @code{sem_unlink} - Remove a named semaphore
     24@item @code{sem_wait} - Lock a semaphore
     25@item @code{sem_trywait} - Lock a semaphore
     26@item @code{sem_post} - Unlock a semaphore
     27@item @code{sem_getvalue} - Get the value of a semeaphore
    2828@end itemize
    2929
    3030@section Background
    3131
    32 There is currently no text in this section.
     32@subsection Theory
     33Semaphores are used for synchronization and mutual exclusion by indicating the
     34availability and number of resources. The task (the task which is returning
     35resources) notifying other tasks of an event increases the number of resources
     36held by the semaphore by one. The task (the task which will obtain resources)
     37waiting for the event decreases the number of resources held by the semaphore
     38by one. If the number of resources held by a semaphore is insufficient (namely
     390), the task requiring resources will wait until the next time resources are
     40returned to the semaphore. If there is more than one task waiting for a
     41semaphore, the tasks will be placed in the queue.
     42
     43@subsection "sem_t" Structure
     44The "sem_t" structure is used to represent semaphores. It is passed as an
     45argument to the semaphore directives and is defined as follows:
     46
     47@example
     48  /*
     49   * sem_t structure
     50   */
     51
     52  typedef int sem_t
     53@end example
     54 
     55@subsection Building a Semaphore Attribute Set
    3356
    3457@section Operations
     58
     59@subsection Using as a Binary Semaphore
     60Although POSIX supports mutexes, they are only visible between threads. To work
     61between processes, a binary semaphore must be used.
     62 
     63Creating a semaphore with a limit on the count of 1 effectively restricts the
     64semaphore to being a binary semaphore. When the binary semaphore is available,
     65the count is 1. When the binary semaphore is unavailable, the count is 0.
     66
     67Since this does not result in a true binary semaphore, advanced binary features like the Priority Inheritance and Priority Ceiling Protocols are not available.
    3568
    3669There is currently no text in this section.
     
    4477
    4578@page
    46 @subsection sem_init -
     79@subsection sem_init - Initialize an unnamed semaphore
    4780
    4881@subheading CALLING SEQUENCE:
     
    5184@example
    5285int sem_init(
    53 );
    54 @end example
    55 @end ifset
    56 
    57 @ifset is-Ada
    58 @end ifset
    59 
    60 @subheading STATUS CODES:
    61 
    62 @table @b
    63 @item E
    64 The
    65 
    66 @end table
    67 
    68 @subheading DESCRIPTION:
    69 
    70 @subheading NOTES:
    71 
    72 @page
    73 @subsection sem_destroy -
     86  sem_t *sem,
     87  int pshared,
     88  unsigned int value
     89);
     90@end example
     91@end ifset
     92
     93@ifset is-Ada
     94@end ifset
     95
     96@subheading STATUS CODES:
     97
     98@table @b
     99@item EINVAL
     100The value argument exceeds SEM_VALUE_MAX
     101
     102@item ENOSPC
     103A resource required to initialize the semaphore has been exhausted
     104The limit on semaphores (SEM_VALUE_MAX) has been reached
     105
     106@item ENOSYS
     107The function sem_init is not supported by this implementation
     108
     109@item EPERM
     110The process lacks appropriate privileges to initialize the semaphore
     111
     112@end table
     113
     114@subheading DESCRIPTION:
     115The sem_init function is used to initialize the unnamed semaphore referred to
     116by "sem". The value of the initialized semaphore is the parameter "value". The
     117semaphore remains valid until it is destroyed.
     118
     119ADD MORE HERE XXX
     120
     121@subheading NOTES:
     122If the functions completes successfully, it shall return a value of zero.
     123Otherwise, it shall return a value of -1 and set "errno" to specify the error
     124that occurred.
     125
     126Multiprocessing is currently not supported in this implementation.
     127
     128@page
     129@subsection sem_destroy - Destroy an unnamed semaphore
    74130
    75131@subheading CALLING SEQUENCE:
     
    78134@example
    79135int sem_destroy(
    80 );
    81 @end example
    82 @end ifset
    83 
    84 @ifset is-Ada
    85 @end ifset
    86 
    87 @subheading STATUS CODES:
    88 
    89 @table @b
    90 @item E
    91 The
    92 
    93 @end table
    94 
    95 @subheading DESCRIPTION:
    96 
    97 @subheading NOTES:
    98 
    99 @page
    100 @subsection sem_open -
    101 
    102 @subheading CALLING SEQUENCE:
    103 
    104 @ifset is-C
    105 @example
    106 int sem_open(
    107 );
    108 @end example
    109 @end ifset
    110 
    111 @ifset is-Ada
    112 @end ifset
    113 
    114 @subheading STATUS CODES:
    115 
    116 @table @b
    117 @item E
    118 The
    119 
    120 @end table
    121 
    122 @subheading DESCRIPTION:
    123 
    124 @subheading NOTES:
    125 
    126 @page
    127 @subsection sem_close -
     136  sem_t *sem
     137);
     138@end example
     139@end ifset
     140
     141@ifset is-Ada
     142@end ifset
     143
     144@subheading STATUS CODES:
     145
     146@table @b
     147@item EINVAL
     148The value argument exceeds SEM_VALUE_MAX
     149
     150@item ENOSYS
     151The function sem_init is not supported by this implementation
     152
     153@item EBUSY
     154There are currently processes blocked on the semaphore
     155
     156@end table
     157
     158@subheading DESCRIPTION:
     159The sem_destroy function is used to destroy an unnamed semaphore refered to by
     160"sem". sem_destroy can only be used on a semaphore that was created using
     161sem_init.
     162
     163@subheading NOTES:
     164If the functions completes successfully, it shall return a value of zero.
     165Otherwise, it shall return a value of -1 and set "errno" to specify the error
     166that occurred.
     167
     168Multiprocessing is currently not supported in this implementation.
     169
     170
     171@page
     172@subsection sem_open - Open a named semaphore
     173
     174@subheading CALLING SEQUENCE:
     175
     176@ifset is-C
     177@example
     178int sem_open)
     179  const char *name,
     180  int oflag
     181);
     182@end example
     183@end ifset
     184
     185@ifset is-Ada
     186@end ifset
     187
     188@subheading ARGUMENTS:
     189
     190The following flag bit may be set in oflag:
     191
     192@code{O_CREAT} - Creates the semaphore if it does not already exist.  If O_CREAT
     193is set and the semaphore already exists then O_CREAT has no effect.  Otherwise,
     194sem_open() creates a semaphore.  The O_CREAT flag requires the third and fourth
     195argument:  mode and value of type mode_t and unsigned int, respectively.
     196
     197@code{O_EXCL} - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail
     198if the semaphore name exists
     199
     200@subheading STATUS CODES:
     201
     202@table @b
     203@item EACCES
     204Valid name specified but oflag permissions are denied,  or the semaphore name
     205specified does not exist and permission to create the named semaphore is denied.
     206
     207@item EEXIST
     208O_CREAT and O_EXCL are set and the named semaphore already exists.
     209
     210@item EINTR
     211The sem_open() operation was interrupted  by a signal.
     212
     213@item EINVAL
     214The sem_open() operation is not supported for the given name.
     215
     216@item EMFILE
     217Too many semaphore descriptors or file descriptors in use by this process.
     218
     219@item ENAMETOOLONG
     220The length of the name exceed PATH_MAX or  name component is longer than NAME_MAX
     221while POSIX_NO_TRUNC  is in effect.
     222
     223@item ENOENT
     224O_CREAT is not set and the named semaphore does not exist.
     225
     226@item ENOSPC
     227There is insufficient space for the creation of a new named semaphore.
     228
     229@item ENOSYS
     230The function sem_open() is not supported by this implementation.
     231
     232@end table
     233
     234@subheading DESCRIPTION:
     235The sem_open() function establishes a connection between a specified semaphore and
     236a process.  After a call to sem_open with a specified semaphore name, a process
     237can reference to semaphore by the associated name using the address returned by
     238the call.  The oflag arguments listed above control the state of the semaphore by
     239determining if the semaphore is created or accessed by a call to sem_open().
     240
     241@subheading NOTES:
     242
     243
     244@page
     245@subsection sem_close - Close a named semaphore
    128246
    129247@subheading CALLING SEQUENCE:
     
    132250@example
    133251int sem_close(
    134 );
    135 @end example
    136 @end ifset
    137 
    138 @ifset is-Ada
    139 @end ifset
    140 
    141 @subheading STATUS CODES:
    142 
    143 @table @b
    144 @item E
    145 The
    146 
    147 @end table
    148 
    149 @subheading DESCRIPTION:
    150 
    151 @subheading NOTES:
    152 
    153 @page
    154 @subsection sem_unlink -
     252  sem_t *sem_close
     253);
     254@end example
     255@end ifset
     256
     257@ifset is-Ada
     258@end ifset
     259
     260@subheading STATUS CODES:
     261
     262@table @b
     263@item EACCES
     264The semaphore argument is  not a valid semaphore descriptor.
     265
     266@item ENOSYS
     267The function sem_close is not supported by this implementation.
     268
     269@end table
     270
     271@subheading DESCRIPTION:
     272The sem_close() function is used to indicate that the calling process is finished
     273using the named semaphore indicated by sem.  The function sem_close deallocates
     274any system resources that were previously allocated by a sem_open system call.  If
     275sem_close() completes successfully it returns a 1, otherwise a value of -1 is
     276return and errno is set.
     277
     278@subheading NOTES:
     279
     280@page
     281@subsection sem_unlink - Unlink a semaphore
    155282
    156283@subheading CALLING SEQUENCE:
     
    159286@example
    160287int sem_unlink(
    161 );
    162 @end example
    163 @end ifset
    164 
    165 @ifset is-Ada
    166 @end ifset
    167 
    168 @subheading STATUS CODES:
    169 
    170 @table @b
    171 @item E
    172 The
    173 
    174 @end table
    175 
    176 @subheading DESCRIPTION:
    177 
    178 @subheading NOTES:
    179 
    180 @page
    181 @subsection sem_wait -
     288  const char *name
     289);
     290@end example
     291@end ifset
     292
     293@ifset is-Ada
     294@end ifset
     295
     296@subheading STATUS CODES:
     297
     298@table @b
     299@item EACCESS
     300Permission is denied to unlink a semaphore.
     301
     302@item ENAMETOOLONG
     303The length of the strong  name exceed NAME_MAX while POSIX_NO_TRUNC is in effect.
     304
     305@item ENOENT
     306The name of the semaphore does not exist.
     307
     308@item ENOSPC
     309There is insufficient space for the creation of a new named semaphore.
     310
     311@item ENOSYS
     312The function sem_unlink is not supported by this implementation.
     313
     314@end table
     315
     316@subheading DESCRIPTION:
     317The sem_unlink() function shall remove the semaphore name by the string name. If
     318a process is currently  accessing the name semaphore, the sem_unlink command has
     319no effect. If one or more processes have the semaphore open when the sem_unlink
     320function is called, the destruction of semaphores shall be postponed until all
     321reference to semaphore are destroyed by calls to sem_close, _exit(), or exec. 
     322After all references have been destroyed, it returns immediately. 
     323
     324If the termination is successful, the function shall return 0.  Otherwise, a -1
     325is returned and the errno is set.
     326
     327@subheading NOTES:
     328
     329@page
     330@subsection sem_wait - Wait on a Semaphore
    182331
    183332@subheading CALLING SEQUENCE:
     
    186335@example
    187336int sem_wait(
    188 );
    189 @end example
    190 @end ifset
    191 
    192 @ifset is-Ada
    193 @end ifset
    194 
    195 @subheading STATUS CODES:
    196 
    197 @table @b
    198 @item E
    199 The
    200 
    201 @end table
    202 
    203 @subheading DESCRIPTION:
    204 
    205 @subheading NOTES:
    206 
    207 @page
    208 @subsection sem_trywait -
     337  sem_t *sem
     338);
     339@end example
     340@end ifset
     341
     342@ifset is-Ada
     343@end ifset
     344
     345@subheading STATUS CODES:
     346
     347@table @b
     348@item EINVAL
     349The "sem" argument does not refer to a valid semaphore
     350
     351@end table
     352
     353@subheading DESCRIPTION:
     354This function attempts to lock a semaphore specified by @code{sem}.  If the
     355semaphore is available, then the semaphore is locked (i.e., the semaphore
     356value is decremented).  If the semaphore is unavailable (i.e., the semaphore
     357value is zero), then the function will block until the semaphore becomes
     358available.  It will then successfully lock the semaphore.  The semaphore
     359remains locked until released by a @code{sem_post()} call.
     360
     361If the call is unsuccessful, then the function returns -1 and sets errno to the
     362appropriate error code.
     363
     364@subheading NOTES:
     365Multiprocessing is not supported in this implementation.
     366
     367@page
     368@subsection sem_trywait - Non-blocking Wait on a Semaphore
    209369
    210370@subheading CALLING SEQUENCE:
     
    213373@example
    214374int sem_trywait(
    215 );
    216 @end example
    217 @end ifset
    218 
    219 @ifset is-Ada
    220 @end ifset
    221 
    222 @subheading STATUS CODES:
    223 
    224 @table @b
    225 @item E
    226 The
    227 
    228 @end table
    229 
    230 @subheading DESCRIPTION:
    231 
    232 @subheading NOTES:
    233 
    234 @page
    235 @subsection sem_post -
     375  sem_t *sem
     376);
     377@end example
     378@end ifset
     379
     380@ifset is-Ada
     381@end ifset
     382
     383@subheading STATUS CODES:
     384
     385@table @b
     386@item EAGAIN
     387The semaphore is not available (i.e., the semaphore value is zero), so the
     388semaphore could not be locked.
     389
     390@item EINVAL
     391The @code{sem} argument does not refewr to a valid semaphore
     392
     393@end table
     394
     395@subheading DESCRIPTION:
     396This function attempts to lock a semaphore specified by @code{sem}.  If the
     397semaphore is available, then the semaphore is locked (i.e., the semaphore
     398value is decremented) and the function returns a value of 0.  The semaphore
     399remains locked until released by a @code{sem_post()} call.  If the semaphore
     400is unavailable (i.e., the semaphore value is zero), then the function will
     401return a value of -1 immediately and set @code{errno} to EAGAIN.
     402
     403If the call is unsuccessful, then the function returns -1 and sets
     404@code{errno} to the appropriate error code.
     405
     406@subheading NOTES:
     407Multiprocessing is not supported in this implementation.
     408
     409@page
     410@subsection sem_timedwait - Wait on a Semaphore for a Specified Time
     411
     412@subheading CALLING SEQUENCE:
     413
     414@ifset is-C
     415@example
     416int sem_timedwait(
     417  sem_t *sem,
     418  const struct timespec *timeout
     419);
     420@end example
     421@end ifset
     422
     423@ifset is-Ada
     424@end ifset
     425
     426@subheading STATUS CODES:
     427
     428@table @b
     429@item EAGAIN
     430The semaphore is not available (i.e., the semaphore value is zero), so the
     431semaphore could not be locked.
     432
     433@item EINVAL
     434The @code{sem} argument does not refewr to a valid semaphore
     435
     436@end table
     437
     438@subheading DESCRIPTION:
     439This function attemtps to lock a semaphore specified by @code{sem}, and will
     440wait for the semaphore for an interval specified by @code{timeout}.  If the
     441semaphore is available, then the semaphore is locked (i.e., the semaphore
     442value is decremented) and the function returns a value of 0.  The semaphore
     443remains locked until released by a @code{sem_post()} call.  If the semaphore
     444is unavailable, then the function will wait for the semaphore to become
     445available for the amount of time specified by @code{timeout}.
     446
     447If the semaphore does not become available within the interval specified by
     448@code{timeout}, then the function returns -1 and sets @code{errno} to EAGAIN.
     449If any other error occurs, the function returns -1 and sets @code{errno} to
     450the appropriate error code.
     451
     452@subheading NOTES:
     453Multiprocessing is not supported in this implementation.
     454
     455@page
     456@subsection sem_post - Unlock a Semaphore
    236457
    237458@subheading CALLING SEQUENCE:
     
    240461@example
    241462int sem_post(
    242 );
    243 @end example
    244 @end ifset
    245 
    246 @ifset is-Ada
    247 @end ifset
    248 
    249 @subheading STATUS CODES:
    250 
    251 @table @b
    252 @item E
    253 The
    254 
    255 @end table
    256 
    257 @subheading DESCRIPTION:
    258 
    259 @subheading NOTES:
    260 
    261 @page
    262 @subsection sem_getvalue -
     463  sem_t *sem
     464);
     465@end example
     466@end ifset
     467
     468@ifset is-Ada
     469@end ifset
     470
     471@subheading STATUS CODES:
     472
     473@table @b
     474@item EINVAL
     475The @code{sem} argument does not refer to a valid semaphore
     476
     477@end table
     478
     479@subheading DESCRIPTION:
     480This function attempts to release the semaphore specified by @code{sem}.  If
     481other tasks are waiting on the semaphore, then one of those tasks (which one
     482depends on the scheduler being used) is allowed to lock the semaphore and
     483return from its @code{sem_wait()}, @code{sem_trywait()}, or
     484@code{sem_timedwait()} call.  If there are no other tasks waiting on the
     485semaphore, then the semaphore value is simply incremented.  @code{sem_post()}
     486returns 0 upon successful completion.
     487
     488If an error occurs, the function returns -1 and sets @code{errno} to the
     489appropriate error code.
     490
     491@subheading NOTES:
     492Multiprocessing is not supported in this implementation.
     493
     494@page
     495@subsection sem_getvalue - Get the value of a semaphore
    263496
    264497@subheading CALLING SEQUENCE:
     
    267500@example
    268501int sem_getvalue(
    269 );
    270 @end example
    271 @end ifset
    272 
    273 @ifset is-Ada
    274 @end ifset
    275 
    276 @subheading STATUS CODES:
    277 
    278 @table @b
    279 @item E
    280 The
    281 
    282 @end table
    283 
    284 @subheading DESCRIPTION:
    285 
    286 @subheading NOTES:
    287 
     502  sem_t *sem,
     503  int *sval
     504);
     505@end example
     506@end ifset
     507
     508@ifset is-Ada
     509@end ifset
     510
     511@subheading STATUS CODES:
     512
     513@table @b
     514@item EINVAL
     515The "sem" argument does not refer to a valid semaphore
     516
     517@item ENOSYS
     518The function sem_getvalue is not supported by this implementation
     519
     520@end table
     521
     522@subheading DESCRIPTION:
     523The sem_getvalue functions sets the location referenced by the "sval" argument
     524to the value of the semaphore without affecting the state of the semaphore. The
     525updated value represents a semaphore value that occurred at some point during
     526the call, but is not necessarily the actual value of the semaphore when it
     527returns to the calling process.
     528 
     529If "sem" is locked, the value returned by sem_getvalue will be zero or a
     530negative number whose absolute value is the number of processes waiting for the
     531semaphore at some point during the call.
     532
     533@subheading NOTES:
     534If the functions completes successfully, it shall return a value of zero.
     535Otherwise, it shall return a value of -1 and set "errno" to specify the error
     536that occurred.
Note: See TracChangeset for help on using the changeset viewer.