MQ_SEND(2)

💌 MQ_SEND(2) — bestie, it's the System Calls Manual 💌

okay so. we're in the System Calls Manual (section 2, the syscall girlies) and today's episode is all about yeeting a message into a queue. real-time flavored. let's GO 🚀

---

✨ NAME ✨

mq_send, mq_timedsend — send a message to message queue (REALTIME) 🦋

---

📚 LIBRARY 📚

POSIX Real-time Library (librt, -lrt) 💅

---

🎀 SYNOPSIS 🎀

#include <mqueue.h>

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

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

---

🌸 DESCRIPTION 🌸

so mq_send() is a system call that takes the message msg_ptr is pointing at and drops it into the message queue that mqdes is referring to. iconic behavior. ✨

the msg_len argument says how long that message is — in bytes — the one msg_ptr points at. and bestie, listen: the value of msg_len should be less than or equal to the mq_msgsize attribute of the message queue, or mq_send() will fail. no cap. 💀

if the message queue you named is not full, mq_send() behaves as if the message gets inserted into the queue at the position indicated by the msg_prio argument. a message with a larger numeric value of msg_prio gets inserted before messages with lower values of msg_prio. and a message gets inserted after other messages in the queue (if there are any) that have an equal msg_prio. the value of msg_prio should be less than {MQ_PRIO_MAX}. priorities are giving main character energy, honestly 👑

now the spicy part. if the message queue is full and O_NONBLOCK is not set in the message queue description associated with mqdes, then mq_send() will block until space becomes available to enqueue the message, or until mq_send() gets interrupted by a signal. 😭

and if more than one thread is waiting to send when space opens up in the message queue, and the Priority Scheduling option is supported, then the thread of the highest priority that has been waiting the longest gets unblocked to send its message. otherwise? it is unspecified which waiting thread gets unblocked. 🤷♀️ (unspecified = we literally cannot promise you anything, bestie, don't @ me)

if the message queue is full and O_NONBLOCK is set in the message queue description associated with mqdes, then the message will not be queued and mq_send() will return an error. periodt. 🚫

---

🕐 and now… mq_timedsend() 🕐

mq_timedsend() adds a message to the message queue specified by mqdes in exactly the manner defined for the mq_send() system call. same vibe, different clock. ✨

however — and this is the whole point — if the specified message queue is full and O_NONBLOCK is not set in the message queue description associated with mqdes, the wait for sufficient room in the queue gets terminated when the specified timeout expires. ⏰

and if O_NONBLOCK is set in the message queue description, this system call is equivalent to mq_send(). so basically the timeout doesn't even matter there. 🫶

the timeout will expire when the absolute time specified by abs_timeout passes — as measured by the clock on which timeouts are based (that is, when the value of that clock equals or exceeds abs_timeout) — or if the absolute time specified by abs_timeout has already been passed at the time of the call. so if you're late, you're late. 🙈

🎀 heads up: the timeout is based on the CLOCK_REALTIME clock. not monotonic, not whatever else. CLOCK_REALTIME. 💜

---

🫶 RETURN VALUES 🫶

upon successful completion, mq_send() and mq_timedsend() return a value of zero. slay. ✨

otherwise — and this is the sad part — no message will be enqueued, the system calls return -1, and the global variable errno is set to indicate the error. 😭

---

💀 ERRORS 💀

the mq_send() and mq_timedsend() system calls will fail if:

• [EAGAIN] — the O_NONBLOCK flag is set in the message queue description associated with mqdes, and the specified message queue is full. 😤
• [EBADF] — the mqdes argument is not a valid message queue descriptor open for writing. bestie that's not even a real queue 💀
• [EINTR] — a signal interrupted the call to mq_send() or mq_timedsend(). rude of it honestly 😭
• [EINVAL] — the value of msg_prio was outside the valid range.
• [EINVAL] — the process or thread would have blocked, and the abs_timeout parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million. that's not a nanosecond field, that's a cry for help 🫠
• [EMSGSIZE] — the specified message length, msg_len, exceeds the message size attribute of the message queue. too much. TOO MUCH. 📏
• [ETIMEDOUT] — the O_NONBLOCK flag was not set when the message queue was opened, but the timeout expired before the message could be added to the queue. clock said no ⏰🚫

---

👀 SEE ALSO 👀

mq_open(2), mq_receive(2), mq_setattr(2), mq_timedreceive(2)

go read those too, they're the rest of the friend group 🫶

---

📜 STANDARDS 📜

the mq_send() and mq_timedsend() system calls conform to IEEE Std 1003.1-2004 (“POSIX.1”). certified. 💅

---

🦋 HISTORY 🦋

support for POSIX message queues first appeared in FreeBSD 7.0. vintage!! ✨

---

⚖️ COPYRIGHT ⚖️

portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. in the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. the original Standard can be obtained online at http://www.opengroup.org/unix/online.html.

---

okay that's the whole page bestie, you're officially a message-queue girlie now 💖 sending u good vibes and zero EAGAINs 🎀

this cutie was brought to you by Debian, dated November 29, 2005 — yeah she's an older icon but she ATE and she's still serving 💅👑