Museum

     LSEARCH(S)                UNIX System V                LSEARCH(S)



     Name
          lsearch, lfind - linear search and update

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

          char *lsearch ((char *)key, (char *)base, nelp,
          sizeof(*key), compar)
          unsigned *nelp;
          int (*compar)( );

          char *lfind ((char *)key, (char *)base, nelp, sizeof(*key),
          compar)
          unsigned *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 a datum may be found.  If the datum
          does not occur, it is added at the end of the table.  key
          points to the datum to be sought in the table.  base points
          to the first element in the table.  nelp points to an
          integer containing the current number of elements in the
          table.  The integer is incremented if the datum is added to
          the table.  compar 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.

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

     Example
          This fragment will read in less than TABSIZE strings of
          length less than ELSIZE and store 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( );
               unsigned nel = 0;
               int strcmp( );
               . . .
               while (fgets(line, ELSIZE, stdin) != NULL &&
                  nel < TABSIZE)
                    (void) lsearch(line, (char *)tab, &nel,
                           ELSIZE, strcmp);
               . . .

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

     Diagnostics
          If the searched-for datum 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 compared.

          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.

     Standards Conformance
          lfind and lsearch are conformant with:
          AT&T SVID Issue 2, Select Code 307-127;
          and The X/Open Portability Guide II of January 1987.







                                             (printed 6/20/89)