mq_getattr()

Updated: April 19, 2023

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:

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.

Note: The message queue manager needs to be running. QNX Neutrino supports two implementations of message queues: a traditional implementation, and an alternate one that uses the mq server and a queue in kernel space. For more information, see the entries for mq and mqueue in the Utilities Reference, as well as the POSIX Message Queues: Two Implementations technote.

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.
Note: 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.

Examples:

See the example for mq_open().

Classification:

POSIX 1003.1 MSG

Safety:  
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes