[src/trunk]: src/lib/libc/stdlib Improvements to wording and markup.

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

details:   https://anonhg.NetBSD.org/src/rev/1c8ad4875e1f
branches:  trunk
changeset: 754460:1c8ad4875e1f
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Sat May 01 06:18:03 2010 +0000

description:
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.

diffstat:

 lib/libc/stdlib/hcreate.3 |  71 ++++++++++++++++++++++++++++++++++++++++------
 1 files changed, 61 insertions(+), 10 deletions(-)

diffs (115 lines):

diff -r 1140cf1e4db0 -r 1c8ad4875e1f lib/libc/stdlib/hcreate.3
--- a/lib/libc/stdlib/hcreate.3 Sat May 01 01:36:25 2010 +0000
+++ b/lib/libc/stdlib/hcreate.3 Sat May 01 06:18:03 2010 +0000
@@ -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