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

mqd	message queue descriptor.

Return values

0	on success;
-1	with 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

mqd	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, mqd is not a valid descriptor.

See also

Specification.

Tags

thread-unrestricted

References mq_setattr().

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

mqd	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, 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

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

q	the queue descriptor;
buffer	the address where the received message will be stored on success;
len	buffer length;
prio	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.

See also

Specification.

Tags

xthread-only, switch-primary

References mq_timedreceive().

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

q	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.

See also

Specification.

Tags

xthread-only, switch-primary

References mq_timedsend().

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

mqd	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, mqd is not a valid message queue descriptor.

See also

Specification.

Tags

thread-unrestricted

Referenced by mq_getattr().

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

q	the queue descriptor;
buffer	the address where the received message will be stored on success;
len	buffer length;
prio	address where the priority of the received message will be stored on success.
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.

See also

Specification.

Tags

xthread-only, switch-primary

Referenced by mq_receive().

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

q	message queue descriptor;
buffer	pointer to the message to be sent;
len	length of the message;
prio	priority of the message;
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.

See also

Specification.

Tags

xthread-only, switch-primary

Referenced by mq_send().

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

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.

See also

Specification.

Tags

thread-unrestricted, switch-secondary