LSEARCH(3P)

LSEARCH(3P) 💖 linear search but make it iconic

okay bestie, welcome to the POSIX Programmer's Manual ✨ this one's a little letter called LSEARCH(3P) and it's giving "I just want to find my thing in a table and maybe add it if it's not there" energy. let's get into it 🫶

---

🌸 PROLOG 🌸

so like, real talk first: this page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ — like, consult the corresponding Linux manual page for the deets on Linux behavior, bestie — or honestly the interface might not even be implemented on Linux at all. 💀 no cap.

---

✨ NAME ✨

lsearch, lfind — linear search and update 💅

---

🎀 SYNOPSIS 🎀

#include <search.h>

void *lsearch(const void *key, void *base, size_t *nelp, size_t width,
    int (*compar)(const void *, const void *));
void *lfind(const void *key, const void *base, size_t *nelp,
    size_t width, int (*compar)(const void *, const void *));

---

💜 DESCRIPTION 💜

okay so lsearch() shall linearly search the table and return a pointer into the table for the matching entry 🔍 and if that entry does not occur, it shall be added at the end of the table. periodt.

let's break down the cast of characters, because there's a lot of them:

• key — points to the entry you're looking for in the table 👀
• base — points to the first element in the table
• width — the size of one element, in bytes 📏
• nelp — points to an integer holding the current number of elements in the table. and listen: that integer to which nelp points shall be incremented if the entry gets added to the table 👑
• compar — points to a comparison function that the application shall supply (for example, strcmp()). it gets called with two arguments that point to the elements being compared. and the application shall ensure that this function returns 0 if the elements are equal, and non-zero otherwise. no pressure 🫶

now lfind()? she's the chill twin. lfind() shall be equivalent to lsearch(), EXCEPT — and this is the whole plot twist — if the entry is not found, it is not added to the table. instead, a null pointer is returned. she's not here to expand your table, she's just here to look. 🙈

---

🔥 RETURN VALUE 🔥

if the searched-for entry is found, both lsearch() and lfind() shall return a pointer to it 💖

otherwise:

• lfind() shall return a null pointer
• lsearch() shall return a pointer to the newly added element

and both functions shall return a null pointer in case of error. 💀

---

🌈 ERRORS 🌈

No errors are defined.

and the following sections are informative (iykyk, they're the bonus content, not the rules) ⭐

---

🦋 EXAMPLES 🦋

🌸 Storing Strings in a Table 🌸

this fragment reads in less than or equal to TABSIZE strings of length less than or equal to ELSIZE and stores them in a table, eliminating duplicates. she's efficient, she's clean, she slays ✨

#include <stdio.h>
#include <string.h>
#include <search.h>

#define TABSIZE 50
#define ELSIZE 120

...
    char line[ELSIZE], tab[TABSIZE][ELSIZE];
    size_t nel = 0;
    ...
    while (fgets(line, ELSIZE, stdin) != NULL && nel < TABSIZE)
        (void) lsearch(line, tab, &nel,
            ELSIZE, (int (*)(const void *, const void *)) strcmp);
    ...

💅 Finding a Matching Entry 💅

this next one finds any line that reads "Thisisatest.". ok the prose says that, the code says "This is a test.\n" — we're keeping both exactly as written, that's the vibe, don't @ me 🫶

#include <search.h>
#include <string.h>
...
char line[ELSIZE], tab[TABSIZE][ELSIZE];
size_t nel = 0;
char *findline;
void *entry;

findline = "This is a test.\n";

entry = lfind(findline, tab, &nel, ELSIZE, (
    int (*)(const void *, const void *)) strcmp);

---

👑 APPLICATION USAGE 👑

the comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared. like, she's flexible, she's not judging your struct 💜

⚠️ Undefined results can occur if there is not enough room in the table to add a new item. ⚠️ fr fr, bestie, make sure your table has room. this is the "check your bag before you leave the house" of this function. 😭

---

🧚 RATIONALE 🧚

None.

she simply had nothing to add. silence. iconic. 💅

---

⭐ FUTURE DIRECTIONS ⭐

None.

the future is bright and also unchanged ✨

---

🎀 SEE ALSO 🎀

• hcreate()
• tdelete()
• The Base Definitions volume of POSIX.1‐2017, <search.h>

---

💖 COPYRIGHT 💖

okay legal bestie moment, we gotta be respectful 🫶

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

and that's the whole page, bestie!! 💖 brought to you by IEEE/The Open Group, 2017 — yes that's the source and the date, and yes they ate. go find your elements, add them if they're missing, and remember: lsearch adds, lfind just looks. periodt. 💅✨🦋