Xenomai  3.1
Message queues

Cobalt/POSIX message queue services. More...

Collaboration diagram for Message queues:

Functions

mqd_t mq_open (const char *name, int oflags,...)
 
Open a message queue More...
 
int mq_close (mqd_t mqd)
 
Close a message queue More...
 
int mq_unlink (const char *name)
 
Unlink a message queue More...
 
int mq_getattr (mqd_t mqd, struct mq_attr *attr)
 
Get message queue attributes More...
 
int mq_setattr (mqd_t mqd, const struct mq_attr *__restrict__ attr, struct mq_attr *__restrict__ oattr)
 
Set message queue attributes More...
 
int mq_send (mqd_t q, const char *buffer, size_t len, unsigned prio)
 
Send a message to a message queue. More...
 
int mq_timedsend (mqd_t q, const char *buffer, size_t len, unsigned prio, const struct timespec *timeout)
 
Attempt, during a bounded time, to send a message to a message queue. More...
 
ssize_t mq_receive (mqd_t q, char *buffer, size_t len, unsigned *prio)
 
Receive a message from a message queue. More...
 
ssize_t mq_timedreceive (mqd_t q, char *__restrict__ buffer, size_t len, unsigned *__restrict__ prio, const struct timespec *__restrict__ timeout)
 
Attempt, during a bounded time, to receive a message from a message queue. More...
 
int mq_notify (mqd_t mqd, const struct sigevent *evp)
 
Enable notification on message arrival More...
 

Detailed Description

Cobalt/POSIX message queue services.

A message queue allow exchanging data between real-time threads. For a POSIX message queue, maximum message length and maximum number of messages are fixed when it is created with mq_open().

Function Documentation

◆ mq_close()

int mq_close ( mqd_t  mqd)


Close a message queue

This service closes the message queue descriptor mqd. The message queue is destroyed only when all open descriptors are closed, and when unlinked with a call to the mq_unlink() service.

Parameters
mqdmessage queue descriptor.
Return values
0on success;
-1with errno set if:
  • EBADF, mqd is an invalid message queue descriptor;
  • EPERM, the caller context is invalid.
See also
Specification.
Tags
thread-unrestricted, switch-secondary

◆ mq_getattr()

int mq_getattr ( mqd_t  mqd,
struct mq_attr *  attr 
)


Get message queue attributes

This service stores, at the address attr, the attributes of the messages queue descriptor mqd.

The following attributes are set:

  • mq_flags, flags of the message queue descriptor mqd;
  • mq_maxmsg, maximum number of messages in the message queue;
  • mq_msgsize, maximum message size;
  • mq_curmsgs, number of messages currently in the queue.
Parameters
mqdmessage queue descriptor;
attraddress where the message queue attributes will be stored on success.
Return values
0on success;
-1with errno set if:
  • EBADF, mqd is not a valid descriptor.
See also
Specification.
Tags
thread-unrestricted

◆ mq_notify()

int mq_notify ( mqd_t  mqd,
const struct sigevent *  evp 
)


Enable notification on message arrival

If evp is not NULL and is the address of a sigevent structure with the sigev_notify member set to SIGEV_SIGNAL, the current thread will be notified by a signal when a message is sent to the message queue mqd, the queue is empty, and no thread is blocked in call to mq_receive() or mq_timedreceive(). After the notification, the thread is unregistered.

If evp is NULL or the sigev_notify member is SIGEV_NONE, the current thread is unregistered.

Only one thread may be registered at a time.

If the current thread is not a Cobalt thread (created with pthread_create()), this service fails.

Parameters
mqdmessage queue descriptor;
evppointer to an event notification structure.
Return values
0on success;
-1with errno set if:
  • EINVAL, evp is invalid;
  • EPERM, the caller context is invalid;
  • EBADF, mqd is not a valid message queue descriptor;
  • EBUSY, another thread is already registered.
See also
Specification.
Tags
xthread-only, switch-primary

◆ mq_open()

mqd_t mq_open ( const char *  name,
int  oflags,
  ... 
)


Open a message queue

This service opens the message queue named name.

