mq_receive(3)

💖 mq_receive(3) — like, the manual page for mq_receive, mq_timedreceive 💖

okay bestie, this is a Library Functions Manual page, and it's literally about two little functions that go grab a message off a message queue for you. no cap, it's giving very "i'm the one who fetches the mail" energy 🫶

---

🌸 NAME 🌸

mq_receive, mq_timedreceive — receive a message from a message queue

so basically: get a message out of a message queue. that's the whole vibe ✨

---

📚 LIBRARY 📚

Real-time library (librt, link it with -lrt)

yes queen, you gotta link the real-time library. don't forget -lrt or the linker will simply not know her 😭

---

✨ 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 (if you wanna know what that even means, go read feature_test_macros(7)):

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. main character message selection, honestly — oldest and highest priority, periodt 💅

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 (peep mq_getattr(3) if you wanna check what that attribute is). so no, you can't bring a tiny little buffer to a big message party 🙈

if msg_prio is not NULL, then the buffer to which it points is used to return the priority associated with the received message. free priority info, we love that for you ⭐

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. she will wait. patiently. forever if she has to 🧚

if the O_NONBLOCK flag is enabled for the message queue description, then the call instead fails immediately with the error EAGAIN. no waiting, no patience, just vibes and an error code 💀

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) structure. absolute, bestie. not "how long from now" — "what time on the clock." iykyk ⏰

if no message is available, and the timeout has already expired by the time of the call, mq_timedreceive() returns immediately. she's not even gonna pretend to wait for you 🔥

---

🎀 RETURN VALUE 🎀

on success, mq_receive() and mq_timedreceive() return the number of bytes in the received message. slay, we got bytes 🦋

on error, -1 is returned, with errno set to indicate the error. classic. check your errno, bestie 😭

---

💀 ERRORS 💀

• EAGAIN — the queue was empty, and the O_NONBLOCK flag was set for the message queue description referred to by mqdes. nothing to read and you told her not to wait 🫠
• EBADF — the descriptor specified in mqdes was invalid or not opened for reading. girl, that descriptor is not it 🙈
• EINTR — the call was interrupted by a signal handler; see signal(7). a signal literally walked in mid-conversation ✋
• 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. your timeout was giving nonsense 😤
• EMSGSIZE — msg_len was less than the mq_msgsize attribute of the message queue. buffer too smol. it's giving "i can't fit" 💅
• ETIMEDOUT — the call timed out before a message could be transferred. you waited, nothing came, time's up 🕐

---

🌈 ATTRIBUTES 🌈

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

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

yes bestie, MT-Safe — she's thread safe, she can hang with all your threads at once 👑

---

⭐ 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 of them is talking straight to the kernel and the other one is her little glibc representative 🎀

---

🌸 STANDARDS 🌸

POSIX.1-2008.

---

💜 HISTORY 💜

POSIX.1-2001.

she's been around. vintage icon.

---

🦋 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)

the whole mq friend group, honestly. go say hi 🫶

---

ok so that's the page!! this one comes from Linux man-pages 6.20, dated 2026-02-08, and it's filed under mq_receive(3) in the Library Functions Manual. go forth and receive your messages, bestie 💖✨