1 files changed, 98 insertions, 0 deletions
diff --git a/lib/libc/stdlib/lsearch.3 b/lib/libc/stdlib/lsearch.3
new file mode 100644
index 0000000..a53dcb1
--- /dev/null
+++ b/lib/libc/stdlib/lsearch.3
@@ -0,0 +1,98 @@
+.\"
+.\" Initial implementation:
+.\" Copyright (c) 2002 Robert Drehmel
+.\" All rights reserved.
+.\"
+.\" As long as the above copyright statement and this notice remain
+.\" unchanged, you can do what ever you want with this file. 
+.\"
+.\" $FreeBSD$
+.\"
+.Dd October 11, 2002
+.Dt LSEARCH 3
+.Os
+.Sh NAME
+.Nm lsearch ,
+.Nm lfind
+.Nd linear search and append
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In search.h
+.Ft void *
+.Fn lsearch "const void *key" "void *base" "size_t *nelp" "size_t width" \
+    "int (*compar)(const void *, const void *)"
+.Ft void *
+.Fn lfind "const void *key" "const void *base" "size_t *nelp" "size_t width" \
+    "int (*compar)(const void *, const void *)"
+.Sh DESCRIPTION
+.Pp
+The
+.Fn lsearch
+and
+.Fn lfind
+functions walk linearly through an array and compare each element with
+the one to be sought using a supplied comparison function.
+.Pp
+.Fa key
+points to an element that matches the one that is searched.
+The array's address in memory is denoted by the 
+.Fa base
+argument.
+The width of one element (i.e. the size as returned by
+.Fn sizeof )
+is passed as the   
+.Fa width 
+argument.
+The number of valid elements contained in the array (not the number of
+elements the array has space reserved for) is given in the integer pointed
+to by
+.Fa nelp .
+The
+.Fa compar
+argument points to a function which compares its two arguments and returns
+zero if they are matching and non-zero otherwise.
+.Pp
+If no matching element was found in the array, 
+.Fn lsearch 
+copies
+.Fa key
+into the position after the last element and increments the
+integer pointed to by
+.Fa nelp .
+.Sh RETURN VALUES
+.Fn lsearch
+and
+.Fn lfind
+return a pointer to the first element found.
+If no element was found,
+.Fn lsearch
+returns a pointer to the newly added element, whereas
+.Fn lfind
+returns
+.Dv NULL .
+Both functions return
+.Dv NULL
+if an error occurs.
+.Sh SEE ALSO
+.Xr bsearch 3 ,
+.Xr hsearch 3 ,
+.Xr tsearch 3
+.Sh HISTORY
+The
+.Fn lsearch
+and
+.Fn lfind
+functions appeared in
+.Bx 4.2 .
+In
+.Fx 5.0 ,
+they reappeared conforming to
+.St -p1003.1-2001 .
+.Sh STANDARDS
+The
+.Fn lsearch
+and
+.Fn lfind
+functions conform to
+.St -p1003.1-2001 .