One of the following values should be set in oflags:

  • O_RDONLY, meaning that the returned queue descriptor may only be used for receiving messages;
  • O_WRONLY, meaning that the returned queue descriptor may only be used for sending messages;
  • O_RDWR, meaning that the returned queue descriptor may be used for both sending and receiving messages.

If no message queue named name exists, and oflags has the O_CREAT bit set, the message queue is created by this function, taking two more arguments:

  • a mode argument, of type mode_t, currently ignored;
  • an attr argument, pointer to an mq_attr structure, specifying the attributes of the new message queue.

If oflags has the two bits O_CREAT and O_EXCL set and the message queue alread exists, this service fails.

If the O_NONBLOCK bit is set in oflags, the mq_send(), mq_receive(), mq_timedsend() and mq_timedreceive() services return -1 with errno set to EAGAIN instead of blocking their caller.

The following arguments of the mq_attr structure at the address attr are used when creating a message queue:

  • mq_maxmsg is the maximum number of messages in the queue (128 by default);
  • mq_msgsize is the maximum size of each message (128 by default).

name may be any arbitrary string, in which slashes have no particular meaning. However, for portability, using a name which starts with a slash and contains no other slash is recommended.

Parameters
namename of the message queue to open;
oflagsflags.
Returns
a message queue descriptor on success;
-1 with errno set if:
  • ENAMETOOLONG, the length of the name argument exceeds 64 characters;
  • EEXIST, the bits O_CREAT and O_EXCL were set in oflags and the message queue already exists;
  • ENOENT, the bit O_CREAT is not set in oflags and the message queue does not exist;
  • ENOSPC, allocation of system memory failed, or insufficient memory available from the system heap to create the queue, try increasing CONFIG_XENO_OPT_SYS_HEAPSZ;
  • EPERM, attempting to create a message queue from an invalid context;
  • EINVAL, the attr argument is invalid;
  • EMFILE, too many descriptors are currently open.
  • EAGAIN, no registry slot available, check/raise CONFIG_XENO_OPT_REGISTRY_NRSLOTS.
See also
Specification.
Tags
thread-unrestricted, switch-secondary

◆ mq_receive()

ssize_t mq_receive ( mqd_t  q,
char *  buffer,
size_t  len,
unsigned *  prio 
)


Receive a message from a message queue.

If the message queue fd is not empty and if len is greater than the mq_msgsize of the message queue, this service copies, at the address buffer, the queued message with the highest priority.

If the queue is empty and the flag O_NONBLOCK is not set for the descriptor fd, the calling thread is suspended until some message is sent to the queue. If the queue is empty and the flag O_NONBLOCK is set for the descriptor fd, this service returns immediately a value of -1 with errno set to EAGAIN.

Parameters
qthe queue descriptor;
bufferthe address where the received message will be stored on success;
lenbuffer length;
prioaddress where the priority of the received message will be stored on success.
Returns
the message length, and copy a message at the address buffer on success;
-1 with no message unqueued and errno set if:
  • EBADF, fd is not a valid descriptor open for reading;
  • EMSGSIZE, the length len is lesser than the message queue mq_msgsize attribute;
  • EAGAIN, the queue is empty, and the flag O_NONBLOCK is set for the descriptor fd;
  • EPERM, the caller context is invalid;
  • EINTR, the service was interrupted by a signal.
See also
Specification.
Tags
xthread-only, switch-primary

◆ mq_send()

int mq_send ( mqd_t  q,
const char *  buffer,
size_t  len,
unsigned  prio 
)


Send a message to a message queue.

If the message queue fd is not full, this service sends the message of length len pointed to by the argument buffer, with priority prio. A message with greater priority is inserted in the queue before a message with lower priority.

If the message queue is full and the flag O_NONBLOCK is not set, the calling thread is suspended until the queue is not full. If the message queue is full and the flag O_NONBLOCK is set, the message is not sent and the service returns immediately a value of -1 with errno set to EAGAIN.

Parameters
qmessage queue descriptor;
bufferpointer to the message to be sent;
lenlength of the message;
priopriority of the message.
Returns
0 and send a message on success;
-1 with no message sent and errno set if:
  • EBADF, fd is not a valid message queue descriptor open for writing;
  • EMSGSIZE, the message length len exceeds the mq_msgsize attribute of the message queue;
  • EAGAIN, the flag O_NONBLOCK is set for the descriptor fd and the message queue is full;
  • EPERM, the caller context is invalid;
  • EINTR, the service was interrupted by a signal.
