Technical Reference: Base Operating System and Extensions, Volume 1

lsearch or lfind Subroutine

Purpose

Performs a linear search and update.

Library

Standard C Library (libc.a)

Syntax

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*);

Description

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.

Parameters

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:

If the first parameter equals the second parameter, the ComparisonPointer parameter returns a value of 0.
If the first parameter does not equal the second parameter, the ComparisonPointer parameter returns a value of 1.

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.

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.2 General Programming Concepts: Writing and Debugging Programs.