summaryrefslogtreecommitdiff
path: root/lib/libc/stdlib/hcreate.3
diff options
context:
space:
mode:
Diffstat (limited to 'lib/libc/stdlib/hcreate.3')
-rw-r--r--lib/libc/stdlib/hcreate.3103
1 files changed, 91 insertions, 12 deletions
diff --git a/lib/libc/stdlib/hcreate.3 b/lib/libc/stdlib/hcreate.3
index 0bc844fee2e..752379edbbe 100644
--- a/lib/libc/stdlib/hcreate.3
+++ b/lib/libc/stdlib/hcreate.3
@@ -1,4 +1,4 @@
-.\" $NetBSD: hcreate.3,v 1.8 2010/05/01 06:18:03 jruoho Exp $
+.\" $NetBSD: hcreate.3,v 1.9 2011/09/14 23:33:51 christos Exp $
.\"
.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,13 +27,16 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd May 1, 2010
+.Dd September 14, 2011
.Dt HCREATE 3
.Os
.Sh NAME
.Nm hcreate ,
+.Nm hcreate_r ,
.Nm hdestroy ,
-.Nm hsearch
+.Nm hdestroy_r ,
+.Nm hsearch ,
+.Nm hsearch_r
.Nd manage hash search table
.Sh LIBRARY
.Lb libc
@@ -41,16 +44,25 @@
.In search.h
.Ft int
.Fn hcreate "size_t nel"
+.Ft int
+.Fn hcreate_r "size_t nel" "struct hsearch_data *table"
.Ft void
.Fn hdestroy "void"
+.Ft void
+.Fn hdestroy_r "struct hsearch_data *table"
.Ft ENTRY *
.Fn hsearch "ENTRY item" "ACTION action"
+.Ft int
+.Fn hsearch_r "ENTRY item" "ACTION action" "ENTRY ** itemp" "struct hsearch_data *table"
.Sh DESCRIPTION
The
.Fn hcreate ,
-.Fn hdestroy
+.Fn hcreate_r ,
+.Fn hdestroy ,
+.Fn hdestroy_r
and
-.Fn hsearch
+.Fn hsearch ,
+.Fn hsearch_r
functions manage hash search tables.
.Pp
The
@@ -152,18 +164,46 @@ Typically the comparison
.Fa key
is allocated by using
.Xr strdup 3 .
+.Pp
+The
+.Fn hcreate_r ,
+.Fn hdestroy_r ,
+and
+.Fn hsearch_r
+are re-entrant versions of the above functions that can operate on a table
+supplied by the user.
+The
+.Fn hsearch_r
+function returns
+.Dv 0
+if the action is
+.Dv ENTER
+and the element cannot be created,
+.Dv 1
+otherwise.
+If the element exists or can be created, it will be placed in
+.Fa itemp ,
+otherwise
+.Fa itemp
+will be set to
+.Dv NULL .
.Sh RETURN VALUES
If successful, the
.Fn hcreate
-function returns a non-zero value.
-Otherwise, a value of 0 is returned and
+and
+.Fn hcreate_r
+function return a non-zero value.
+Otherwise, a value of
+.Dv 0
+is returned and
.Va errno
is set to indicate the error.
.Pp
The
.Fn hdestroy
-functions
-returns no value.
+and
+.Fn hdestroy_r
+functions return no value.
.Pp
If successful, the
.Fn hsearch
@@ -182,16 +222,45 @@ 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.
+.Pp
+The
+.Fn hsearch_r
+function returns
+.Dv 1
+unless the table is full, when it returns
+.Dv 0 .
+If the
+.Fn hsearch
+returns
+.Dv 0
+or the element is not found,
+.Va errno
+is set to indicate the error.
.Sh ERRORS
The
-.Fn hcreate
-and
+.Fn hcreate ,
+.Fn hcreate_r ,
.Fn hsearch
+and
+.Fn hsearch_r
functions will fail if:
.Bl -tag -width Er
.It Bq Er ENOMEM
Insufficient memory is available.
.El
+.Pp
+The
+.Fn hsearch
+and
+.Fn hsearch_r
+functions will also fail if the action is
+.Dv SEARCH and the element is not found:
+.Bl -tag -width Er
+.It Bq Er ESRCH
+The
+.Fa item
+given is not found.
+.El
.Sh SEE ALSO
.Xr bsearch 3 ,
.Xr lsearch 3 ,
@@ -213,11 +282,21 @@ and
.Fn hsearch
functions first appeared in
.At V .
+The
+.Fn hcreate_r ,
+.Fn hdestroy_r
+and
+.Fn hsearch_r
+are
+.Tn GNU
+extensions.
.Sh CAVEATS
At least the following limitations can be mentioned:
.Bl -bullet
.It
-The interface permits the use of only one hash table at a time.
+The original, non-
+.Tn GNU
+interface permits the use of only one hash table at a time.
.It
Individual hash table entries can be added, but not deleted.
.It