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 entries for mq and mqueue in the Utilities Reference, as well as the Managing POSIX Message Queues 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.

---

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

Managing POSIX Message Queues technote.