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