VxWorks Reference Manual : Libraries
mqPxLib - message queue library (POSIX)
mqPxLibInit( ) - initialize the POSIX message queue library
mq_open( ) - open a message queue (POSIX)
mq_receive( ) - receive a message from a message queue (POSIX)
mq_send( ) - send a message to a message queue (POSIX)
mq_close( ) - close a message queue (POSIX)
mq_unlink( ) - remove a message queue (POSIX)
mq_notify( ) - notify a task that a message is available on a queue (POSIX)
mq_setattr( ) - set message queue attributes (POSIX)
mq_getattr( ) - get message queue attributes (POSIX)
This library implements the message-queue interface defined in the POSIX 1003.1b standard, as an alternative to the VxWorks-specific message queue design in msgQLib. These message queues are accessed through names; each message queue supports multiple sending and receiving tasks.
The message queue interface imposes a fixed upper bound on the size of messages that can be sent to a specific message queue. The size is set on an individual queue basis. The value may not be changed dynamically.
This interface allows a task be notified asynchronously of the availability of a message on the queue. The purpose of this feature is to let the task to perform other functions and yet still be notified that a message has become available on the queue.
The mq_close( ) call terminates a message queue descriptor and deallocates any associated memory. When deleting message queue descriptors, take care to avoid interfering with other tasks that are using the same descriptor. Tasks should only close message queue descriptors that the same task has opened successfully.
The routines in this library conform to POSIX 1003.1b.
mqueue.h
mqPxLib, POSIX 1003.1b document, msgQLib, VxWorks Programmer's Guide: Basic OS
mqPxLibInit( ) - initialize the POSIX message queue library
int mqPxLibInit ( int hashSize /* log2 of number of hash buckets */ )
This routine initializes the POSIX message queue facility. If hashSize is 0, the default value is taken from MQ_HASH_SIZE_DEFAULT.
OK or ERROR.
mq_open( ) - open a message queue (POSIX)
mqd_t mq_open ( const char * mqName, /* name of queue to open */ int oflags /* open flags */ )
This routine establishes a connection between a named message queue and the calling task. After a call to mq_open( ), the task can reference the message queue using the address returned by the call. The message queue remains usable until the queue is closed by a successful call to mq_close( ).
The oflags argument controls whether the message queue is created or merely accessed by the mq_open( ) call. The following flag bits can be set in oflags:
- O_RDONLY
- Open the message queue for receiving messages. The task can use the returned message queue descriptor with mq_receive( ), but not mq_send( ).
- O_WRONLY
- Open the message queue for sending messages. The task can use the returned message queue descriptor with mq_send( ), but not mq_receive( ).
- O_RDWR
- Open the queue for both receiving and sending messages. The task can use any of the functions allowed for O_RDONLY and O_WRONLY.
Any combination of the remaining flags can be specified in oflags:
- O_CREAT
- This flag is used to create a message queue if it does not already exist. If O_CREAT is set and the message queue already exists, then O_CREAT has no effect except as noted below under O_EXCL. Otherwise, mq_open( ) creates a message queue. The O_CREAT flag requires a third and fourth argument: mode, which is of type mode_t, and pAttr, which is of type pointer to an mq_attr structure. The value of mode has no effect in this implementation. If pAttr is NULL, the message queue is created with implementation-defined default message queue attributes. If pAttr is non-NULL, the message queue attributes mq_maxmsg and mq_msgsize are set to the values of the corresponding members in the mq_attr structure referred to by pAttr; if either attribute is less than or equal to zero, an error is returned and errno is set to EINVAL.
- O_EXCL
- This flag is used to test whether a message queue already exists. If O_EXCL and O_CREAT are set, mq_open( ) fails if the message queue name exists.
- O_NONBLOCK
- The setting of this flag is associated with the open message queue descriptor and determines whether a mq_send( ) or mq_receive( ) will wait for resources or messages that are not currently available, or fail with errno set to EAGAIN.
The mq_open( ) call does not add or remove messages from the queue.
Some POSIX functionality is not yet supported:
- A message queue cannot be closed with calls to _exit( ) or exec( ).
- A message queue cannot be implemented as a file.
- Message queue names will not appear in the file system.
A message queue descriptor, otherwise -1 (ERROR).
EEXIST, EINVAL, ENOENT, ENOSPC
mqPxLib, mq_send( ), mq_receive( ), mq_close( ), mq_setattr( ), mq_getattr( ), mq_unlink( )
mq_receive( ) - receive a message from a message queue (POSIX)
ssize_t mq_receive ( mqd_t mqdes, /* message queue descriptor */ void * pMsg, /* buffer to receive message */ size_t msgLen, /* size of buffer, in bytes */ int * pMsgPrio /* if not NULL, priority of message */ )
This routine receives the oldest of the highest priority message from the message queue specified by mqdes. If the size of the buffer in bytes, specified by the msgLen argument, is less than the mq_msgsize attribute of the message queue, mq_receive( ) will fail and return an error. Otherwise, the selected message is removed from the queue and copied to pMsg.
If pMsgPrio is not NULL, the priority of the selected message will be stored in pMsgPrio.
If the message queue is empty and O_NONBLOCK is not set in the message queue's description, mq_receive( ) will block until a message is added to the message queue, or until it is interrupted by a signal. If more than one task is waiting to receive a message when a message arrives at an empty queue, the task of highest priority that has been waiting the longest will be selected to receive the message. If the specified message queue is empty and O_NONBLOCK is set in the message queue's description, no message is removed from the queue, and mq_receive( ) returns an error.
The length of the selected message in bytes, otherwise -1 (ERROR).
EAGAIN, EBADF, EMSGSIZE, EINTR
mq_send( ) - send a message to a message queue (POSIX)
int mq_send ( mqd_t mqdes, /* message queue descriptor */ const void * pMsg, /* message to send */ size_t msgLen, /* size of message, in bytes */ int msgPrio /* priority of message */ )
This routine adds the message pMsg to the message queue mqdes. The msgLen parameter specifies the length of the message in bytes pointed to by pMsg. The value of pMsg must be less than or equal to the mq_msgsize attribute of the message queue, or mq_send( ) will fail.
If the message queue is not full, mq_send( ) will behave as if the message is inserted into the message queue at the position indicated by the msgPrio argument. A message with a higher numeric value for msgPrio is inserted before messages with a lower value. The value of msgPrio must be less than or equal to 31.
If the specified message queue is full and O_NONBLOCK is not set in the message queue's, mq_send( ) will block until space becomes available to queue the message, or until it is interrupted by a signal. The priority scheduling option is supported in the event that there is more than one task waiting on space becoming available. If the message queue is full and O_NONBLOCK is set in the message queue's description, the message is not queued, and mq_send( ) returns an error.
This routine can be called by interrupt service routines as well as by tasks. This is one of the primary means of communication between an interrupt service routine and a task. If mq_send( ) is called from an interrupt service routine, it will behave as if the O_NONBLOCK flag were set.
0 (OK), otherwise -1 (ERROR).
EAGAIN, EBADF, EINTR, EINVAL, EMSGSIZE
mqPxLib, mq_receive( )
mq_close( ) - close a message queue (POSIX)
int mq_close ( mqd_t mqdes /* message queue descriptor */ )
This routine is used to indicate that the calling task is finished with the specified message queue mqdes. The mq_close( ) call deallocates any system resources allocated by the system for use by this task for its message queue. The behavior of a task that is blocked on either a mq_send( ) or mq_receive( ) is undefined when mq_close( ) is called. The mqdes parameter will no longer be a valid message queue ID.
0 (OK) if the message queue is closed successfully, otherwise -1 (ERROR).
EBADF
mq_unlink( ) - remove a message queue (POSIX)
int mq_unlink ( const char * mqName /* name of message queue */ )
This routine removes the message queue named by the pathname mqName. After a successful call to mq_unlink( ), a call to mq_open( ) on the same message queue will fail if the flag O_CREAT is not set. If one or more tasks have the message queue open when mq_unlink( ) is called, removal of the message queue is postponed until all references to the message queue have been closed.
0 (OK) if the message queue is unlinked successfully, otherwise -1 (ERROR).
ENOENT
mqPxLib, mq_close( ), mq_open( )
mq_notify( ) - notify a task that a message is available on a queue (POSIX)
int mq_notify ( mqd_t mqdes, /* message queue descriptor */ const struct sigevent * pNotification /* real-time signal */ )
If pNotification is not NULL, this routine attaches the specified pNotification request by the calling task to the specified message queue mqdes associated with the calling task. The real-time signal specified by pNotification will be sent to the task when the message queue changes from empty to non-empty. If a task has already attached a notification request to the message queue, all subsequent attempts to attach a notification to the message queue will fail. A task is able to attach a single notification to each mqdes it has unless another task has already attached one.
If pNotification is NULL and the task has previously attached a notification request to the message queue, the attached notification request is detached and the queue is available for another task to attach a notification request.
If a notification request is attached to a message queue and any task is blocked in mq_receive( ) waiting to receive a message when a message arrives at the queue, then the appropriate mq_receive( ) will be completed and the notification request remains pending.
0 (OK) if successful, otherwise -1 (ERROR).
EBADF, EBUSY, EINVAL
mqPxLib, mq_open( ), mq_send( )
mq_setattr( ) - set message queue attributes (POSIX)
int mq_setattr ( mqd_t mqdes, /* message queue descriptor */ const struct mq_attr * pMqStat, /* new attributes */ struct mq_attr * pOldMqStat /* old attributes */ )
This routine sets attributes associated with the specified message queue mqdes.
The message queue attributes corresponding to the following members defined in the mq_attr structure are set to the specified values upon successful completion of the call:
- mq_flags
- The value the O_NONBLOCK flag.
If pOldMqStat is non-NULL, mq_setattr( ) will store, in the location referenced by pOldMqStat, 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.
0 (OK) if attributes are set successfully, otherwise -1 (ERROR).
EBADF
mqPxLib, mq_open( ), mq_send( ), mq_getattr( )
mq_getattr( ) - get message queue attributes (POSIX)
int mq_getattr ( mqd_t mqdes, /* message queue descriptor */ struct mq_attr * pMqStat /* buffer in which to return attributes */ )
This routine gets status information and attributes associated with a specified message queue mqdes. Upon return, the following members of the mq_attr structure referenced by pMqStat will contain the values set when the message queue was created but with modifications made by subsequent calls to mq_setattr( ):
- mq_flags
- May be modified by mq_setattr( ).
The following were set at message queue creation:
- mq_maxmsg
- Maximum number of messages.
- mq_msgsize
- Maximum message size.
- mq_curmsgs
- The number of messages currently in the queue.
0 (OK) if message attributes can be determined, otherwise -1 (ERROR).
EBADF
mqPxLib, mq_open( ), mq_send( ), mq_setattr( )