Updated information obtained from:
a) Reading the source of search.h on my Fedora system (uses __USE_GNU
instead of _GNU_SOURCE) -- this works in my test program
b) Reading the documentation:
http://www.gnu.org/software/libc/manual/html_node/Hash-Search-Function.html#Hash-Search-Function
Having said that, though, it's mostly a reorganisation, and putting in
little snippets of information that would've helped me. I don't mind if the
patch gets changed around or whatever, but I think the patch is an improvement
on the current situation. In particular, things I wondered about are:
- I have no idea about groff; if anyone can think of improvements, go
for it (I did check it out with nroff -man though)
- If it needs to be split into multiple pages (ie. hcreate*/hdestroy* on
a separate page from hsearch*), that's fine by me too
HTH,
---------------------------------------------------------------------
| Name: Tim Nelson | Because the Creator is, |
| E-mail: wayland@xxxxxxxxxxxxx | I am |
---------------------------------------------------------------------
----BEGIN GEEK CODE BLOCK----
Version 3.12
GCS d+++ s+: a- C++$ U+++$ P+++$ L+++ E- W+ N+ w--- V-
PE(+) Y+>++ PGP->+++ R(+) !tv b++ DI++++ D G+ e++>++++ h! y-
-----END GEEK CODE BLOCK-----
diff -urN man-pages-3.08/man3/hsearch.3 man-pages-3.08-tsn1/man3/hsearch.3
--- man-pages-3.08/man3/hsearch.3 2008-08-27 16:09:02.000000000 +1000
+++ man-pages-3.08-tsn1/man3/hsearch.3 2008-09-02 14:11:07.000000000 +1000
@@ -41,7 +41,7 @@
.sp
.B "void hdestroy(void);"
.sp
-.B #define _GNU_SOURCE
+.B #define __USE_GNU
.br
.B #include <search.h>
.sp
@@ -58,23 +58,62 @@
.BR hsearch (),
and
.BR hdestroy ()
-allow the user to create a hash table (only one at a time)
+allow the user to create and manipulate a hash table (only one at a time)
which associates a key with any data.
.PP
+The three functions
+.BR hcreate_r (),
+.BR hsearch_r (),
+.BR hdestroy_r ()
+are reentrant versions that allow the use of more than one table.
+The last argument used identifies the table.
+.PP
+.SS "hcreate()/hcreate_r()"
+.PP
First the table must be created with the function
-.BR hcreate ().
+.BR hcreate ()
+/
+.BR hcreate_r ().
+.TP
+.B Argument "nel"
The argument \fInel\fP is an estimate of the maximum number of entries
in the table.
-The function
-.BR hcreate ()
+The creation function
may adjust this value upward to improve the
performance of the resulting hash table.
-.PP
+.TP
+.B Argument "tab"
+As specified above, in the case of hcreate_r, this points to the
+table to be created. The struct it points to must be malloc'd and
+zeroed before the first call to
+.BR hcreate_r ().
+.TP
+.B Return Value
+.BR hcreate ()
+and
+.BR hcreate_r ()
+return 0 when allocation of the memory
+for the hash table fails (or, in the case of
+.BR hcreate(),
+when a hash table is already in use), non-zero otherwise.
+.LP
+.SS "hdestroy()/hdestroy_r()"
The corresponding function
.BR hdestroy ()
+/
+.BR hdestroy_r()
frees the memory occupied by
the hash table so that a new table can be constructed.
.PP
+.SS "hsearch()/hsearch_r()"
+The function
+.BR hsearch ()
+searches the hash table for an
+item with the same key as \fIitem\fP (where "the same" is determined using
+.BR strcmp (3)),
+and if successful returns a pointer to it.
+.TP
+.B Argument "item"
The argument \fIitem\fP is of type \fBENTRY\fP, which is a typedef defined in
\fI<search.h>\fP and includes these elements:
.in +4n
@@ -90,12 +129,8 @@
The field \fIkey\fP points to the null-terminated string which is the
search key.
The field \fIdata\fP points to the data associated with that key.
-The function
-.BR hsearch ()
-searches the hash table for an
-item with the same key as \fIitem\fP (where "the same" is determined using
-.BR strcmp (3)),
-and if successful returns a pointer to it.
+.TP
+.B Argument "action"
The argument \fIaction\fP determines what
.BR hsearch ()
does
@@ -103,33 +138,21 @@
A value of \fBENTER\fP instructs it to
insert a copy of \fIitem\fP, while a value of \fBFIND\fP means to return
NULL.
-.PP
-The three functions
-.BR hcreate_r (),
-.BR hsearch_r (),
-.BR hdestroy_r ()
-are reentrant versions that allow the use of more than one table.
-The last argument used identifies the table.
-The struct it points to
-must be zeroed before the first call to
-.BR hcreate_r ().
-.SH "RETURN VALUE"
-.BR hcreate ()
-and
-.BR hcreate_r ()
-return 0 when allocation of the memory
-for the hash table fails, non-zero otherwise.
-.LP
+.TP
+.B Argument "ret"
+The argument \fIret\fP points at the found item, if action was \fBFIND\fP
+and there were no errors.
+.TP
+.B Return Value
.BR hsearch ()
returns NULL if \fIaction\fP is \fBENTER\fP and
the hash table is full, or \fIaction\fP is \fBFIND\fP and \fIitem\fP
cannot be found in the hash table.
-.LP
.BR hsearch_r ()
-returns 0 if \fIaction\fP is \fBENTER\fP and
-the hash table is full, and non-zero otherwise.
+returns zero on failure, and non-zero on success. If there's a failure,
+the error (see ERRORS section below) is stored in errno.
.SH ERRORS
-POSIX documents
+POSIX documents the following errno values (#include <errno.h>):
.TP
.B ENOMEM
Out of memory.
