lib/libc/stdlib/lsearch.3

   1 .\"
   2 .\" Initial implementation:
   3 .\" Copyright (c) 2002 Robert Drehmel
   4 .\" All rights reserved.
   5 .\"
   6 .\" As long as the above copyright statement and this notice remain
   7 .\" unchanged, you can do what ever you want with this file.
   8 .\"
   9 .Dd April 17, 2016
  10 .Dt LSEARCH 3
  11 .Os
  12 .Sh NAME
  13 .Nm lsearch ,
  14 .Nm lfind
  15 .Nd linear search and append
  16 .Sh LIBRARY
  17 .Lb libc
  18 .Sh SYNOPSIS
  19 .In search.h
  20 .Ft "void *"
  21 .Fo lsearch
  22 .Fa "const void *key" "void *base" "size_t *nelp" "size_t width"
  23 .Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  24 .Fc
  25 .Ft "void *"
  26 .Fo lfind
  27 .Fa "const void *key" "const void *base" "size_t *nelp" "size_t width"
  28 .Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]"
  29 .Fc
  30 .Sh DESCRIPTION
  31 The
  32 .Fn lsearch
  33 and
  34 .Fn lfind
  35 functions walk linearly through an array and compare each element with
  36 the one to be sought using a supplied comparison function.
  37 .Pp
  38 The
  39 .Fa key
  40 argument
  41 points to an element that matches the one that is searched.
  42 The array's address in memory is denoted by the
  43 .Fa base
  44 argument.
  45 The width of one element (i.e., the size as returned by
  46 .Fn sizeof )
  47 is passed as the
  48 .Fa width
  49 argument.
  50 The number of valid elements contained in the array (not the number of
  51 elements the array has space reserved for) is given in the integer pointed
  52 to by
  53 .Fa nelp .
  54 The
  55 .Fa compar
  56 argument points to a function which compares its two arguments and returns
  57 zero if they are matching, and non-zero otherwise.
  58 .Pp
  59 If no matching element was found in the array,
  60 .Fn lsearch
  61 copies
  62 .Fa key
  63 into the position after the last element and increments the
  64 integer pointed to by
  65 .Fa nelp .
  66 .Sh RETURN VALUES
  67 The
  68 .Fn lsearch
  69 and
  70 .Fn lfind
  71 functions
  72 return a pointer to the first element found.
  73 If no element was found,
  74 .Fn lsearch
  75 returns a pointer to the newly added element, whereas
  76 .Fn lfind
  77 returns
  78 .Dv NULL .
  79 Both functions return
  80 .Dv NULL
  81 if an error occurs.
  82 .Sh EXAMPLES
  83 .Bd -literal
  84 #include <search.h>
  85 #include <stdio.h>
  86 #include <stdlib.h>
  87
  88 static int
  89 element_compare(const void *p1, const void *p2)
  90 {
  91         int left = *(const int *)p1;
  92         int right = *(const int *)p2;
  93
  94         return (left - right);
  95 }
  96
  97 int
  98 main(int argc, char **argv)
  99 {
 100         const int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
 101         size_t element_size = sizeof(array[0]);
 102         size_t array_size = sizeof(array) / element_size;
 103         int key;
 104         void *element;
 105
 106         printf("Enter a number: ");
 107         if (scanf("%d", &key) != 1) {
 108                 printf("Bad input\en");
 109                 return (EXIT_FAILURE);
 110         }
 111
 112         element = lfind(&key, array, &array_size, element_size,
 113             element_compare);
 114
 115         if (element != NULL)
 116                 printf("Element found: %d\en", *(int *)element);
 117         else
 118                 printf("Element not found\en");
 119
 120         return (EXIT_SUCCESS);
 121 }
 122 .Ed
 123 .Sh SEE ALSO
 124 .Xr bsearch 3 ,
 125 .Xr hsearch 3 ,
 126 .Xr tsearch 3
 127 .Sh STANDARDS
 128 The
 129 .Fn lsearch
 130 and
 131 .Fn lfind
 132 functions conform to
 133 .St -p1003.1-2001 .
 134 .Sh HISTORY
 135 The
 136 .Fn lsearch
 137 and
 138 .Fn lfind
 139 functions appeared in
 140 .Bx 4.2 .
 141 In
 142 .Fx 5.0 ,
 143 they reappeared conforming to
 144 .St -p1003.1-2001 .