MSGCTL(2)

💖 MSGCTL(2) — message control operations 💖

okay bestie, sit down, hydrate, because today we're learning msgctl — the System Calls Manual page that lets you boss around your message queues. no cap, this is the group-chat admin of the SysV IPC world. 👑

LIBRARY: Standard C Library (libc, -lc) — she's built in, you don't gotta install anything. iconic.

---

✨ SYNOPSIS ✨

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

int
msgctl(int msqid, int cmd, struct msqid_ds *buf);

---

🌸 DESCRIPTION 🌸

The msgctl() system call performs some control operations on the message queue specified by msqid. literally it's the "manage my queue" button. the way that every queue deserves a lil manager 💅

Every message queue has a data structure associated with it, and parts of it can be altered by msgctl() while other parts determine what msgctl() does. it's giving mutual. that structure lives in <sys/msg.h> and contains (amongst others) these members:

struct msqid_ds {
        struct  ipc_perm msg_perm;      /* msg queue permission bits */
        msglen_t msg_cbytes;    /* number of bytes in use on the queue */
        msgqnum_t msg_qnum;     /* number of msgs in the queue */
        msglen_t msg_qbytes;    /* max # of bytes on the queue */
        pid_t   msg_lspid;      /* pid of last msgsnd() */
        pid_t   msg_lrpid;      /* pid of last msgrcv() */
        time_t  msg_stime;      /* time of last msgsnd() */
        time_t  msg_rtime;      /* time of last msgrcv() */
        time_t  msg_ctime;      /* time of last msgctl() */
};

and the ipc_perm structure that's chilling inside msqid_ds? that one's defined in <sys/ipc.h> and looks like this:

struct ipc_perm {
        uid_t           cuid;   /* creator user id */
        gid_t           cgid;   /* creator group id */
        uid_t           uid;    /* user id */
        gid_t           gid;    /* group id */
        mode_t          mode;   /* r/w permission */
        unsigned short  seq;    /* sequence # (to generate unique ipcid) */
        key_t           key;    /* user specified msg/sem/shm key */
};

so. the operation msgctl() performs is specified in cmd, and it's one of these three besties:

• IPC_STAT — Gather information about the message queue and place it in the structure pointed to by buf. it's the "spill the tea, what's going on in there" command. 🔍
• IPC_SET — Set the value of the msg_perm.uid, msg_perm.gid, msg_perm.mode and msg_qbytes fields in the structure associated with msqid. the values come from the corresponding fields in the structure pointed to by buf. ✨

🚨 BUT: this operation can only be executed by the super-user, or a process that has an effective user id equal to either msg_perm.cuid or msg_perm.uid in the data structure associated with the message queue. and the value of msg_qbytes can only be increased by the super-user. values for msg_qbytes that exceed the system limit (MSGMNB from <sys/msg.h>) are silently truncated to that limit. silently!! no warning, no text back, just vibes. 💀

• IPC_RMID — Remove the message queue specified by msqid and destroy the data associated with it. it's the block-and-delete. only the super-user or a process with an effective uid equal to the msg_perm.cuid or msg_perm.uid values in the data structure associated with the queue can do this. 🔥

Permission to read from or write to a message queue (see msgsnd(2) and msgrcv(2)) is determined by the msg_perm.mode field in the same way as is done with files (see chmod(2)), except here's the twist: the effective uid can match either the msg_perm.cuid field or the msg_perm.uid field, and the effective gid can match either msg_perm.cgid or msg_perm.gid. two chances to get in, we love options 🫶

---

🌈 RETURN VALUES 🌈

The msgctl() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. so like, 0 = slay, -1 = check errno, bestie. 😭

---

💅 ERRORS 💅

The msgctl() function will fail if:

• [EPERM] — The cmd argument is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does the effective uid match either the msg_perm.uid or msg_perm.cuid fields of the data structure associated with the message queue.

also: an attempt is made to increase the value of msg_qbytes through IPC_SET but the caller is not the super-user. 🙈

• [EACCES] — The command is IPC_STAT and the caller has no read permission for this message queue. no read perms, no tea. 💀
• [EINVAL] — The msqid argument is not a valid message queue identifier.

or: cmd is not a valid command. 🚫

• [EFAULT] — The buf argument specifies an invalid address. that pointer is giving nowhere. 👻

---

🦋 SEE ALSO 🦋

msgget(2), msgrcv(2), msgsnd(2)

---

👑 HISTORY 👑

Message queues appeared in the first release of AT&T System V UNIX. yes she's old old. vintage. archival. still serving though. periodt. ✨

---

and that's the whole page, bestie!! 🎀 this was the Debian flavour of MSGCTL(2), dated July 9, 2020 — go forth and control your message queues responsibly, mwah 💖