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