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:

• mq_flags, flags of the message queue descriptor fd;
• 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:

	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:

• 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:

	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.

---