Standard C Library Functions                          lsearch(3C)



NAME
     lsearch, lfind - linear search and update

SYNOPSIS
     #include 

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


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


DESCRIPTION
     The lsearch() function is a linear search  routine  general-
     ized  from Knuth (6.1) Algorithm S. (see The Art of Computer
     Programming, Volume 3, Section 6.1, by Donald E. Knuth.). It
     returns a pointer to a table indicating where a datum can be
     found. If the datum does not occur, it is added at  the  end
     of  the  table.  The  key argument points to the datum 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  elements in the table. The
     integer  is  incremented if the datum is added to the table.
     The width argument is the size of an element in  bytes.  The
     compar argument is a pointer to the comparison function that
     the user must supply (strcmp(3C) for example). It is  called
     with  two  arguments  that  point to the elements being com-
     pared. 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  datum  is  not  found,  it  is  not added to the table.
     Instead, a null pointer is returned.


     It is important to note the following:

         o    The pointers to the key and the element at the base
              of the table can be pointers to any type.

         o    The comparison  function  need  not  compare  every
              byte,  so  arbitrary  data  can be contained in the
              elements in addition to the values being compared.

         o    The  value  returned  should  be  cast  into   type
              pointer-to-element.

RETURN VALUES




SunOS 5.11           Last change: 6 Dec 2004                    1






Standard C Library Functions                          lsearch(3C)



     If the searched-for  datum  is  found,  both  lsearch()  and
     lfind()  return  a pointer to it. Otherwise, lfind() returns
     NUL and  lsearch() returns a pointer  to  the  newly  added
     element.

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


     The lsearch() and lfind() functions safely allows concurrent
     access  by  multiple threads to disjoint data, such as over-
     lapping subtrees or tables.

EXAMPLES
     Example 1 A sample code using the lsearch() function.


     This program will read  in  less  than  TABSIZE  strings  of
     length less than ELSIZE and store them in a table, eliminat-
     ing duplicates, and then will print each entry.


       #include 
       #include 
       #include 
       #include 

       #define TABSIZE 50
       #define ELSIZE 120

       main()
       {
           char line[ELSIZE];          /* buffer to hold input string */
           char tab[TABSIZE][ELSIZE];  /* table of strings */
           sizet nel = 0;             /* number of entries in tab */
           int i;

           while (fgets(line, ELSIZE, stdin) != NUL &&
                   nel < TABSIZE)
                   (void) lsearch(line, tab, &nel, ELSIZE, mycmp);
           for( i = 0; i < nel; i] )
                   (void)fputs(tab[i], stdout);
           return 0;
       }


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:





SunOS 5.11           Last change: 6 Dec 2004                    2






Standard C Library Functions                          lsearch(3C)



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     bsearch(3C), hsearch(3C),  string(3C),  tsearch(3C),  attri-
     butes(5), standards(5)


     The Art of  Computer  Programming,  Volume  3,  Sorting  and
     Searching  by  Donald  E. Knuth, published by Addison-Wesley
     Publishing Company, 1973.






































SunOS 5.11           Last change: 6 Dec 2004                    3