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 34The 35.Fn lsearch 36and 37.Fn lfind 38functions walk linearly through an array and compare each element with 39the one to be sought using a supplied comparison function. 40.Pp 41The 42.Fa key 43argument 44points to an element that matches the one that is searched. 45The array's address in memory is denoted by the 46.Fa base 47argument. 48The width of one element (i.e., the size as returned by 49.Fn sizeof ) 50is passed as the 51.Fa width 52argument. 53The number of valid elements contained in the array (not the number of 54elements the array has space reserved for) is given in the integer pointed 55to by 56.Fa nelp . 57The 58.Fa compar 59argument points to a function which compares its two arguments and returns 60zero if they are matching, and non-zero otherwise. 61.Pp 62If no matching element was found in the array, 63.Fn lsearch 64copies 65.Fa key 66into the position after the last element and increments the 67integer pointed to by 68.Fa nelp . 69.Sh RETURN VALUES 70The 71.Fn lsearch 72and 73.Fn lfind 74functions 75return a pointer to the first element found. 76If no element was found, 77.Fn lsearch 78returns a pointer to the newly added element, whereas 79.Fn lfind 80returns 81.Dv NULL . 82Both functions return 83.Dv NULL 84if an error occurs. 85.Sh SEE ALSO 86.Xr bsearch 3 , 87.Xr hsearch 3 , 88.Xr tsearch 3 89.Sh STANDARDS 90The 91.Fn lsearch 92and 93.Fn lfind 94functions conform to 95.St -p1003.1-2001 . 96.Sh HISTORY 97The 98.Fn lsearch 99and 100.Fn lfind 101functions appeared in 102.Bx 4.2 . 103In 104.Dx 1.13 105they reappeared conforming to 106.St -p1003.1-2001 . 107