MQ_NOTIFY(2)

💖 MQ_NOTIFY(2) 💖

ok so bestie, welcome to the System Calls Manual entry for mq_notify — she lives in section 2, she's giving REALTIME energy, and she's literally the girl who tells your process "hey. a message just showed up. wake up." 🫶

---

✨ LIBRARY ✨

POSIX Real-time Library — link it with librt, aka the flag -lrt. don't forget it, she will not link herself 💅

---

🌸 SYNOPSIS 🌸

#include <mqueue.h>

int
mq_notify(mqd_t mqdes, const struct sigevent *notification);

---

🎀 DESCRIPTION 🎀

ok so here's the tea. if the argument notification is not NULL, this system call registers the calling process to get notified when a message arrives at an empty message queue — the one tied to the message queue descriptor you passed in, mqdes. the notification you described in notification gets sent to the process the moment the queue transitions from empty ➡️ non-empty. glow-up arc fr fr ✨

⚠️ and here's the rule: at any given time, only ONE process can be registered for notification on a message queue. so if the calling process, or literally anybody else, already registered for notification of message arrival on that queue, then any subsequent attempts to register on it will fail. no queue-sniping allowed, bestie 😭

the notification argument points at a sigevent structure that defines how the calling process gets notified. so:

• if notification->sigev_notify is SIGEV_NONE, then no signal will be posted — but the error status and the return status for the operation still get set appropriately. she's quiet but she's still doing her job 👑
• for SIGEV_SIGNO and SIGEV_THREAD_ID notifications, the signal specified in notification->sigev_signo gets sent to the calling process (SIGEV_SIGNO) or to the thread whose LWP ID is notification->sigev_notify_thread_id (SIGEV_THREAD_ID).

and the info for the queued signal? she comes stacked with these:

• si_code — value: SI_MESGQ
• si_value — value: the value stored in notification->sigev_value
• si_mqd — value: mqdes

---

now, if notification is NULL and the process is currently registered for notification by that specified message queue? the existing registration gets removed. bye bestie, unsubscribe 🦋

and when the notification is sent to the registered process, its registration is removed automatically. the message queue then becomes available for registration again — free real estate ✨

ok one more thing, and it's important. if a process has registered for notification of message arrival at a message queue, and some thread is blocked in mq_receive() waiting to receive a message when a message arrives at the queue, then the arriving message will satisfy the appropriate mq_receive(). the resulting behavior is as if the message queue remains empty, and no notification will be sent. she said "the thread got it first, no need to ping u" 💀

---

💫 RETURN VALUES 💫

upon successful completion, the value 0 is returned. otherwise, the value -1 is returned and the global variable errno is set to indicate the error. that's it, that's the vibe check 🌈

---

🔥 ERRORS 🔥

the mq_notify() system call will fail if:

• [EBADF] — the mqdes argument is not a valid message queue descriptor.
• [EBUSY] — process is already registered for notification by the message queue.
• [EINVAL] — the asynchronous notification method in notification->sigev_notify is invalid or not supported.

---

👀 SEE ALSO 👀

mq_open(2), mq_send(2), mq_timedsend(2), sigevent(3), siginfo(3)

go read those next bestie, they're all connected, iykyk 🧚

---

📜 STANDARDS 📜

the mq_notify() system call conforms to IEEE Std 1003.1-2004 (“POSIX.1”). certified icon behavior, periodt 💅

---

🕰️ HISTORY 🕰️

support for POSIX message queues first appeared in FreeBSD 7.0. she's been that girl since 7.0 🎀

---

⚖️ 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.

---

and that's the whole page, bestie!! 🫶 this one shipped from Debian on July 15, 2016 — so like, a vintage baddie. go notify somebody that a message is available, u got this 🌸💖✨