From f22795e90c0343742b46ca0a209a6e4059676f88 Mon Sep 17 00:00:00 2001 From: millert <> Date: Thu, 24 Jun 2004 04:43:33 +0000 Subject: Working hcreate(3) et al from NetBSD (cgd) via ray at cyth dot net. Now passes the regress tests. --- src/lib/libc/stdlib/hcreate.3 | 195 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 src/lib/libc/stdlib/hcreate.3 (limited to 'src/lib/libc/stdlib/hcreate.3') diff --git a/src/lib/libc/stdlib/hcreate.3 b/src/lib/libc/stdlib/hcreate.3 new file mode 100644 index 0000000000..d1d4e5c185 --- /dev/null +++ b/src/lib/libc/stdlib/hcreate.3 @@ -0,0 +1,195 @@ +.\" $OpenBSD: hcreate.3,v 1.1 2004/06/24 04:43:33 millert Exp $ +.\" $NetBSD: hcreate.3,v 1.6 2003/04/16 13:34:46 wiz Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Klaus Klein. +.\" +.\" 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 the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``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 FOUNDATION OR CONTRIBUTORS +.\" 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. +.\" +.Dd February 13, 2001 +.Dt HCREATE 3 +.Os +.Sh NAME +.Nm hcreate , +.Nm hdestroy , +.Nm hsearch +.Nd manage hash search table +.Sh SYNOPSIS +.In search.h +.Ft int +.Fn hcreate "size_t nel" +.Ft void +.Fn hdestroy "void" +.Ft ENTRY * +.Fn hsearch "ENTRY item" "ACTION action" +.Sh DESCRIPTION +The +.Fn hcreate , +.Fn hdestroy +and +.Fn hsearch +functions manage hash search tables. +.Pp +The +.Fn hcreate +function allocates and initializes the table. +The +.Fa nel +argument specifies an estimate of the maximum number of entries to be held +by the table. +Unless further memory allocation fails, supplying an insufficient +.Fa nel +value will not result in functional harm, although a performance degradation +may occur. +Initialization using the +.Fn hcreate +function is mandatory prior to any access operations using +.Fn hsearch . +.Pp +The +.Fn hdestroy +function destroys a table previously created using +.Fn hcreate . +After a call to +.Fn hdestroy , +the data can no longer be accessed. +.Pp +The +.Fn hsearch +function is used to search to the hash table. +It returns a pointer into the +hash table indicating the address of an item. +The +.Fa item +argument is of type +.Dv ENTRY , +a structural type which contains the following members: +.Bl -tag -compact -offset indent -width voidX*dataXX +.It Fa char *key +comparison key. +.It Fa void *data +pointer to data associated with +.Fa key . +.El +.Pp +The key comparison function used by +.Fn hsearch +is +.Xr strcmp 3 . +.Pp +The +.Fa action +argument is of type +.Dv ACTION , +an enumeration type which defines the following values: +.Bl -tag -compact -offset indent -width ENTERXX +.It Dv ENTER +Insert +.Fa item +into the hash table. +If an existing item with the same key is found, it is not replaced. +Note that the +.Fa key +and +.Fa data +elements of +.Fa item +are used directly by the new table entry. +The storage for the +key must not be modified during the lifetime of the hash table. +.It Dv FIND +Search the hash table without inserting +.Fa item . +.El +.Sh RETURN VALUES +If successful, the +.Fn hcreate +function returns a non-zero value. +Otherwise, a value of 0 is returned and +.Va errno +is set to indicate the error. +.Pp +The +.Fn hdestroy +functions +returns no value. +.Pp +If successful, the +.Fn hsearch +function returns a pointer to hash table entry matching +the provided key. +If the action is +.Dv FIND +and the item was not found, or if the action is +.Dv ENTER +and the insertion failed, +.Dv NULL +is returned and +.Va errno +is set to indicate the error. +If the action is +.Dv ENTER +and an entry already existed in the table matching the given +key, the existing entry is returned and is not replaced. +.Sh ERRORS +The +.Fn hcreate +and +.Fn hsearch +functions will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory is available. +.El +.Sh SEE ALSO +.Xr bsearch 3 , +.Xr lsearch 3 , +.Xr malloc 3 , +.Xr strcmp 3 +.Sh STANDARDS +The +.Fn hcreate , +.Fn hdestroy +and +.Fn hsearch +functions conform to +.St -xpg4.2 . +.Sh HISTORY +The +.Fn hcreate , +.Fn hdestroy +and +.Fn hsearch +functions first appeared in +.At V . +.Sh BUGS +The interface permits the use of only one hash table at a time. -- cgit v1.2.3-55-g6feb