MSGRCV(2)

💌 msgrcv — bestie, come get your message 💌

okay so first things first: this page is MSGRCV(2), and it lives in the System Calls Manual. Yes, that one. The one with all the SysV IPC lore. Sit down, get comfy, we're learning how to pull a message out of a message queue. 🫶

---

✨ NAME ✨

msgrcv — receive a message from a message queue

📚 LIBRARY 📚

Standard C Library (libc, -lc) — she's standard, she's in libc, she's right there. 💅

🧾 SYNOPSIS 🧾

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>

ssize_t
msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp, int msgflg);

🌸 DESCRIPTION 🌸

So msgrcv() does exactly what it says on the tin: it receives a message from the message queue you specify in msqid, and it drops that message into the structure that msgp points to. 📥

And that structure? It's giving very much these two members, periodt:

long mtype;    /* message type */
char mtext[1]; /* body of message */

mtype is an integer greater than 0, and it's the little tag you use to pick which messages you want. mtext is an array of bytes, and it can be up to as big as the system limit allows (MSGMAX). 👑

Now, msgtyp — this one's the main character, because its value completely changes the vibe of the call. Here's the tea:

• If msgtyp is greater than 0, you get the first message of type msgtyp. 🎯
• If msgtyp is equal to 0, you get the first message on the queue, no type discrimination, we're not picky. 🫠
• If msgtyp is less than 0, you get the first message of the lowest message type that is less than or equal to the absolute value of msgtyp. Yes bestie, the absolute value. Math class said it would come up again and it did. 😭

Next up: msgsz specifies the maximum length of the requested message. And here's the part you need to pay attention to, because it's lowkey sneaky:

If the received message is longer than msgsz, it gets silently truncated when the MSG_NOERROR flag is set in msgflg. If that flag is not set, you get an error instead. Silent truncation. Not a word. Nothing. 👀

Now, what if there's no matching message on the queue that msqid points at? That depends entirely on whether IPC_NOWAIT is set in msgflg:

• If IPC_NOWAIT is set, msgrcv() immediately returns a value of -1 and sets errno to ENOMSG. No waiting, no patience, we move. 🏃‍♀️
• If IPC_NOWAIT is not set, your calling process gets blocked until one of these three things happens:
  • A message of the requested type becomes available on the message queue. 🎉
  • The message queue is removed — in which case -1 is returned and errno is set to EINVAL. 💀
  • A signal is received and caught — -1 is returned and errno is set to EINTR. 😵

And when a message is successfully received, the data structure associated with msqid gets updated like this:

• msg_cbytes is decremented by the size of the message. 📉
• msg_lrpid is set to the pid of the caller. 🫵
• msg_lrtime is set to the current time. ⏰
• msg_qnum is decremented by 1. 1️⃣

🎁 RETURN VALUES 🎁

When it works out? msgrcv() returns the number of bytes received into the mtext field of the structure that msgp points to. Beautiful. Iconic. ✨

Otherwise you get -1, and errno is set to tell you what went wrong. 😭

🚨 ERRORS 🚨

The msgrcv() function will fail if:

• [EINVAL] — The msqid argument is not a valid message queue identifier. Also: the message queue was removed while msgrcv() was waiting for a message of the requested type to become available on it. Also also: the msgsz argument is less than 0. 🙃
• [E2BIG] — A matching message was received, but its size was greater than msgsz and the MSG_NOERROR flag was not set in msgflg. She was too big and you didn't give permission. 😤
• [EACCES] — The calling process does not have read access to the message queue. No read permission, no message, sorry bestie. 🚫
• [EFAULT] — The msgp argument points to an invalid address. 🕳️
• [EINTR] — The system call was interrupted by the delivery of a signal. 😵‍💫
• [ENOMSG] — There is no message of the requested type available on the message queue, and IPC_NOWAIT is set in msgflg. Empty queue behavior, immediately returned. 🫙

👀 SEE ALSO 👀

msgctl(2), msgget(2), msgsnd(2) — the whole friend group, go say hi. 🫶

📜 HISTORY 📜

Message queues appeared in the first release of AT&T System V UNIX. She's old money, she's been here since the beginning, and she's still running. 💜

---

okay that's the whole page bestie, you're officially a message queue girlie now 💅✨

this one's from Debian, dated July 28, 2016 — so shoutout to the Debian crew for keeping the lore alive. mwah. 🎀🦋