bsearch(3)

🌸 bsearch(3) — the glow-up edition 🌸

okay bestie, so <stdlib.h> has this absolute icon called bsearch(), and it's a binary search of a sorted array ✨ (that's the NAME, bestie, we're doing this properly). It lives in the Standard C library (libc, -lc) 🎀

---

🫶 SYNOPSIS 🫶

#include <stdlib.h>

void *bsearch(size_t n, size_t size;
              const void key[size], const void base[size * n],
              size_t n, size_t size,
              typeof(int (const void [size], const void [size]))
                  *compar);

no bestie I did not typo that, that's literally the synopsis, look it up 💅

---

✨ DESCRIPTION ✨

so what bsearch() does is it searches an array of n objects — and the very first member of that array is pointed to by base — looking for a member that matches the object pointed to by key. the size of each member of the array? that's specified by size. periodt. 👑

the contents of the array should be in ascending sorted order according to the comparison function referenced by compar. that's not optional advice, that's the vibe the whole function runs on 🔥

the compar routine is expected to have two arguments, and they point to the key object and to an array member, in that order. and it should return an integer that is less than, equal to, or greater than zero if the key object is found, respectively, to be less than, to match, or to be greater than the array member. so like, compar is the little matchmaker and the <0, ==0, >0 is how it says "nah", "IT'S THEM 💖", or "too far babe".

---

💅 RETURN VALUE 💅

bsearch() hands back a pointer to a matching member of the array, or NULL if no match is found. and here's the tea: if there are multiple elements that match the key, the element returned is unspecified. so like, don't get attached to which one shows up, bestie 🙈

---

🦋 ATTRIBUTES 🦋

(for an explanation of the terms used in this section, go see attributes(7) 📖)

• Interface bsearch()
• Attribute Thread safety
• Value MT-Safe

she's MT-Safe, she's unbothered, she's fine in a crowd 😌✨

---

🌈 STANDARDS 🌈

C11, POSIX.1-2008.

---

🧚 HISTORY 🧚

POSIX.1-2001, C89, C99, SVr4, 4.3BSD.

she's been iconic for DECADES, we love a legacy queen 👑

---

🍓 EXAMPLES 🍓

okay so this example first sorts an array of structs using qsort(3), and then retrieves the elements you want using bsearch(). sort then search, that's the whole plot bestie 🎬

#include <stdcountof.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

struct mi {
    int         nr;
    const char  *name;
};

static struct mi  months[] = {
    { 1, "jan" }, { 2, "feb" }, { 3, "mar" }, { 4, "apr" },
    { 5, "may" }, { 6, "jun" }, { 7, "jul" }, { 8, "aug" },
    { 9, "sep" }, {10, "oct" }, {11, "nov" }, {12, "dec" }
};

static int
compmi(const void *m1, const void *m2)
{
    const struct mi *mi1 = m1;
    const struct mi *mi2 = m2;

    return strcmp(mi1->name, mi2->name);
}

int
main(int argc, char *argv[])
{
    qsort(months, countof(months), sizeof(months[0]), compmi);
    for (size_t i = 1; i < argc; i++) {
        struct mi key;
        struct mi *res;

        key.name = argv[i];
        res = bsearch(&key, months, countof(months),
                      sizeof(months[0]), compmi);
        if (res == NULL)
            printf("'%s': unknown month\n", argv[i]);
        else
            printf("%s: month #%d\n", res->name, res->nr);
    }
    exit(EXIT_SUCCESS);
}

---

👑 SEE ALSO 👑

hsearch(3), lsearch(3), qsort(3), tsearch(3)

---

real talk bestie: bsearch() only works on an array that is already sorted in ascending order per compar. if it isn't, the results are undefined and nobody can save you 💀 sort first, search second, that's the rule 🫶

---

mwah, that's the whole page 💜 this came from Linux man-pages 6.20, dated 2026-02-10 — ily, go sort an array and find your key 🦋✨