lsearch(S)                     6 January 1993                     lsearch(S)


 Name

    lsearch, lfind - linear search and update

 Syntax


    cc  . . .  -lc


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

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

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


 Description

    The lsearch function is a linear search routine generalized from Knuth
    (6.1) Algorithm S.  It returns a pointer into a table indicating where an
    entry may be found.  If the entry does not occur, it is added at the end
    of the table.  The key argument points to the entry to be sought in the
    table.  The base argument points to the first element in the table.  The
    nelp argument points to an integer containing the current number of ele-
    ments in the table.  The width argument is the size of an element in
    bytes.  The integer is incremented if the entry is added to the table.
    The compar argument is the name of the comparison function which the user
    must supply (strcmp, for example).  It is called with two arguments that
    point to the elements being compared.  The function must return zero if
    the elements are equal and non-zero otherwise.

    The lfind function is the same as lsearch except that if the entry is not
    found, it is not added to the table. Instead, a NULL pointer is returned.

 Example

    This fragment reads in less than TABSIZE strings of length less than
    ELSIZE and stores them in a table, eliminating duplicates.

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

       #define TABSIZE 50
       #define ELSIZE 120

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


 Diagnostics

    If the searched-for entry is found, both lsearch and lfind return a
    pointer to it.  Otherwise, lfind returns NULL and lsearch returns a
    pointer to the newly added element.

 Notes

    The pointers to the key and the element at the base of the table should
    be of type pointer-to-element, and cast to type pointer-to-character.

    The comparison function need not compare every byte, so arbitrary data
    may be contained in the elements in addition to the values being com-
    pared.

    Although declared as type pointer-to-character, the value returned should
    be cast into type pointer-to-element.

    Undefined results can occur if there is not enough room in the table to
    add a new item.

 See also

    bsearch(S), hsearch(S), string(S), tsearch(S)

 Standards conformance

    lfind and lsearch are conformant with:
    AT&T SVID Issue 2;
    and X/Open Portability Guide, Issue 3, 1989.