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: src/lib/libc/stdlib/lsearch.3,v 1.5 2005/01/20 09:17:04 ru Exp $
  10 .\" $DragonFly: src/lib/libc/stdlib/lsearch.3,v 1.1 2008/05/19 10:06:34 corecode Exp $
  11 .\"
  12 .Dd May 18, 2008
  13 .Dt LSEARCH 3
  14 .Os
  15 .Sh NAME
  16 .Nm lsearch ,
  17 .Nm lfind
  18 .Nd linear search and append
  19 .Sh LIBRARY
  20 .Lb libc
  21 .Sh SYNOPSIS
  22 .In search.h
  23 .Ft "void *"
  24 .Fo lsearch
  25 .Fa "const void *key" "void *base" "size_t *nelp" "size_t width"
  26 .Fa "int (*compar)(const void *, const void *)"
  27 .Fc
  28 .Ft "void *"
  29 .Fo lfind
  30 .Fa "const void *key" "const void *base" "size_t *nelp" "size_t width"
  31 .Fa "int (*compar)(const void *, const void *)"
  32 .Fc
  33 .Sh DESCRIPTION
  34 The
  35 .Fn lsearch
  36 and
  37 .Fn lfind
  38 functions walk linearly through an array and compare each element with
  39 the one to be sought using a supplied comparison function.
  40 .Pp
  41 The
  42 .Fa key
  43 argument
  44 points to an element that matches the one that is searched.
  45 The array's address in memory is denoted by the
  46 .Fa base
  47 argument.
  48 The width of one element (i.e., the size as returned by
  49 .Fn sizeof )
  50 is passed as the
  51 .Fa width
  52 argument.
  53 The number of valid elements contained in the array (not the number of
  54 elements the array has space reserved for) is given in the integer pointed
  55 to by
  56 .Fa nelp .
  57 The
  58 .Fa compar
  59 argument points to a function which compares its two arguments and returns
  60 zero if they are matching, and non-zero otherwise.
  61 .Pp
  62 If no matching element was found in the array,
  63 .Fn lsearch
  64 copies
  65 .Fa key
  66 into the position after the last element and increments the
  67 integer pointed to by
  68 .Fa nelp .
  69 .Sh RETURN VALUES
  70 The
  71 .Fn lsearch
  72 and
  73 .Fn lfind
  74 functions
  75 return a pointer to the first element found.
  76 If no element was found,
  77 .Fn lsearch
  78 returns a pointer to the newly added element, whereas
  79 .Fn lfind
  80 returns
  81 .Dv NULL .
  82 Both functions return
  83 .Dv NULL
  84 if an error occurs.
  85 .Sh SEE ALSO
  86 .Xr bsearch 3 ,
  87 .Xr hsearch 3 ,
  88 .Xr tsearch 3
  89 .Sh STANDARDS
  90 The
  91 .Fn lsearch
  92 and
  93 .Fn lfind
  94 functions conform to
  95 .St -p1003.1-2001 .
  96 .Sh HISTORY
  97 The
  98 .Fn lsearch
  99 and
 100 .Fn lfind
 101 functions appeared in
 102 .Bx 4.2 .
 103 In
 104 .Dx 1.13
 105 they reappeared conforming to
 106 .St -p1003.1-2001 .