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 October 11, 2002
  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 SEE ALSO
  85 .Xr bsearch 3 ,
  86 .Xr hsearch 3 ,
  87 .Xr tsearch 3
  88 .Sh STANDARDS
  89 The
  90 .Fn lsearch
  91 and
  92 .Fn lfind
  93 functions conform to
  94 .St -p1003.1-2001 .
  95 .Sh HISTORY
  96 The
  97 .Fn lsearch
  98 and
  99 .Fn lfind
 100 functions appeared in
 101 .Bx 4.2 .
 102 In
 103 .Fx 5.0 ,
 104 they reappeared conforming to
 105 .St -p1003.1-2001 .