mq_send(3)

💌 mq_send — aka mq_send, mq_timedsend

okay bestie, gather round, because today we're learning how to slide a message into a message queue. yes, that's the whole job. it's giving ✨message delivery✨ and honestly? iconic.

btw this page lives in the Library Functions Manual, section 3, and the vibe is Real-time library (librt, -lrt) — so if the linker starts acting up, that's the -lrt you're missing, no cap.

---

🫶 LIBRARY

Real-time library (librt, -lrt)

---

✨ SYNOPSIS ✨

#include <mqueue.h>

int mq_send(size_t msg_len;
              mqd_t mqdes, const char msg_ptr[msg_len],
              size_t msg_len, unsigned int msg_prio);

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

int mq_timedsend(size_t msg_len;
              mqd_t mqdes, const char msg_ptr[msg_len],
              size_t msg_len, unsigned int msg_prio,
              const struct timespec *abs_timeout);

🌸 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

• mq_timedsend():
  • _POSIX_C_SOURCE >= 200112L

like, yes, you literally have to define that macro or glibc will pretend it doesn't know her 💅

---

💖 DESCRIPTION 💖

So mq_send() takes the message that msg_ptr is pointing at and adds it to the message queue that the message queue descriptor mqdes refers to. That's it. That's the function. She's a deliverer. 🎀

The msg_len argument says how long that message is — the one msg_ptr is pointing to. And listen: this length must be less than or equal to the queue's mq_msgsize attribute. Rule is the rule. Oh, and zero-length messages? allowed. send an empty little nothing, she's valid. 🦋

msg_prio is a nonnegative integer and it's the priority of this message. Messages go on the queue in decreasing order of priority — so the high-priority ones skip the line like they own the place — and newer messages with the same priority get placed after the older messages with that same priority. First come, first served between equals, basically. If you wanna know the actual range for message priority, go check mq_overview(7), she has the receipts.

Now. If the message queue is already full — meaning the number of messages on the queue equals the queue's mq_maxmsg attribute — then by default mq_send() blocks. It just stands there, waiting, until enough space frees up so the message can be queued, or until a signal handler interrupts the call. 😭 But if the O_NONBLOCK flag is enabled for that message queue description, the call doesn't wait at all — it fails immediately with the error EAGAIN. Boom. Not sorry. 💅

mq_timedsend() behaves just like mq_send(), except for one lil upgrade: if the queue is full and the O_NONBLOCK flag is not enabled for the message queue description, then abs_timeout points to a structure that says how long the call will block. That 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 "from now" — absolute. don't get caught slipping. 🌈

And if the message queue is full and the timeout has already expired by the time you make the call, mq_timedsend() returns immediately. No waiting, no drama, just instant feedback. 🍓

---

🫧 RETURN VALUE 🫧

On success, mq_send() and mq_timedsend() return zero. 🎉 On error, -1 comes back, with errno set to tell you what went wrong. The errno is basically the "and here's why" text message. 💜

---

💀 ERRORS 💀

• EAGAIN — the queue was full, 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 it wasn't opened for writing. (write permissions, bestie, they matter 🙈)
• EINTR — the call got interrupted by a signal handler; see 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.
• EMSGSIZE — msg_len was greater than the mq_msgsize attribute of the message queue. Too much. Overflowing. Not the vibe. 😭
• 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).

• mq_send(), mq_timedsend() — Thread safety: MT-Safe ✅

MT-Safe means she's thread-safe and she knows it. main character energy, fr fr.

---

⭐ VERSIONS ⭐

On Linux, mq_timedsend() is a system call, and mq_send() is a library function layered on top of that system call. So like, mq_send() is wearing mq_timedsend()'s outfit. slay. 💅

---

📜 STANDARDS 📜

POSIX.1-2008.

---

🎀 HISTORY 🎀

POSIX.1-2001.

---

🌸 SEE ALSO 🌸

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

---

and that's the whole page, bestie 🫶 go send some messages, and remember: absolute timeout, not relative, iykyk.

this was brought to you by Linux man-pages 6.20, dated 2026-02-08 — the mq_send(3) era, and we're obsessed with her. bye!! 💖✨🎀🦋