mq_receive(3)

💌 mq_receive — receive a message from a message queue 💌

okay bestie, sit down, hydrate, because today we're learning about mq_receive and mq_timedreceive from the Linux man pages, section 3 (that's "Library Functions Manual" energy, iykyk 📚✨). This is the glow-up of getting a message OUT of a message queue. Let's go 🫶

---

📖 NAME

mq_receive, mq_timedreceive — receive a message from a message queue 💅

---

🎀 LIBRARY

Real-time library (librt, -lrt) — yes you have to link it, no it's not optional, don't come for me 🌸

---

✨ 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 (peep feature_test_macros(7) for the lore 👀):

• mq_timedreceive():
  • _POSIX_C_SOURCE >= 200112L

---

💖 DESCRIPTION

So mq_receive() does the main character thing: it removes the oldest message with the highest priority from the message queue that the descriptor mqdes is pointing at, and drops it into the buffer that msg_ptr points to. Iconic behavior honestly 🌟

The msg_len argument is literally just the size of the buffer at msg_ptr. And bestie, it must be greater than or equal to the mq_msgsize attribute of the queue (go check mq_getattr(3) for that one, she'll tell you) 🧚

If msg_prio is not NULL, then the buffer it points to gets used to return the priority that came with the received message. Cute little bonus value 💜

Now — if the queue is empty? By default mq_receive() just blocks until a message shows up, or until the call gets interrupted by a signal handler. It's giving waiting-by-the-phone energy 😭 But if the O_NONBLOCK flag is enabled for the message queue description, then instead the call fails immediately with the error EAGAIN. No waiting, no patience, periodt 💅

mq_timedreceive() behaves exactly 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 struct that says how long the call will block. And the value is an absolute timeout — seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC) — specified in a timespec(3) structure. Absolute, not relative, don't get it twisted ⏰✨

And if no message is available, and the timeout has already expired by the time of the call? mq_timedreceive() returns immediately. It's not gonna sit around for a deadline that already passed, she has places to be 💀

---

🔥 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. Classic.

---

🌸 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; peep signal(7).
• 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. Yeah. 1000 million. That's the number. Don't ask 🙈
• 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. She waited, the vibe expired, it's over 😭

---

👑 ATTRIBUTES

For an explanation of the terms used in this section, see attributes(7).

• Interface: mq_receive(), mq_timedreceive()
• Attribute: Thread safety
• Value: MT-Safe

(Yes they're thread safe. Slay. Multithreaded besties stay winning 🏆)

---

🦋 VERSIONS

On Linux, mq_timedreceive() is a system call, and mq_receive() is a library function layered on top of that system call. So one's the real one and one's wearing a cute little coat. Both valid 💅

---

⭐ STANDARDS

POSIX.1-2008.

---

🌈 HISTORY

POSIX.1-2001.

---

🫶 SEE ALSO

mq_close(3), mq_getattr(3), mq_notify(3), mq_open(3), mq_send(3), mq_unlink(3), timespec(3), mq_overview(7), time(7)

---

and that's the whole thing bestie, you ate that 💖 this was brought to you by Linux man-pages 6.20, dated 2026-02-08 — page mq_receive(3), out 🎀✨🦋 no cap, go read the whole queue now, ily 🫶