[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

lsearch or lfind Subroutine


Performs a linear search and update.


Standard C Library (libc.a)


void *lsearch (Key, Base, NumberOfElementsPointer, Width, ComparisonPointer)
const void *Key;
void *Base;
size_t Width, *NumberOfElementsPointer;
int (*ComparisonPointer) (cont void*, const void*);

void *lfind (Key, Base, NumberOfElementsPointer, Width, ComparisonPointer)
const void *Key, Base;
size_t Width, *NumberOfElementsPointer;
int (*ComparisonPointer) (cont void*, const void*);


Warning: Undefined results can occur if there is not enough room in the table for the lsearch subroutine to add a new item.

The lsearch subroutine performs a linear search.

The algorithm returns a pointer to a table where data can be found. If the data is not in the table, the program adds it at the end of the table.

The lfind subroutine is identical to the lsearch subroutine, except that if the data is not found, it is not added to the table. In this case, a NULL pointer is returned.

The pointers to the Key parameter and the element at the base of the table should be of type pointer-to-element and cast to type pointer-to-character. The value returned should be cast into type pointer-to-element.

The comparison function need not compare every byte; therefore, the elements can contain arbitrary data in addition to the values being compared.


Base Points to the first element in the table.
ComparisonPointer Specifies the name (that you supply) of the comparison function (strcmp, for example). It is called with two parameters that point to the elements being compared.
Key Specifies the data to be sought in the table.
NumberOfElementsPointer Points to an integer containing the current number of elements in the table. This integer is incremented if the data is added to the table.
Width Specifies the size of an element in bytes.

The comparison function compares its parameters and returns a value as follows:

Return Values

If the sought entry is found, both the lsearch and lfind subroutines return a pointer to it. Otherwise, the lfind subroutine returns a null pointer and the lsearch subroutine returns a pointer to the newly added element.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The bsearch (bsearch Subroutine) subroutine, hsearch (hsearch, hcreate, or hdestroy Subroutine) subroutine, qsort subroutine, tsearch subroutine.

Donald E. Knuth. The Art of Computer Programming, Volume 3, 6.1, Algorithm S. Reading, Massachusetts: Addison-Wesley, 1981.

Searching and Sorting Example Program and Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]