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.Dd April 17, 2016 10.Dt LSEARCH 3 11.Os 12.Sh NAME 13.Nm lsearch , 14.Nm lfind 15.Nd linear search and append 16.Sh LIBRARY 17.Lb libc 18.Sh SYNOPSIS 19.In search.h 20.Ft "void *" 21.Fo lsearch 22.Fa "const void *key" "void *base" "size_t *nelp" "size_t width" 23.Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]" 24.Fc 25.Ft "void *" 26.Fo lfind 27.Fa "const void *key" "const void *base" "size_t *nelp" "size_t width" 28.Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]" 29.Fc 30.Sh DESCRIPTION 31The 32.Fn lsearch 33and 34.Fn lfind 35functions walk linearly through an array and compare each element with 36the one to be sought using a supplied comparison function. 37.Pp 38The 39.Fa key 40argument 41points to an element that matches the one that is searched. 42The array's address in memory is denoted by the 43.Fa base 44argument. 45The width of one element (i.e., the size as returned by 46.Fn sizeof ) 47is passed as the 48.Fa width 49argument. 50The number of valid elements contained in the array (not the number of 51elements the array has space reserved for) is given in the integer pointed 52to by 53.Fa nelp . 54The 55.Fa compar 56argument points to a function which compares its two arguments and returns 57zero if they are matching, and non-zero otherwise. 58.Pp 59If no matching element was found in the array, 60.Fn lsearch 61copies 62.Fa key 63into the position after the last element and increments the 64integer pointed to by 65.Fa nelp . 66.Sh RETURN VALUES 67The 68.Fn lsearch 69and 70.Fn lfind 71functions 72return a pointer to the first element found. 73If no element was found, 74.Fn lsearch 75returns a pointer to the newly added element, whereas 76.Fn lfind 77returns 78.Dv NULL . 79Both functions return 80.Dv NULL 81if an error occurs. 82.Sh EXAMPLES 83.Bd -literal 84#include <search.h> 85#include <stdio.h> 86#include <stdlib.h> 87 88static int 89element_compare(const void *p1, const void *p2) 90{ 91 int left = *(const int *)p1; 92 int right = *(const int *)p2; 93 94 return (left - right); 95} 96 97int 98main(int argc, char **argv) 99{ 100 const int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; 101 size_t element_size = sizeof(array[0]); 102 size_t array_size = sizeof(array) / element_size; 103 int key; 104 void *element; 105 106 printf("Enter a number: "); 107 if (scanf("%d", &key) != 1) { 108 printf("Bad input\en"); 109 return (EXIT_FAILURE); 110 } 111 112 element = lfind(&key, array, &array_size, element_size, 113 element_compare); 114 115 if (element != NULL) 116 printf("Element found: %d\en", *(int *)element); 117 else 118 printf("Element not found\en"); 119 120 return (EXIT_SUCCESS); 121} 122.Ed 123.Sh SEE ALSO 124.Xr bsearch 3 , 125.Xr hsearch 3 , 126.Xr tsearch 3 127.Sh STANDARDS 128The 129.Fn lsearch 130and 131.Fn lfind 132functions conform to 133.St -p1003.1-2001 . 134.Sh HISTORY 135The 136.Fn lsearch 137and 138.Fn lfind 139functions appeared in 140.Bx 4.2 . 141In 142.Fx 5.0 , 143they reappeared conforming to 144.St -p1003.1-2001 . 145