Named Message Queue Interfaces
NuttX supports POSIX named message queues for inter-task communication. Any task may send or receive messages on named message queues. Interrupt handlers may send messages via named message queues.
-
mqd_t mq_open(const char *mqName, int oflags, ...)
Establishes a connection between a named message queue and the calling task. After a successful call of mq_open(), the task can reference the message queue using the address returned by the call. The message queue remains usable until it is closed by a successful call to mq_close().
- Parameters:
mqName – Name of the queue to open
oflags –
Open flags. These may be any combination of:
O_RDONLY
. Open for read access.O_WRONLY
. Open for write access.O_RDWR
. Open for both read & write access.O_CREAT
. Create message queue if it does not already exist.O_EXCL
. Name must not exist when opened.O_NONBLOCK
. Don’t wait for data.
... –
Optional parameters. When the O_CREAT flag is specified, POSIX requires that a third and fourth parameter be supplied:
mode
. The mode parameter is of type mode_t. In the POSIX specification, this mode value provides file permission bits for the message queue. This parameter is required but not used in the present implementation.attr
. A pointer to an mq_attr that is provided to initialize. the message queue. If attr is NULL, then the messages queue is created with implementation-defined default message queue attributes. If attr is non-NULL, then the message queue mq_maxmsg attribute is set to the corresponding value when the queue is created. The mq_maxmsg attribute determines the maximum number of messages that can be queued before addition attempts to send messages on the message queue fail or cause the sender to block; the mq_msgsize attribute determines the maximum size of a message that can be sent or received. Other elements of attr are ignored (i.e, set to default message queue attributes).
- Returns:
A message queue descriptor or -1 (
ERROR
)
POSIX Compatibility: Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include:
The mq_msgsize attributes determines the maximum size of a message that may be sent or received. In the present implementation, this maximum message size is limited at 22 bytes.
-
int mq_close(mqd_t mqdes)
Used to indicate that the calling task is finished with the specified message queued
mqdes
. Themq_close()
deallocates any system resources allocated by the system for use by this task for its message queue.If the calling task has attached a notification request to the message queue via this
mqdes
(seemq_notify()
), this attachment will be removed and the message queue is available for another task to attach for notification.- Parameters:
mqdes – Message queue descriptor.
- Returns:
0 (
OK
) if the message queue is closed successfully, otherwise, -1 (ERROR
).
Assumptions/Limitations:
The behavior of a task that is blocked on either a
mq_send()
ormq_receive()
is undefined whenmq_close()
is called.The result of using this message queue descriptor after successful return from
mq_close()
is undefined.
POSIX Compatibility: Comparable to the POSIX interface of the same name.
-
int mq_unlink(const char *mqName)
Removes the message queue named by “mqName.” 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.- Parameters:
mqName – Name of the message queue
POSIX Compatibility: Comparable to the POSIX interface of the same name.
-
int mq_send(mqd_t mqdes, const void *msg, size_t msglen, int prio)
Adds the specified message,
msg
, to the message queue,mqdes
. Themsglen
parameter specifies the length of the message in bytes pointed to bymsg
. This length must not exceed the maximum message length from themq_getattr()
.If the message queue is not full,
mq_send()
will place themsg
in the message queue at the position indicated by theprio
argument. Messages with higher priority will be inserted before lower priority messages The value ofprio
must not exceedMQ_PRIO_MAX
.If the specified message queue is full and
O_NONBLOCK
is not set in the message queue, thenmq_send()
will block until space becomes available to the queue the message.If the message queue is full and
NON_BLOCK
is set, the message is not queued andERROR
is returned.NOTE:
mq_send()
may be called from an interrupt handler. However, it behaves differently when called from the interrupt level:It does not check the size of the queue. It will always post the message, even if there are already too many messages in queue. This is because the interrupt handler does not have the option of waiting for the message queue to become non-full.
It doesn’t allocate new memory (because you cannot allocate memory from an interrupt handler). Instead, there is a pool of pre-allocated message structures that may be used just for sending messages from interrupt handlers. The number of such pre-allocated messages is set by the
PREALLOC_MQ_IRQ_MSGS
configuration parameter.
- Parameters:
mqdes – Message queue descriptor.
msg – Message to send.
msglen – The length of the message in bytes.
prio – The priority of the message.
- Returns:
On success,
mq_send()
returns 0 (OK
); on error, -1 (ERROR
) is returned, with`errno
<#ErrnoAccess>`__ set to indicate the error:EAGAIN
. The queue was empty, and theO_NONBLOCK
flag was set for the message queue description referred to bymqdes
.EINVAL
. Eithermsg
ormqdes
isNULL
or the value ofprio
is invalid.EPERM
. Message queue opened not opened for writing.EMSGSIZE
.msglen
was greater than themaxmsgsize
attribute of the message queue.EINTR
. The call was interrupted by a signal handler.
POSIX Compatibility: Comparable to the POSIX interface of the same name.
-
int mq_timedsend(mqd_t mqdes, const char *msg, size_t msglen, int prio, const struct timespec *abstime);
Adds the specified message,
msg
, to the message queue,mqdes
. Themsglen
parameter specifies the length of the message in bytes pointed to bymsg
. This length must not exceed the maximum message length from themq_getattr()
.If the message queue is not full,
mq_timedsend()
will place themsg
in the message queue at the position indicated by theprio
argument. Messages with higher priority will be inserted before lower priority messages The value ofprio
must not exceedMQ_PRIO_MAX
.If the specified message queue is full and
O_NONBLOCK
is not set in the message queue, thenmq_send()
will block until space becomes available to the queue the message or until a timeout occurs.mq_timedsend()
behaves just likemq_send()
, except that if the queue is full and theO_NONBLOCK
flag is not enabled for the message queue description, thenabstime
points to a structure which specifies a ceiling on the time for which the call will block. This ceiling is an absolute timeout in seconds and nanoseconds since the Epoch (midnight on the morning of 1 January 1970).If the message queue is full, and the timeout has already expired by the time of the call,
mq_timedsend()
returns immediately.- Parameters:
mqdes – Message queue descriptor.
msg – Message to send.
msglen – The length of the message in bytes.
prio – The priority of the message.
- Returns:
On success,
mq_send()
returns 0 (OK
); on error, -1 (ERROR
) is returned, with`errno
<#ErrnoAccess>`__ set to indicate the error:EAGAIN
. The queue was empty, and theO_NONBLOCK
flag was set for the message queue description referred to bymqdes
.EINVAL
. Eithermsg
ormqdes
isNULL
or the value ofprio
is invalid.EPERM
. Message queue opened not opened for writing.EMSGSIZE
.msglen
was greater than themaxmsgsize
attribute of the message queue.EINTR
. The call was interrupted by a signal handler.
POSIX Compatibility: Comparable to the POSIX interface of the same name.
-
ssize_t mq_receive(mqd_t mqdes, void *msg, size_t msglen, int *prio)
Receives the oldest of the highest priority messages from the message queue specified by
mqdes
. If the size of the buffer in bytes,msgLen
, is less than themq_msgsize
attribute of the message queue,mq_receive()
will return an error. Otherwise, the selected message is removed from the queue and copied tomsg
.If the message queue is empty and
O_NONBLOCK
was not set,mq_receive()
will block until a message is added to the message queue. If more than one task is waiting to receive a message, only the task with the highest priority that has waited the longest will be unblocked.If the queue is empty and
O_NONBLOCK
is set,ERROR
will be returned.- Parameters:
mqdes – Message Queue Descriptor.
msg – Buffer to receive the message.
msglen – Size of the buffer in bytes.
prio – If not NULL, the location to store message priority.
- Returns:
On success, the length of the selected message in bytes is returned. On failure, -1 (
ERROR
) is returned and the`errno
<#ErrnoAccess>`__ is set appropriately:EAGAIN
The queue was empty and theO_NONBLOCK
flag was set for the message queue description referred to bymqdes
.EPERM
Message queue opened not opened for reading.EMSGSIZE
msglen
was less than themaxmsgsize
attribute of the message queue.EINTR
The call was interrupted by a signal handler.EINVAL
Invalidmsg
ormqdes
POSIX Compatibility: Comparable to the POSIX interface of the same name.
-
ssize_t mq_timedreceive(mqd_t mqdes, void *msg, size_t msglen, int *prio, const struct timespec *abstime);
Receives the oldest of the highest priority messages from the message queue specified by
mqdes
. If the size of the buffer in bytes,msgLen
, is less than themq_msgsize
attribute of the message queue,mq_timedreceive()
will return an error. Otherwise, the selected message is removed from the queue and copied tomsg
.If the message queue is empty and
O_NONBLOCK
was not set,mq_timedreceive()
will block until a message is added to the message queue (or until a timeout occurs). If more than one task is waiting to receive a message, only the task with the highest priority that has waited the longest will be unblocked.mq_timedreceive()
behaves just likemq_receive()
, except that if the queue is empty and theO_NONBLOCK
flag is not enabled for the message queue description, thenabstime
points to a structure which specifies a ceiling on the time for which the call will block. This ceiling is an absolute timeout in seconds and nanoseconds since the Epoch (midnight on the morning of 1 January 1970).If no message is available, and the timeout has already expired by the time of the call,
mq_timedreceive()
returns immediately.- Parameters:
mqdes – Message Queue Descriptor.
msg – Buffer to receive the message.
msglen – Size of the buffer in bytes.
prio – If not NULL, the location to store message priority.
abstime – The absolute time to wait until a timeout is declared.
- Returns:
On success, the length of the selected message in bytes is returned. On failure, -1 (
ERROR
) is returned and the`errno
<#ErrnoAccess>`__ is set appropriately:EAGAIN
: The queue was empty and theO_NONBLOCK
flag was set for the message queue description referred to bymqdes
.EPERM
: Message queue opened not opened for reading.EMSGSIZE
:msglen
was less than themaxmsgsize
attribute of the message queue.EINTR
: The call was interrupted by a signal handler.EINVAL
: Invalidmsg
ormqdes
orabstime
ETIMEDOUT
: The call timed out before a message could be transferred.
POSIX Compatibility: Comparable to the POSIX interface of the same name.
-
int mq_notify(mqd_t mqdes, FAR const struct sigevent *notification)
If the
notification
input parameter is notNULL
, this function connects the task with the message queue such that the specified signal will be sent to the task whenever the message queue changes from empty to non-empty. One notification can be attached to a message queue.If
notification
; isNULL
, the attached notification is detached (if it was held by the calling task) and the queue is available to attach another notification.When the notification is sent to the registered task, its registration will be removed. The message queue will then be available for registration.
- Parameters:
mqdes – Message queue descriptor
notification –
Real-time signal structure containing:
sigev_notify
. Should be SIGEV_SIGNAL (but actually ignored)sigev_signo
. The signo to use for the notificationsigev_value
. Value associated with the signal
- Returns:
On success
mq_notify()
returns 0; on error, -1 is returned, witherrno
set to indicate the error:EBADF
. The descriptor specified inmqdes
is invalid.EBUSY
. Another process has already registered to receive notification for this message queue.EINVAL
.sevp->sigev_notify
is not one of the permitted values; orsevp->sigev_notify
isSIGEV_SIGNAL
andsevp->sigev_signo
is not a valid signal number.ENOMEM
. Insufficient memory.
POSIX Compatibility: Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include:
The notification signal will be sent to the registered task even if another task is waiting for the message queue to become non-empty. This is inconsistent with the POSIX specification which states, “If a process has registered for notification of message arrival at a message queue and some process is blocked in
mq_receive
waiting to receive a message when a message arrives at the queue, the arriving message will satisfy the appropriatemq_receive()
… The resulting behavior is as if the message queue remains empty, and no notification will be sent.”
-
int mq_setattr(mqd_t mqdes, const struct mq_attr *mqStat, struct mq_attr *oldMqStat);
Sets the attributes associated with the specified message queue “mqdes.” Only the “O_NONBLOCK” bit of the “mq_flags” can be changed.
If
oldMqStat
is non-null, mq_setattr() will store the previous message queue attributes at that location (just as would have been returned by mq_getattr()).- Parameters:
mqdes – Message queue descriptor
mqStat – New attributes
oldMqState – Old attributes
- Returns:
0 (
OK
) if attributes are set successfully, otherwise -1 (ERROR
).
POSIX Compatibility: Comparable to the POSIX interface of the same name.
-
int mq_getattr(mqd_t mqdes, struct mq_attr *mqStat)
Gets status information and attributes associated with the specified message queue.
- Parameters:
mqdes – Message queue descriptor
mqStat –
Buffer in which to return attributes. The returned attributes include:
mq_maxmsg
. Max number of messages in queue.mq_msgsize
. Max message size.mq_flags
. Queue flags.mq_curmsgs
. Number of messages currently in queue.
- Returns:
0 (
OK
) if attributes provided, -1 (ERROR
) otherwise.
POSIX Compatibility: Comparable to the POSIX interface of the same name.