16c84d0b1SRobert Drehmel.\" 26c84d0b1SRobert Drehmel.\" Initial implementation: 36c84d0b1SRobert Drehmel.\" Copyright (c) 2002 Robert Drehmel 46c84d0b1SRobert Drehmel.\" All rights reserved. 56c84d0b1SRobert Drehmel.\" 66c84d0b1SRobert Drehmel.\" As long as the above copyright statement and this notice remain 76c84d0b1SRobert Drehmel.\" unchanged, you can do what ever you want with this file. 86c84d0b1SRobert Drehmel.\" 96c84d0b1SRobert Drehmel.\" $FreeBSD$ 106c84d0b1SRobert Drehmel.\" 116c84d0b1SRobert Drehmel.Dd October 11, 2002 126c84d0b1SRobert Drehmel.Dt LSEARCH 3 136c84d0b1SRobert Drehmel.Os 146c84d0b1SRobert Drehmel.Sh NAME 156c84d0b1SRobert Drehmel.Nm lsearch , 166c84d0b1SRobert Drehmel.Nm lfind 176c84d0b1SRobert Drehmel.Nd linear search and append 186c84d0b1SRobert Drehmel.Sh LIBRARY 196c84d0b1SRobert Drehmel.Lb libc 206c84d0b1SRobert Drehmel.Sh SYNOPSIS 216c84d0b1SRobert Drehmel.In search.h 226c84d0b1SRobert Drehmel.Ft void * 236c84d0b1SRobert Drehmel.Fn lsearch "const void *key" "void *base" "size_t *nelp" "size_t width" \ 246c84d0b1SRobert Drehmel "int (*compar)(const void *, const void *)" 256c84d0b1SRobert Drehmel.Ft void * 266c84d0b1SRobert Drehmel.Fn lfind "const void *key" "const void *base" "size_t *nelp" "size_t width" \ 276c84d0b1SRobert Drehmel "int (*compar)(const void *, const void *)" 286c84d0b1SRobert Drehmel.Sh DESCRIPTION 296c84d0b1SRobert Drehmel.Pp 306c84d0b1SRobert DrehmelThe 316c84d0b1SRobert Drehmel.Fn lsearch 326c84d0b1SRobert Drehmeland 336c84d0b1SRobert Drehmel.Fn lfind 346c84d0b1SRobert Drehmelfunctions walk linearly through an array and compare each element with 356c84d0b1SRobert Drehmelthe one to be sought using a supplied comparison function. 366c84d0b1SRobert Drehmel.Pp 376c84d0b1SRobert Drehmel.Fa key 386c84d0b1SRobert Drehmelpoints to an element that matches the one that is searched. 396c84d0b1SRobert DrehmelThe array's address in memory is denoted by the 406c84d0b1SRobert Drehmel.Fa base 416c84d0b1SRobert Drehmelargument. 426c84d0b1SRobert DrehmelThe width of one element (i.e. the size as returned by 436c84d0b1SRobert Drehmel.Fn sizeof ) 446c84d0b1SRobert Drehmelis passed as the 456c84d0b1SRobert Drehmel.Fa width 466c84d0b1SRobert Drehmelargument. 476c84d0b1SRobert DrehmelThe number of valid elements contained in the array (not the number of 486c84d0b1SRobert Drehmelelements the array has space reserved for) is given in the integer pointed 496c84d0b1SRobert Drehmelto by 506c84d0b1SRobert Drehmel.Fa nelp . 516c84d0b1SRobert DrehmelThe 526c84d0b1SRobert Drehmel.Fa compar 536c84d0b1SRobert Drehmelargument points to a function which compares its two arguments and returns 546c84d0b1SRobert Drehmelzero if they are matching and non-zero otherwise. 556c84d0b1SRobert Drehmel.Pp 566c84d0b1SRobert DrehmelIf no matching element was found in the array, 576c84d0b1SRobert Drehmel.Fn lsearch 586c84d0b1SRobert Drehmelcopies 596c84d0b1SRobert Drehmel.Fa key 606c84d0b1SRobert Drehmelinto the position after the last element and increments the 616c84d0b1SRobert Drehmelinteger pointed to by 626c84d0b1SRobert Drehmel.Fa nelp . 636c84d0b1SRobert Drehmel.Sh RETURN VALUES 646c84d0b1SRobert Drehmel.Fn lsearch 656c84d0b1SRobert Drehmeland 666c84d0b1SRobert Drehmel.Fn lfind 676c84d0b1SRobert Drehmelreturn a pointer to the first element found. 686c84d0b1SRobert DrehmelIf no element was found, 696c84d0b1SRobert Drehmel.Fn lsearch 706c84d0b1SRobert Drehmelreturns a pointer to the newly added element, whereas 716c84d0b1SRobert Drehmel.Fn lfind 726c84d0b1SRobert Drehmelreturns 736c84d0b1SRobert Drehmel.Dv NULL . 746c84d0b1SRobert DrehmelBoth functions return 756c84d0b1SRobert Drehmel.Dv NULL 766c84d0b1SRobert Drehmelif an error occurs. 776c84d0b1SRobert Drehmel.Sh SEE ALSO 786c84d0b1SRobert Drehmel.Xr bsearch 3 , 796c84d0b1SRobert Drehmel.Xr hsearch 3 , 806c84d0b1SRobert Drehmel.Xr tsearch 3 816c84d0b1SRobert Drehmel.Sh HISTORY 826c84d0b1SRobert DrehmelThe 836c84d0b1SRobert Drehmel.Fn lsearch 846c84d0b1SRobert Drehmeland 856c84d0b1SRobert Drehmel.Fn lfind 866c84d0b1SRobert Drehmelfunctions appeared in 876c84d0b1SRobert Drehmel.Bx 4.2 . 886c84d0b1SRobert DrehmelIn 896c84d0b1SRobert Drehmel.Fx 5.0 , 906c84d0b1SRobert Drehmelthey reappeared conforming to 916c84d0b1SRobert Drehmel.St -p1003.1-2001 . 926c84d0b1SRobert Drehmel.Sh STANDARDS 936c84d0b1SRobert DrehmelThe 946c84d0b1SRobert Drehmel.Fn lsearch 956c84d0b1SRobert Drehmeland 966c84d0b1SRobert Drehmel.Fn lfind 976c84d0b1SRobert Drehmelfunctions conform to 986c84d0b1SRobert Drehmel.St -p1003.1-2001 . 99