man3/lsearch.3

   1 '\" t
   2 .\" Copyright 1995 Jim Van Zandt <jrv@vanzandt.mv.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Corrected prototype and include, aeb, 990927
   7 .TH lsearch 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 lfind, lsearch \- linear search of an array
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <search.h>
  16 .PP
  17 .BI "void *lfind(const void " key [. size "], \
  18 const void " base [. size " * ." nmemb ],
  19 .BI "            size_t *" nmemb ", size_t " size ,
  20 .BI "            int(*" compar ")(const void [." size "], \
  21 const void [." size ]));
  22 .BI "void *lsearch(const void " key [. size "], \
  23 void " base [. size " * ." nmemb ],
  24 .BI "            size_t *" nmemb ", size_t " size ,
  25 .BI "            int(*" compar ")(const void [." size "], \
  26 const void [." size ]));
  27 .fi
  28 .SH DESCRIPTION
  29 .BR lfind ()
  30 and
  31 .BR lsearch ()
  32 perform a linear search for
  33 .I key
  34 in the array
  35 .I base
  36 which has
  37 .I *nmemb
  38 elements of
  39 .I size
  40 bytes each.
  41 The comparison function referenced by
  42 .I compar
  43 is expected to have two arguments which point to the
  44 .I key
  45 object and to an array member, in that order, and which
  46 returns zero if the
  47 .I key
  48 object matches the array member, and
  49 nonzero otherwise.
  50 .PP
  51 If
  52 .BR lsearch ()
  53 does not find a matching element, then the
  54 .I key
  55 object is inserted at the end of the table, and
  56 .I *nmemb
  57 is
  58 incremented.
  59 In particular, one should know that a matching element
  60 exists, or that more room is available.
  61 .SH RETURN VALUE
  62 .BR lfind ()
  63 returns a pointer to a matching member of the array, or
  64 NULL if no match is found.
  65 .BR lsearch ()
  66 returns a pointer to
  67 a matching member of the array, or to the newly added member if no
  68 match is found.
  69 .SH ATTRIBUTES
  70 For an explanation of the terms used in this section, see
  71 .BR attributes (7).
  72 .ad l
  73 .nh
  74 .TS
  75 allbox;
  76 lbx lb lb
  77 l l l.
  78 Interface       Attribute       Value
  79 T{
  80 .BR lfind (),
  81 .BR lsearch ()
  82 T}      Thread safety   MT-Safe
  83 .TE
  84 .hy
  85 .ad
  86 .sp 1
  87 .SH STANDARDS
  88 POSIX.1-2008.
  89 .SH HISTORY
  90 POSIX.1-2001, SVr4, 4.3BSD.
  91 libc-4.6.27.
  92 .SH BUGS
  93 The naming is unfortunate.
  94 .SH SEE ALSO
  95 .BR bsearch (3),
  96 .BR hsearch (3),
  97 .BR tsearch (3)