mq_getattr()

Get a message queue's attributes

Synopsis:

#include <mqueue.h>

int mq_getattr( mqd_t mqdes,
                struct mq_attr* mqstat );

Arguments:

mqdes

The message-queue descriptor, returned by mq_open(), of the message queue that you want to get the attributes of.

mqstat

A pointer to a mq_attr structure where the function can store the attributes of the message queue. For more information, see below.

Library:

• For the traditional implementation, libc

  Use the -l c option to qcc to link against this library. This library is usually included automatically.

• For the alternate implementation using asynchronous messages, libmq

  Use the -l mq option to qcc to link against this library.

Description:

The mq_getattr() function determines the current attributes of the queue referenced by mqdes. These attributes are stored in the location pointed to by mqstat.

Neutrino supports two implementations of message queues: a traditional implementation, and an alternate one that uses asynchronous messages. For more information, see the entry for mq and mqueue in the Utilities Reference.

The fields of the mq_attr structure are as follows:

long mq_flags

The options set for this open message-queue description (i.e. these options are for the given mqdes, not the queue as a whole). This field may have been changed by call to mq_setattr() since you opened the queue.

• O_NONBLOCK -- no call to mq_receive() or mq_send() will ever block on this queue. If the queue is in such a condition that the given operation can't be performed without blocking, then an error is returned, and errno is set to EAGAIN.

long mq_maxmsg

The maximum number of messages that can be stored on the queue. This value was set when the queue was created.

long mq_msgsize

The maximum size of each message on the given message queue. This value was also set when the queue was created.

long mq_curmsgs

The number of messages currently on the given queue.

long mq_sendwait

The number of threads currently waiting to send a message. This field was eliminated from the POSIX standard after draft 9, but has been kept as a QNX Neutrino extension. A nonzero value in this field implies that the queue is full.

long mq_recvwait

The number of threads currently waiting to receive a message. Like mq_sendwait, this field has been kept as a QNX Neutrino extension. A nonzero value in this field implies that the queue is empty.

The alternate (mq) implementation of message queues doesn't see the non-POSIX mq_sendwait and mq_recvwait fields.

Returns:

-1 if an error occurred (errno is set). Any other value indicates success.

Errors:

EBADF

Invalid message queue mqdes.

Classification:

POSIX 1003.1 MSG

See also:

mq_close(), mq_open(), mq_receive(), mq_send(), mq_setattr()

mq, mqueue in the Utilities Reference