[src/trunk]: src/lib/libc move db/man/hcreate.3 to stdlib/hcreate.3

[cgd <cgd%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a847821d15f8
branches:  trunk
changeset: 503806:a847821d15f8
user:      cgd <cgd%NetBSD.org@localhost>
date:      Wed Feb 14 05:41:01 2001 +0000

description:
move db/man/hcreate.3 to stdlib/hcreate.3

diffstat:

 lib/libc/db/man/hcreate.3 |  189 ----------------------------------------------
 lib/libc/stdlib/hcreate.3 |  189 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 189 insertions(+), 189 deletions(-)

diffs (truncated from 386 to 300 lines):

diff -r e29381870677 -r a847821d15f8 lib/libc/db/man/hcreate.3
--- a/lib/libc/db/man/hcreate.3 Wed Feb 14 05:32:19 2001 +0000
+++ /dev/null   Thu Jan 01 00:00:00 1970 +0000
@@ -1,189 +0,0 @@
-.\"    $NetBSD: hcreate.3,v 1.3 1999/03/22 19:44:38 garbled 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 16, 1999
-.Dt HCREATE 3
-.Os
-.Sh NAME
-.Nm hcreate ,
-.Nm hdestroy ,
-.Nm hsearch
-.Nd manage hash search table
-.Sh LIBRARY
-.Lb libc
-.Sh SYNOPSIS
-.Fd #include <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, possibly replacing an existing item.
-.It Dv FIND
-search the hash table without inserting
-.Fa item .
-Unsuccessful resolution is indicated by the return of a
-.Dv NULL
-pointer.
-.El
-.Pp
-.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 the item.
-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.
-.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 BUGS
-The
-.Fn hsearch
-function currently returns a pointer into a static buffer area; subsequent
-calls to
-.Fn hsearch
-may overwrite this buffer.
-.Pp
-The interface permits the use of only one hash table at a time.
-.Sh HISTORY
-The
-.Fn hcreate ,
-.Fn hdestroy
-and
-.Fn hsearch
-functions first appeared in
-.At V .
diff -r e29381870677 -r a847821d15f8 lib/libc/stdlib/hcreate.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/stdlib/hcreate.3 Wed Feb 14 05:41:01 2001 +0000
@@ -0,0 +1,189 @@
+.\"    $NetBSD: hcreate.3,v 1.1 2001/02/14 05:41:01 cgd 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 16, 1999
+.Dt HCREATE 3
+.Os
+.Sh NAME
+.Nm hcreate ,
+.Nm hdestroy ,
+.Nm hsearch
+.Nd manage hash search table
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.Fd #include <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