The Linux kernel maintains an internal table of slots for each type of IPC object (message queues, semaphore sets, shared memory segments). Each slot in this table either holds a pointer to a live IPC object or is empty.

The key insight is that the IPC identifier (msqid) is not the same as the array index. The array index is just a slot number (0, 1, 2, …). The msqid is a larger number computed from the slot index combined with a sequence counter to prevent reuse confusion. MSG_STAT takes an index and returns the msqid as its function return value.

The TLPI book describes a two-step algorithm (which is how ipcs works internally):

The same pattern applies to the other two System V IPC mechanisms — semaphore sets and shared memory segments:

All six constants require #define _GNU_SOURCE to be defined. The algorithm to enumerate all objects is identical across all three types — call the INFO variant to get maxind, then loop with the STAT variant.

This program implements the two-step algorithm described above. It mirrors the svmsg_ls program from Listing 46-6 in TLPI.

#define _GNU_SOURCE          /* Required for MSG_INFO, MSG_STAT, struct msginfo */
#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/msg.h>

int main(void)
{
    int maxind;           /* Highest occupied index in entries array */
    int msqid;            /* IPC identifier returned by MSG_STAT */
    int idx;              /* Loop index for scanning */
    struct msginfo info;  /* Receives resource stats from MSG_INFO */
    struct msqid_ds ds;   /* Receives queue metadata from MSG_STAT */

    /*
     * Step 1: MSG_INFO
     *   - Fills 'info' with system-wide resource statistics
     *   - Return value = highest occupied slot index (maxind)
     *   - First argument is ignored (pass 0)
     *   - Cast msginfo ptr to (struct msqid_ds *) — required by API signature
     */
    maxind = msgctl(0, MSG_INFO, (struct msqid_ds *) &info);
    if (maxind == -1) {
        perror("msgctl MSG_INFO");
        exit(EXIT_FAILURE);
    }
    printf("maxind: %d\n\n", maxind);

    /*
     * Step 2: Loop from 0 to maxind, using MSG_STAT for each index.
     *
     * MSG_STAT:
     *   - First arg is the array INDEX (not a queue ID)
     *   - On success: fills 'ds', returns the msqid of that slot
     *   - On empty slot: returns -1, errno = EINVAL  → skip
     *   - On no permission: returns -1, errno = EACCES → skip
     */
    printf("%-8s %-10s %-14s %s\n", "index", "ID", "key", "messages");
    printf("%-8s %-10s %-14s %s\n", "-----", "--", "---", "--------");

    for (idx = 0; idx <= maxind; idx++) {
        msqid = msgctl(idx, MSG_STAT, &ds);

        if (msqid == -1) {
            if (errno == EINVAL || errno == EACCES)
                continue;   /* Empty slot or no permission — normal, skip */
            perror("msgctl MSG_STAT");
            continue;
        }

        /* Live queue found: print its details */
        printf("%-8d %-10d 0x%08lx     %lu\n",
               idx,
               msqid,
               (unsigned long) ds.msg_perm.__key,
               (unsigned long) ds.msg_qnum);
    }

    return 0;
}

This example focuses on using MSG_INFO to print system-wide message queue resource statistics, not just the list of queues. Useful for monitoring queue pressure in production systems.

#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/msg.h>

int main(void)
{
    struct msginfo info;
    int maxind;

    /*
     * MSG_INFO fills struct msginfo with system-wide resource usage:
     *   msgpool  - number of message queue headers allocated
     *   msgmap   - number of entries in message map
     *   msgmax   - max bytes per message (same as MSGMAX)
     *   msgmnb   - max bytes per queue (same as MSGMNB)
     *   msgmni   - max queues on system (same as MSGMNI)
     *   msgssz   - message segment size
     *   msgtql   - max total messages
     *   msgseg   - max number of message segments
     *
     * The RETURN VALUE is the highest occupied index in the entries array.
     */
    maxind = msgctl(0, MSG_INFO, (struct msqid_ds *) &info);
    if (maxind == -1) {
        perror("msgctl MSG_INFO");
        exit(EXIT_FAILURE);
    }

    printf("===== Message Queue Resource Info (MSG_INFO) =====\n\n");
    printf("Highest occupied entry index : %d\n", maxind);
    printf("Max queues on system (msgmni): %d\n", info.msgmni);
    printf("Max bytes per message (msgmax): %d\n", info.msgmax);
    printf("Max bytes per queue  (msgmnb): %d\n", info.msgmnb);
    printf("Max total messages   (msgtql): %d\n", info.msgtql);
    printf("\n");
    printf("To list all queues, scan indices 0..%d using MSG_STAT.\n", maxind);
    return 0;
}

The ipcs utility is a standard tool on every Linux system. When you run ipcs -q, it internally performs exactly the two-step algorithm above:

1. Calls msgctl(MSG_INFO) to discover maxind
2. Loops with msgctl(MSG_STAT) to read each live queue

The shell session in TLPI Listing 46-6’s commentary confirms this — the output of the custom svmsg_ls program exactly matches ipcs -q output, showing the same msqid values, keys, and message counts.