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 April 21, 2013 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 EXAMPLES 85.Bd -literal 86#include <search.h> 87#include <stdio.h> 88#include <stdlib.h> 89 90static int 91element_compare(const void *p1, const void *p2) 92{ 93 int left = *(const int *)p1; 94 int right = *(const int *)p2; 95 96 return (left - right); 97} 98 99int 100main(int argc, char **argv) 101{ 102 const int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; 103 size_t element_size = sizeof(array[0]); 104 size_t array_size = sizeof(array) / element_size; 105 int key; 106 void *element; 107 108 printf("Enter a number: "); 109 if (scanf("%d", &key) != 1) { 110 printf("Bad input\n"); 111 return (EXIT_FAILURE); 112 } 113 114 element = lfind(&key, array, &array_size, element_size, 115 element_compare); 116 117 if (element != NULL) 118 printf("Element found: %d\n", *(int *)element); 119 else 120 printf("Element not found\n"); 121 122 return (EXIT_SUCCESS); 123} 124.Ed 125.Sh SEE ALSO 126.Xr bsearch 3 , 127.Xr hsearch 3 , 128.Xr tsearch 3 129.Sh STANDARDS 130The 131.Fn lsearch 132and 133.Fn lfind 134functions conform to 135.St -p1003.1-2001 . 136.Sh HISTORY 137The 138.Fn lsearch 139and 140.Fn lfind 141functions appeared in 142.Bx 4.2 . 143In 144.Fx 5.0 , 145they reappeared conforming to 146.St -p1003.1-2001 . 147