See also
Specification.
Tags
xthread-only, switch-primary

◆ mq_setattr()

int mq_setattr ( mqd_t  mqd,
const struct mq_attr *__restrict__  attr,
struct mq_attr *__restrict__  oattr 
)


Set message queue attributes

This service sets the flags of the mqd descriptor to the value of the member mq_flags of the mq_attr structure pointed to by attr.

The previous value of the message queue attributes are stored at the address oattr if it is not NULL.

Only setting or clearing the O_NONBLOCK flag has an effect.

Parameters
mqdmessage queue descriptor;
attrpointer to new attributes (only mq_flags is used);
oattrif not NULL, address where previous message queue attributes will be stored on success.
Return values
0on success;
-1with errno set if:
  • EBADF, mqd is not a valid message queue descriptor.
See also
Specification.
Tags
thread-unrestricted

◆ mq_timedreceive()

ssize_t mq_timedreceive ( mqd_t  q,
char *__restrict__  buffer,
size_t  len,
unsigned *__restrict__  prio,
const struct timespec *__restrict__  timeout 
)


Attempt, during a bounded time, to receive a message from a message queue.

This service is equivalent to mq_receive(), except that if the flag O_NONBLOCK is not set for the descriptor fd and the message queue is empty, the calling thread is only suspended until the timeout abs_timeout expires.

Parameters
qthe queue descriptor;
bufferthe address where the received message will be stored on success;
lenbuffer length;
prioaddress where the priority of the received message will be stored on success.
timeoutthe timeout, expressed as an absolute value of the CLOCK_REALTIME clock.
Returns
the message length, and copy a message at the address buffer on success;
-1 with no message unqueued and errno set if:
  • EBADF, fd is not a valid descriptor open for reading;
  • EMSGSIZE, the length len is lesser than the message queue mq_msgsize attribute;
  • EAGAIN, the queue is empty, and the flag O_NONBLOCK is set for the descriptor fd;
  • EPERM, the caller context is invalid;
  • EINTR, the service was interrupted by a signal;
  • ETIMEDOUT, the specified timeout expired.
See also
Specification.
Tags
xthread-only, switch-primary

◆ mq_timedsend()

int mq_timedsend ( mqd_t  q,
const char *  buffer,
size_t  len,
unsigned  prio,
const struct timespec *  timeout 
)


Attempt, during a bounded time, to send a message to a message queue.

This service is equivalent to mq_send(), except that if the message queue is full and the flag O_NONBLOCK is not set for the descriptor fd, the calling thread is only suspended until the timeout specified by abs_timeout expires.

Parameters
qmessage queue descriptor;
bufferpointer to the message to be sent;
lenlength of the message;
priopriority of the message;
timeoutthe timeout, expressed as an absolute value of the CLOCK_REALTIME clock.
Returns
0 and send a message on success;
-1 with no message sent and errno set if:
  • EBADF, fd is not a valid message queue descriptor open for writing;
  • EMSGSIZE, the message length exceeds the mq_msgsize attribute of the message queue;
  • EAGAIN, the flag O_NONBLOCK is set for the descriptor fd and the message queue is full;
  • EPERM, the caller context is invalid;
  • ETIMEDOUT, the specified timeout expired;
  • EINTR, the service was interrupted by a signal.
See also
Specification.
Tags
xthread-only, switch-primary

◆ mq_unlink()

int mq_unlink ( const char *  name)


Unlink a message queue

This service unlinks the message queue named name. The message queue is not destroyed until all queue descriptors obtained with the mq_open() service are closed with the mq_close() service. However, after a call to this service, the unlinked queue may no longer be reached with the mq_open() service.

Parameters
namename of the message queue to be unlinked.
Return values
0on success;
-1with errno set if:
  • EPERM, the caller context is invalid;
  • ENAMETOOLONG, the length of the name argument exceeds 64 characters;
  • ENOENT, the message queue does not exist.
See also
Specification.
Tags
thread-unrestricted, switch-secondary