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