insque(3)

✨ insque(3) — the library functions manual page, bestie edition ✨

okay so we're in the Library Functions Manual today and we are talking about insque and remque, two of the most lowkey iconic little list-manglers in libc. buckle up 💖

---

🌸 NAME 🌸

insque, remque — insert/remove an item from a queue

---

🎀 LIBRARY 🎀

Standard C library — that's libc, and you link it with -lc. she's everywhere, she's free, she's the moment 💅

---

🦋 SYNOPSIS 🦋

#include <search.h>

void insque(void *elem, void *prev);
void remque(void *elem);

🧚 Feature Test Macro Requirements for glibc (see feature_test_macros(7)), no cap:

insque(), remque():
    _XOPEN_SOURCE >= 500
        || /* glibc >= 2.19: */ _DEFAULT_SOURCE
        || /* glibc <= 2.19: */ _SVID_SOURCE

---

💜 DESCRIPTION 💜

so <pink>insque()andremque()</pink> are your girls for manipulating doubly linked lists, fr fr. every element in the list is a struct where the first two elements are a forward pointer and a backward pointer. periodt. that's the whole deal.

and the list itself? it can be either:

• linear — meaning the forward pointer at the end of the list is NULL, and the backward pointer at the start of the list is NULL, or
• circular — meaning she loops back around like a little orbit 🌀

insque() inserts the element pointed to by elem immediately after the element pointed to by prev. that's it, that's the function.

if the list is linear: you can use the call insque(elem, NULL) to insert the initial list element, and this call sets the forward and backward pointers of elem to NULL. so cute, so convenient.

if the list is circular: the caller has to make sure the forward and backward pointers of the first element are initialized to point to that element itself (very self-love of them, honestly ✨), and the prev argument of the insque() call should also point to that element.

then <hotpink>remque() removes the element pointed to by *elem`* from the doubly linked list. bye bestie 👋 no restructuring, no drama, she just unlinks.

---

🔥 ATTRIBUTES 🔥

for the whole explanation of what these terms even mean, go check out attributes(7) — iykyk.

• insque(), remque() — Thread safety: MT-Safe 👑

so yeah. multithread away, she's safe.

---

⭐ VERSIONS ⭐

okay so on ancient systems, the arguments of these functions were of type struct qelem *, which was defined as:

struct qelem {
    struct qelem *q_forw;
    struct qelem *q_back;
    char          q_data[1];
};

and this is still what you will get if _GNU_SOURCE is defined before including <search.h>. vintage behavior, still shipping 💀

also, the location of the prototypes for these functions differs among several versions of UNIX. the one shown in the synopsis above is the POSIX version. some systems place them in <string.h> instead. so if your compiler is yelling at you, maybe check there first 🫶

---

🌈 STANDARDS 🌈

POSIX.1-2008. she's certified ✨

---

👑 HISTORY 👑

POSIX.1-2001. she's been here a while, and she's not leaving.

---

💀 BUGS 💀

okay so this one's a real one — in glibc 2.4 and earlier, it was not possible to specify prev as NULL. so to build a linear list back then, the caller had to build a list using an initial call that contained the first two elements of the list, with the forward and backward pointers in each element suitably initialized. messy! glad we don't have to do that anymore 😭

lowkey grateful we live in the present day. hug your glibc.

---

🍓 EXAMPLES 🍓

the program below demonstrates the use of insque(). here's what a run of the program looks like:

$ ./a.out -c a b c
Traversing completed list:
    a
    b
    c
That was a circular list

🌸 Program source 🌸

#include <search.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

struct element {
    struct element *forward;
    struct element *backward;
    char *name;
};

static struct element *
new_element(void)
{
    struct element *e;

    e = malloc(sizeof(*e));
    if (e == NULL) {
        fprintf(stderr, "malloc() failed\n");
        exit(EXIT_FAILURE);
    }

    return e;
}

int
main(int argc, char *argv[])
{
    struct element *first, *elem, *prev;
    int circular, opt, errfnd;

    /* The "-c" command-line option can be used to specify that the
       list is circular.  */

    errfnd = 0;
    circular = 0;
    while ((opt = getopt(argc, argv, "c")) != -1) {
        switch (opt) {
        case 'c':
            circular = 1;
            break;
        default:
            errfnd = 1;
            break;
        }
    }

    if (errfnd || optind >= argc) {
        fprintf(stderr,  "Usage: %s [-c] string...\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    /* Create first element and place it in the linked list.  */

    elem = new_element();
    first = elem;

    elem->name = argv[optind];

    if (circular) {
        elem->forward = elem;
        elem->backward = elem;
        insque(elem, elem);
    } else {
        insque(elem, NULL);
    }

    /* Add remaining command-line arguments as list elements.  */

    while (++optind < argc) {
        prev = elem;

        elem = new_element();
        elem->name = argv[optind];
        insque(elem, prev);
    }

    /* Traverse the list from the start, printing element names.  */

    printf("Traversing completed list:\n");
    elem = first;
    do {
        printf("    %s\n", elem->name);
        elem = elem->forward;
    } while (elem != NULL && elem != first);

    if (elem == first)
        printf("That was a circular list\n");

    exit(EXIT_SUCCESS);
}

---

🫶 SEE ALSO 🫶

• queue(7)

---

and that's the whole page, bestie!! this was Linux man-pages 6.20, dated 2026-02-08 — written by the man-pages girlies, delivered to you with love. mwah 💋 go build a linked list, you've got this 💖✨