NetBSD/lib/libc/gen/lsearch.3

86 lines
3.1 KiB
Groff

.\" Copyright (c) 1993 Winning Strategies, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by Winning Strategies, Inc.
.\" 4. The name of the author may not be used to endorse or promote products
.\" derived from this software without specific prior written permission
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: lsearch.3,v 1.2 1994/01/28 20:41:01 jtc Exp $
.\"
.Dd October 21, 1993
.Dt LSEARCH 3
.Os
.Sh NAME
.Nm lsearch ,
.Nm lfind
.Nd linear search and update
.Sh SYNOPSIS
.Fd #include <search.h>
.Ft void *
.Fn lsearch "void *key" "void *base" "size_t *nelp" "size_t width" "int (*compar)(const void *, const void *)"
.Ft void *
.Fn lfind "void *key" "void *base" "size_t *nelp" "size_t width" "int (*compar)(const void *, const void *)"
.Sh DESCRIPTION
.Fn Lsearch
is a linear search.
If the entry is not found, it is added to the end of the table.
.Pp
.Fa Key
points to the entry to be searched for.
.Fa Base
points to the first element of the table.
.Fa Nelp
points to an integer containing the number of elements in the table.
The integer is incremented whenever an entry is added.
.Fa Width
is the size of an element in bytes.
The user supplied comparison function
.Fa compar
is called with two arguments that point to the elements being compared.
The comparison function must return zero if the elements are equal and non-zero
if they are not.
.Pp
.Fn Lfind
is the same as
.Fn lsearch ,
except if the entry is not found, it is not added to the table.
.Sh RETURN VALUES
.Fn Lsearch
and
.Fn lfind
return a pointer to the entry if it was found.
Otherwise,
.Fn lsearch
returns a pointer to the newly added element, and
.Fn lfind
returns a
.Dv NULL
pointer.
.Sh SEE ALSO
.Xr bsearch 3 ,
.Xr hsearch 3 ,
.Xr tsearch 3
.Sh AUTHORS
J.T. Conklin