Message queues services.
[POSIX skin.]

Collaboration diagram for Message queues services.:

Detailed Description

Message queues 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().


Functions

mqd_t mq_open (const char *name, int oflags,...)
 Open a message queue.
int mq_close (mqd_t fd)
 Close a message queue.
int mq_unlink (const char *name)
 Unlink a message queue.
int mq_send (mqd_t fd, const char *buffer, size_t len, unsigned prio)
 Send a message to a message queue.
int mq_timedsend (mqd_t fd, const char *buffer, size_t len, unsigned prio, const struct timespec *abs_timeout)
 Attempt, during a bounded time, to send a message to a message queue.
ssize_t mq_receive (mqd_t fd, char *buffer, size_t len, unsigned *priop)
 Receive a message from a message queue.
ssize_t mq_timedreceive (mqd_t fd, char *__restrict__ buffer, size_t len, unsigned *__restrict__ priop, const struct timespec *__restrict__ abs_timeout)
 Attempt, during a bounded time, to receive a message from a message queue.
int mq_getattr (mqd_t fd, struct mq_attr *attr)
 Get the attributes object of a message queue.
int mq_setattr (mqd_t fd, const struct mq_attr *__restrict__ attr, struct mq_attr *__restrict__ oattr)
 Set flags of a message queue.
int mq_notify (mqd_t fd, const struct sigevent *evp)
 Register the current thread to be notified of message arrival at an empty message queue.


Function Documentation

int mq_close ( mqd_t  fd  ) 

Close a message queue.

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

Parameters:
fd message queue descriptor.
Return values:
0 on success;
-1 with errno set if:
  • EBADF, fd is an invalid message queue descriptor;
  • EPERM, the caller context is invalid.
Valid contexts:
  • kernel module initialization or cleanup routine;
  • kernel-space cancellation cleanup routine;
  • user-space thread (Xenomai threads switch to secondary mode);
  • user-space cancellation cleanup routine.
See also:
Specification.
Examples:
rtcan_rtt.c.

int mq_getattr ( mqd_t  fd,
struct mq_attr *  attr 
)

Get the attributes object of a message queue.

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

The following attributes are set:

Parameters:
fd message queue descriptor;
attr address where the message queue attributes will be stored on success.
Return values:
0 on success;
-1 with errno set if:
  • EBADF, fd is not a valid descriptor.
See also:
Specification.

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

Register the current thread to be notified of message arrival at an empty message queue.

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 fd, 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 Xenomai POSIX skin thread (created with pthread_create()), this service fails.

Note that signals sent to user-space Xenomai POSIX skin threads will cause them to switch to secondary mode.

Parameters:
fd message queue descriptor;
evp pointer to an event notification structure.
Return values:
0 on success;
-1 with errno set if:
  • EINVAL, evp is invalid;
  • EPERM, the caller context is invalid;
  • EBADF, fd is not a valid message queue descriptor;
  • EBUSY, another thread is already registered.
Valid contexts:
  • Xenomai kernel-space POSIX skin thread,
  • Xenomai user-space POSIX skin thread (switches to primary mode).
See also:
Specification.

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

Open a message queue.

This service establishes a connection between the message queue named name and the calling context (kernel-space as a whole, or user-space process).

One of the following values should be set in oflags:

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:

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:

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:
name name of the message queue to open;
oflags flags.
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 exists in 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.
Valid contexts:
When creating a message queue, only the following contexts are valid:
  • kernel module initialization or cleanup routine;
  • user-space thread (Xenomai threads switch to secondary mode).
See also:
Specification.
Examples:
rtcan_rtt.c.

ssize_t mq_receive ( mqd_t  fd,
char *  buffer,
size_t  len,
unsigned *  priop 
)

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:
fd the queue descriptor;
buffer the address where the received message will be stored on success;
len buffer length;
priop address 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.
Valid contexts:
  • Xenomai kernel-space thread,
  • Xenomai user-space thread (switches to primary mode).
See also:
Specification.
Examples:
rtcan_rtt.c.

int mq_send ( mqd_t  fd,
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:
fd message queue descriptor;
buffer pointer to the message to be sent;
len length of the message;
prio priority 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.
Valid contexts:
  • Xenomai kernel-space thread,
  • Xenomai user-space thread (switches to primary mode).
See also:
Specification.
Examples:
rtcan_rtt.c.

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

Set flags of a message queue.

This service sets the flags of the fd 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:
fd message queue descriptor;
attr pointer to new attributes (only mq_flags is used);
oattr if not NULL, address where previous message queue attributes will be stored on success.
Return values:
0 on success;
-1 with errno set if:
  • EBADF, fd is not a valid message queue descriptor.
See also:
Specification.

ssize_t mq_timedreceive ( mqd_t  fd,
char *__restrict__  buffer,
size_t  len,
unsigned *__restrict__  priop,
const struct timespec *__restrict__  abs_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:
fd the queue descriptor;
buffer the address where the received message will be stored on success;
len buffer length;
priop address where the priority of the received message will be stored on success.
abs_timeout the 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.
Valid contexts:
  • Xenomai kernel-space thread,
  • Xenomai user-space thread (switches to primary mode).
See also:
Specification.

int mq_timedsend ( mqd_t  fd,
const char *  buffer,
size_t  len,
unsigned  prio,
const struct timespec *  abs_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:
fd message queue descriptor;
buffer pointer to the message to be sent;
len length of the message;
prio priority of the message;
abs_timeout the 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.
Valid contexts:
  • Xenomai kernel-space thread,
  • Xenomai user-space thread (switches to primary mode).
See also:
Specification.

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:
name name of the message queue to be unlinked.
Return values:
0 on success;
-1 with 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.
Valid contexts:
  • kernel module initialization or cleanup routine;
  • kernel-space cancellation cleanup routine;
  • user-space thread (Xenomai threads switch to secondary mode);
  • user-space cancellation cleanup routine.
See also:
Specification.


Generated on Mon Mar 24 18:02:44 2008 for Xenomai API by  doxygen 1.5.3