---
name: "mq_receive"
section: "3"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/mq_receive/3"
---

# mq\_receive(3)

receive a message from a message queue

## NAME

mq\_receive, mq\_timedreceive - receive a message from a message queue

## LIBRARY

Real-time library (*librt*, *-lrt*)

## SYNOPSIS

```
#include <mqueue.h>
```

**ssize\_t mq\_receive(**size\_t msg\_len;                    **mqd\_t** *mqdes***, char** *msg\_ptr***\[***msg\_len***\],**                    **size\_t** *msg\_len***, unsigned int \****msg\_prio***);**

**#include \<time.h\>** **#include \<mqueue.h\>**

**ssize\_t mq\_timedreceive(**size\_t msg\_len;                    **mqd\_t** *mqdes***, char \*restrict** *msg\_ptr***\[***msg\_len***\],**                    **size\_t** *msg\_len***, unsigned int \*restrict** *msg\_prio***,**                    **const struct timespec \*restrict** *abs\_timeout***);**

Feature Test Macro Requirements for glibc (see [**feature\_test\_macros**(7)](/feature_test_macros/7.md)):

**mq\_timedreceive**():

```
    _POSIX_C_SOURCE >= 200112L
```

## DESCRIPTION

**mq\_receive**() removes the oldest message with the highest priority from the message queue referred to by the message queue descriptor *mqdes*, and places it in the buffer pointed to by *msg\_ptr*. The *msg\_len* argument specifies the size of the buffer pointed to by *msg\_ptr*; this must be greater than or equal to the *mq\_msgsize* attribute of the queue (see [**mq\_getattr**(3)](/mq_getattr/3.md)). If *msg\_prio* is not NULL, then the buffer to which it points is used to return the priority associated with the received message.

If the queue is empty, then, by default, **mq\_receive**() blocks until a message becomes available, or the call is interrupted by a signal handler. If the **O\_NONBLOCK** flag is enabled for the message queue description, then the call instead fails immediately with the error **EAGAIN**.

**mq\_timedreceive**() behaves just like **mq\_receive**(), except that if the queue is empty and the **O\_NONBLOCK** flag is not enabled for the message queue description, then *abs\_timeout* points to a structure which specifies how long the call will block. This value is an absolute timeout in seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), specified in a [**timespec**(3)](/timespec/3.md) structure.

If no message is available, and the timeout has already expired by the time of the call, **mq\_timedreceive**() returns immediately.

## RETURN VALUE

On success, **mq\_receive**() and **mq\_timedreceive**() return the number of bytes in the received message; on error, -1 is returned, with *errno* set to indicate the error.

## ERRORS

- **EAGAIN**

  The queue was empty, and the **O\_NONBLOCK** flag was set for the message queue description referred to by *mqdes*.

- **EBADF**

  The descriptor specified in *mqdes* was invalid or not opened for reading.

- **EINTR**

  The call was interrupted by a signal handler; see [**signal**(7)](/signal/7.md).

- **EINVAL**

  The call would have blocked, and *abs\_timeout* was invalid, either because *tv\_sec* was less than zero, or because *tv\_nsec* was less than zero or greater than 1000 million.

- **EMSGSIZE**

  *msg\_len* was less than the *mq\_msgsize* attribute of the message queue.

- **ETIMEDOUT**

  The call timed out before a message could be transferred.

## ATTRIBUTES

For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md).

| | | |
| --- | --- | --- |
| **Interface** | **Attribute** | **Value** |
| **mq\_receive**(), **mq\_timedreceive**() | Thread safety | MT-Safe |

## VERSIONS

On Linux, **mq\_timedreceive**() is a system call, and **mq\_receive**() is a library function layered on top of that system call.

## STANDARDS

POSIX.1-2008.

## HISTORY

POSIX.1-2001.

## SEE ALSO

[**mq\_close**(3)](/mq_close/3.md), [**mq\_getattr**(3)](/mq_getattr/3.md), [**mq\_notify**(3)](/mq_notify/3.md), [**mq\_open**(3)](/mq_open/3.md), [**mq\_send**(3)](/mq_send/3.md), [**mq\_unlink**(3)](/mq_unlink/3.md), [**timespec**(3)](/timespec/3.md), [**mq\_overview**(7)](/mq_overview/7.md), [**time**(7)](/time/7.md)