Module Name: src
Committed By: jruoho
Date: Sat May 1 06:18:03 UTC 2010
Modified Files:
src/lib/libc/stdlib: hcreate.3
Log Message:
Improvements to wording and markup.
In addition, list more bugs and caveats. Namely, the NetBSD implementation
(like the FreeBSD one where this was ported to) requires that the comparison
keys are allocated dynamically, and that hdestroy() will try to free(3) each
key. This obviously severely limits the portability, given that other
implementations (for example, the Linux one) make no such assumptions. Both
approaches are legitimate, and thus the real bug is in the ambiguity of the
standard.
To generate a diff of this commit:
cvs rdiff -u -r1.7 -r1.8 src/lib/libc/stdlib/hcreate.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/stdlib/hcreate.3
diff -u src/lib/libc/stdlib/hcreate.3:1.7 src/lib/libc/stdlib/hcreate.3:1.8
--- src/lib/libc/stdlib/hcreate.3:1.7 Wed Apr 30 13:10:51 2008
+++ src/lib/libc/stdlib/hcreate.3 Sat May 1 06:18:03 2010
@@ -1,4 +1,4 @@
-.\" $NetBSD: hcreate.3,v 1.7 2008/04/30 13:10:51 martin Exp $
+.\" $NetBSD: hcreate.3,v 1.8 2010/05/01 06:18:03 jruoho Exp $
.\"
.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,7 +27,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd February 13, 2001
+.Dd May 1, 2010
.Dt HCREATE 3
.Os
.Sh NAME
@@ -85,14 +85,18 @@
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
+.Vt ENTRY ,
+defined in the
+.In search.h
+header.
+This is a structure type that contains two pointers:
+.Pp
+.Bl -tag -compact -offset indent -width "void *data "
.It Fa char *key
-comparison key.
+comparison key
.It Fa void *data
pointer to data associated with
-.Fa key .
+.Fa key
.El
.Pp
The key comparison function used by
@@ -103,9 +107,9 @@
The
.Fa action
argument is of type
-.Dv ACTION ,
+.Vt ACTION ,
an enumeration type which defines the following values:
-.Bl -tag -compact -offset indent -width ENTERXX
+.Bl -tag -offset indent -width ENTERXX
.It Dv ENTER
Insert
.Fa item
@@ -124,6 +128,30 @@
Search the hash table without inserting
.Fa item .
.El
+.Pp
+Note that the comparison
+.Fa key
+must be allocated using
+.Xr malloc 3
+or
+.Xr calloc 3
+if action is
+.Dv ENTER
+and
+.Fn hdestroy
+will be called.
+This is because
+.Fn hdestroy
+will call
+.Xr free 3
+for each comparison
+.Fa key
+(but not
+.Fa data ) .
+Typically the comparison
+.Fa key
+is allocated by using
+.Xr strdup 3 .
.Sh RETURN VALUES
If successful, the
.Fn hcreate
@@ -185,5 +213,28 @@
.Fn hsearch
functions first appeared in
.At V .
-.Sh BUGS
+.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.
+.It
+Individual hash table entries can be added, but not deleted.
+.It
+The standard is indecipherable about the
+internal memory usage of the functions,
+mentioning only that
+.Do
+.Fn hcreate
+and
+.Fn hsearch
+functions may use
+.Fn malloc
+to allocate space
+.Dc .
+This limits the portability of the functions,
+given that other implementations may not
+.Xr free 3
+the buffer pointed by
+.Fa key .
+.El
