Patch to hsearch.3 from man-pages-3.08

Patch to hsearch.3 from man-pages-3.08

[Timothy S. Nelson]

[-- Attachment #1: Type: text/plain, Size: 1358 bytes --]

 	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-r28gBBs99rhWo+R/V/U2/g@public.gmane.org    | 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-----

[-- Attachment #2: Type: text/plain, Size: 4072 bytes --]

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.

Re: Patch to hsearch.3 from man-pages-3.08

[Michael Kerrisk]

Hello Timothy,

Timothy S. Nelson wrote:
>     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

This is wrong.  See <feature.h> and feature_test_macros(7).

> b)    Reading the documentation:
>     http://www.gnu.org/software/libc/manual/html_node/Hash-Search-Function.html#Hash-Search-Function 

Your mail contains no description of what changes your patch makes,
or why they should be useful.  (I am not a mind reader ;-).)

Also, you combine several logical changes in a single patch.
Please review http://www.kernel.org/doc/man-pages/patches.html
and also take a look at man-pages(7).

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

But you don't explain what you changed, or why you think it
improves things.

 > 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

It's easier for me if you send patches inline.

 > --- 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

No.

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

Why do you think this is better?  I think it is better to describe the
non-reentrant functions first, and then describe the differences for
the reentrant functions.

 >  First the table must be created with the function
 > -.BR hcreate ().
 > +.BR hcreate ()
 > +/
 > +.BR hcreate_r ().
 > +.TP
 > +.B Argument "nel"

I don't really think such subdivisions of the text really help,
and they are not the norm in man-pages.  Also, you've removed the
.SH RETURN VALUE
section, which really should be present in every .2 and .3 page
(though it is currently missing from several).

 >  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

Why must it be *malloc'd*?  Surely allocation anywhere (stack, heap) will do?

Cheers,

Michael

 > +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.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Patch to hsearch.3 from man-pages-3.08

[Michael Kerrisk]

Timothy,

Your patch did prompt me to look at the info docs for hsearch() and friends
and I've revised the page as shown below.  If you feel further changes are
required, send a patch against this new version.

Cheers,

Michael

.\" Hey Emacs! This file is -*- nroff -*- source.
.\" Copyright 1993 Ulrich Drepper (drepper-R/BzpT9BeSbQ/dyy7Hk5pA@public.gmane.org)
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\" References consulted:
.\"     SunOS 4.1.1 man pages
.\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt <jrv-krxCGfS0CTlN0jTZmbxGZA@public.gmane.org>
.\" Remarks from dhw-iOD1Ui1JDHCMQhOLUu48bZQCsf4PZ8us@public.gmane.org Fri Jun 19 06:46:31 1998
.\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb
.\" 2008-09-02, mtk: various additions and rewrites
.\"
.TH HSEARCH 3 2008-09-02 "GNU" "Linux Programmer's Manual"
.SH NAME
hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r,
hsearch_r \- hash table management
.SH SYNOPSIS
.nf
.B #include <search.h>
.sp
.BI "int hcreate(size_t " nel );
.sp
.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action );
.sp
.B "void hdestroy(void);"
.sp
.B #define _GNU_SOURCE
.br
.B #include <search.h>
.sp
.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" tab );
.sp
.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" ret ,
.BI "              struct hsearch_data *" tab );
.sp
.BI "void hdestroy_r(struct hsearch_data *" tab );
.fi
.SH DESCRIPTION
The three functions
.BR hcreate (),
.BR hsearch (),
and
.BR hdestroy ()
allow the caller to create and manage a hash table
containing entries, each of which consists of a key (a string)
and associated data.
Using these functions, only one hash table can be used at a time.
.PP
First the table must be created with the function
.BR hcreate ().
The argument \fInel\fP specifies the maximum number of entries
in the table.
(This maximum cannot be changed later, so choose it wisely.)
The function
.BR hcreate ()
may adjust this value upward to improve the
performance of the resulting hash table.
.\" e.g., in glibc it is raised to the next higher prime number
.PP
The corresponding function
.BR hdestroy ()
frees the memory occupied by the hash table.
After calling
.BR hdestroy ()
a new hash table can be created using
.BR hcreate ().

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.

The argument \fIitem\fP is of type \fIENTRY\fP, which is defined in
\fI<search.h>\fP as follows:
.in +4n
.sp
.nf
typedef struct entry {
     char *key;
     void *data;
} ENTRY;
.in
.fi
.sp
The field \fIkey\fP points to a null-terminated string which is the
search key.
The field \fIdata\fP points to data that is associated with that key.

The argument \fIaction\fP determines what
.BR hsearch ()
does after an unsuccessful search.
This argument must either have the value
.BR ENTER ,
meaning insert a copy of
.IR item ,
or the value
.BR FIND ,
meaning that NULL should be returned.
(If
.I action
is
.BR FIND ,
then
.I data
is ignored.)
.PP
The three functions
.BR hcreate_r (),
.BR hsearch_r (),
.BR hdestroy_r ()
are reentrant versions that allow a program to use
more than one table at the same time.
The last argument,
.IR tab ,
identifies the table.
The structure that it points to
must be zeroed before the first call to
.BR hcreate_r ().
The
.BR hsearch_r ()
function differs from
.BR hsearch ()
in that a pointer to the found item is returned in
.IR retval ,
rather than as the function result.
.SH "RETURN VALUE"
.BR hcreate ()
and
.BR hcreate_r ()
return non-zero on success.
They return 0 on error.

On success,
.BR hsearch ()
returns a pointer to an entry in the hash table.
.BR hsearch ()
returns NULL on error, that is,
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.
.BR hsearch_r ()
returns non-zero on success, and 0 on error.
.SH ERRORS
.LP
.BR hcreate ()
and
.BR hcreate_r ()
can fail for the following reasons:
.TP
.B EINVAL
.RB ( hcreate_r ())
.I tab
is NULL.
.TP
.B ENOMEM
Table full with \fIaction\fP set to \fBENTER\fP.
.TP
.B ESRCH
The \fIaction\fP argument is \fBFIND\fP and no corresponding element
is found in the table.
.\" hdestroy_r() can set errno to EINVAL if 'tab' is NULL.
.PP
.BR hsearch ()
and
.BR hsearch_r ()
can fail for the following reasons:
.TP
.B ENOMEM
.I action
was
.BR ENTER ,
.I key
was not found in the table,
and there was no room in the table to add a new entry.
.TP
.B ESRCH
.I action
was
.BR find ,
and
.I key
was not found in the table.
.PP
POSIX.1-2001 only specifies the
.B ENOMEM
error.
.SH "CONFORMING TO"
The functions
.BR hcreate (),
.BR hsearch (),
and
.BR hdestroy ()
are from SVr4, and are described in POSIX.1-2001.
The functions
.BR hcreate_r (),
.BR hsearch_r (),
.BR hdestroy_r ()
are GNU extensions.
.SH NOTES
Hash table implementations are usually more efficient when the
table contains enough free space to minimize collisions.
Typically, this means that
.I nel
should be at least 25% larger than the maximum number of elements
that the caller expects to store in the table.

The
.BR hdestroy ()
function does not free the buffers pointed to by the
.I key
and
.I data
elements of the hash table entries.
If these buffers need to be freed (perhaps because the program
is repeatedly creating and destroying hash tables,
rather than creating a single table whose lifetime
matches that of the program),
then the program must maintain bookkeeping data structures that
allow it to free them.
.SH BUGS
SVr4 and POSIX.1-2001 specify that \fIaction\fP
is significant only for unsuccessful searches, so that an \fBENTER\fP
should not do anything for a successful search.
The libc and glibc (before version 2.3)
implementations update the \fIdata\fP for the given \fIkey\fP
in this case.

Individual hash table entries can be added, but not deleted.
.SH EXAMPLE
.PP
The following program inserts 24 items into a hash table, then prints
some of them.
.nf

#include <stdio.h>
#include <stdlib.h>
#include <search.h>

char *data[] = { "alpha", "bravo", "charlie", "delta",
      "echo", "foxtrot", "golf", "hotel", "india", "juliet",
      "kilo", "lima", "mike", "november", "oscar", "papa",
      "quebec", "romeo", "sierra", "tango", "uniform",
      "victor", "whisky", "x\-ray", "yankee", "zulu"
};

int
main(void)
{
     ENTRY e, *ep;
     int i;

     hcreate(30);

     for (i = 0; i < 24; i++) {
         e.key = data[i];
         /* data is just an integer, instead of a
            pointer to something */
         e.data = (void *) i;
         ep = hsearch(e, ENTER);
         /* there should be no failures */
         if (ep == NULL) {
             fprintf(stderr, "entry failed\\n");
             exit(EXIT_FAILURE);
         }
     }

     for (i = 22; i < 26; i++) {
         /* print two entries from the table, and
            show that two are not in the table */
         e.key = data[i];
         ep = hsearch(e, FIND);
         printf("%9.9s \-> %9.9s:%d\\n", e.key,
                ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0);
     }
     exit(EXIT_SUCCESS);
}
.fi
.SH "SEE ALSO"
.BR bsearch (3),
.BR lsearch (3),
.BR malloc (3),
.BR tsearch (3),
.BR feature_test_macros (7)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[patch] hsearch.3: Reorder entire page for readability, add information for completeness (was: Re: Patch to hsearch.3 from man-pages-3.08)

[Timothy S. Nelson]

On Tue, 2 Sep 2008, Michael Kerrisk wrote:

> Hello Timothy,
>
> Timothy S. Nelson wrote:
>>     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
>
> This is wrong.  See <feature.h> and feature_test_macros(7).

 	Great!  Thanks.  I'll update the patch so that it tells people to 
#include <feature.h>.

>> b)    Reading the documentation:
>>     http://www.gnu.org/software/libc/manual/html_node/Hash-Search-Function.html#Hash-Search-Function 
>
> Your mail contains no description of what changes your patch makes,
> or why they should be useful.  (I am not a mind reader ;-).)

 	I guess I assumed you'd take a skim over the patch to find that out, 
but I can see why you wouldn't :).

 	Here's a summary of the changes:
-	_GNU_SOURCE didn't work for me, so I'm updating the documentation so
 	that it will work for others (now #include <feature.h>)
-	It was constantly difficult to find the piece of information I wanted
 	on this page, so I reordered a lot of the paragraphs; it's now both
 	more readable, and easier to find the information I want.  In
 	particular, this includes grouping information about particular
 	functions together under a heading with the function name
-	Various small readability enhancements and snippets of information
 	(ie. mentioning errno.h)

> Also, you combine several logical changes in a single patch.
> Please review http://www.kernel.org/doc/man-pages/patches.html
> and also take a look at man-pages(7).

 	Ok.  I guess I assumed that, since I was moving a lot of stuff anyway 
as part of the reorg, a few extra changes wouldn't show that much.  But I can 
see your point.  I'm reworking the patch, but until we agree (see below), 
there's no point me issuing another patch we disagree on.

>>     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.
>
> But you don't explain what you changed, or why you think it
> improves things.
>
>> 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
>
> It's easier for me if you send patches inline.

 	Ok, I'll try to remember that.  Btw, sorry about the subject line too 
(hopefully better now).

>
>> --- 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
>
> No.

 	Fixed in the next version.

>
>>  .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
>
> Why do you think this is better?  I think it is better to describe the
> non-reentrant functions first, and then describe the differences for
> the reentrant functions.

 	Well, as someone who only wants to use the re-entrant versions, I must 
say, this made things much more difficult for me to get a grip on.  As soon as 
I knew what the re-entrant versions were, I knew I didn't care about the other 
ones, so I didn't want to know about them.  Also, one of the first things I'm 
wondering when I come to this man page is "There's two sets of functions here; 
I need to choose the right one to start with; which is it?".  This answers 
that.

>>  First the table must be created with the function
>> -.BR hcreate ().
>> +.BR hcreate ()
>> +/
>> +.BR hcreate_r ().
>> +.TP
>> +.B Argument "nel"
>
> I don't really think such subdivisions of the text really help,
> and they are not the norm in man-pages.

 	If you're talking about the headings for the individual functions, 
then "man perlfunc" :).  But that's also why I was wondering whether there 
should be separate man pages.

 	If you're talking about the headings for the different arguments, then 
I guess I realise it's not quite like the others (although gethostbyname does 
something similar for the members of the hostent struct; would you like it if 
I reformatted it like that?).  I can name two advantages:
-	It makes it easier to quickly locate information
-	It immediately highlighted the fact that the "ret" argument was not
 	documented at all (which is something I've corrected in this patch)

> Also, you've removed the
> ..SH RETURN VALUE
> section, which really should be present in every .2 and .3 page
> (though it is currently missing from several).

 	I've divided the Return Value into two separate sections, as you've 
seen.  This is one of the reasons why I was wondering if there shouldn't be at 
least two separate man pages here; one for hsearch/hsearch_r, and one for 
everything else.

 	If your objection is that it's not marked ".SS", that's probably 
because I know nothing about groff.  Visually (with nroff -man), it somewhat 
resembles the information on the printf page.

>>  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
>
> Why must it be *malloc'd*?  Surely allocation anywhere (stack, heap) will do?

 	Sorry.  If you ever find out what I was thinking when I wrote this, 
let me know, 'cause I don't know what I was thinking :).

 	To me, the ideal situation for the man pages around the hash table 
management would be at least 3 separate man pages:
-	hsearch/hsearch_r
-	hcreate/hcreate_r
-	An overview of the hashing functions (referring to the other two man
 	pages)

 	I'm not sure where hdestroy/hdestroy_r should go; probably in its own 
page, possibly with the overview, and possibly with hcreate & friends.  I'm 
also not pushing for this change, but if you like the idea better than the way 
I've done things at the moment, then I'm happy to format things that way too 
(although then I'd probably need a suggestion on what man section the 
overview page would go best in).

 	In review, it seems to me like I agree with you, except for:
-	I think re-entrant functions should be discussed with their brethren,
 	rather than being discussed afterwards
-	I think there's some sort of sectioning needed, which you're not sure
 	of

 	Thanks for your careful review of the patch.

 	:)


---------------------------------------------------------------------
| Name: Tim Nelson                 | Because the Creator is,        |
| E-mail: wayland-r28gBBs99rhWo+R/V/U2/g@public.gmane.org    | 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-----

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Patch to hsearch.3 from man-pages-3.08

[Timothy S. Nelson]

On Tue, 2 Sep 2008, Michael Kerrisk wrote:

> Timothy,
>
> Your patch did prompt me to look at the info docs for hsearch() and friends
> and I've revised the page as shown below.  If you feel further changes are
> required, send a patch against this new version.

 	Great!  I'll try to remember that too.  Unfortunately, something along 
the way seems to have mangled it a little; the main symptom of this is the 
extra dots starting some of the lines (which I can strip off easily); another 
difficulty is some extra spaces that appeared from somewhere.  I'll do the 
best I can :).

 	Oh, btw, I've just realised that, if we were to do the separation of 
man pages that I suggested as a possibility in the other e-mail, the new 
overview page would probably be hash_table.7 or something.

 	Thanks,


---------------------------------------------------------------------
| Name: Tim Nelson                 | Because the Creator is,        |
| E-mail: wayland-r28gBBs99rhWo+R/V/U2/g@public.gmane.org    | 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-----

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] hsearch.3: Reorder entire page for readability, add information for completeness

[Michael Kerrisk]

Timothy S. Nelson wrote:
> On Tue, 2 Sep 2008, Michael Kerrisk wrote:
> 
>> Hello Timothy,
>>
>> Timothy S. Nelson wrote:
>>>     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
>>
>> This is wrong.  See <feature.h> and feature_test_macros(7).
> 
>     Great!  Thanks.  I'll update the patch so that it tells people to 
> #include <feature.h>.

 From feature_test_macros(7):

    NOTES
        <features.h>  is  a  Linux/glibc-specific  header   file.
        Other  systems have an analogous file, but typically with
        a different name.   This  header  file  is  automatically
        included  by  other  header  files as required: it is not
        necessary to explicitly include it  in  order  to  employ
        feature test macros.

>>> b)    Reading the documentation:
>>>     
>>> http://www.gnu.org/software/libc/manual/html_node/Hash-Search-Function.html#Hash-Search-Function 
>>
>>
>> Your mail contains no description of what changes your patch makes,
>> or why they should be useful.  (I am not a mind reader ;-).)
> 
>     I guess I assumed you'd take a skim over the patch to find that out, 
> but I can see why you wouldn't :).
> 
>     Here's a summary of the changes:
> -    _GNU_SOURCE didn't work for me, so I'm updating the documentation so
>     that it will work for others (now #include <feature.h>)

If it didn't work for you then you probably didn't define the FTM before
including *any* header file.  Including <features.h> should never be
necessary.

> -    It was constantly difficult to find the piece of information I wanted
>     on this page, so I reordered a lot of the paragraphs; it's now both
>     more readable, and easier to find the information I want.  In
>     particular, this includes grouping information about particular
>     functions together under a heading with the function name
> -    Various small readability enhancements and snippets of information
>     (ie. mentioning errno.h)
> 
>> Also, you combine several logical changes in a single patch.
>> Please review http://www.kernel.org/doc/man-pages/patches.html
>> and also take a look at man-pages(7).
> 
>     Ok.  I guess I assumed that, since I was moving a lot of stuff 
> anyway as part of the reorg, a few extra changes wouldn't show that 
> much.  But I can see your point.  I'm reworking the patch, but until we 
> agree (see below), there's no point me issuing another patch we disagree 
> on.
> 
>>>     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.
>>
>> But you don't explain what you changed, or why you think it
>> improves things.
>>
>>> 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
>>
>> It's easier for me if you send patches inline.
> 
>     Ok, I'll try to remember that.  Btw, sorry about the subject line 
> too (hopefully better now).
> 
>>
>>> --- 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
>>
>> No.
> 
>     Fixed in the next version.
> 
>>
>>>  .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
>>
>> Why do you think this is better?  I think it is better to describe the
>> non-reentrant functions first, and then describe the differences for
>> the reentrant functions.
> 
>     Well, as someone who only wants to use the re-entrant versions, I 
> must say, this made things much more difficult for me to get a grip on.  
> As soon as I knew what the re-entrant versions were, I knew I didn't 
> care about the other ones, so I didn't want to know about them.  Also, 
> one of the first things I'm wondering when I come to this man page is 
> "There's two sets of functions here; I need to choose the right one to 
> start with; which is it?".  This answers that.

Okay.

>>>  First the table must be created with the function
>>> -.BR hcreate ().
>>> +.BR hcreate ()
>>> +/
>>> +.BR hcreate_r ().
>>> +.TP
>>> +.B Argument "nel"
>>
>> I don't really think such subdivisions of the text really help,
>> and they are not the norm in man-pages.
> 
>     If you're talking about the headings for the individual functions, 
> then "man perlfunc" :).  But that's also why I was wondering whether 
> there should be separate man pages.

Formatted, perlfunc(1) is 7000 lines long.  It is a different kind of beast.

>     If you're talking about the headings for the different arguments, 
> then I guess I realise it's not quite like the others (although 
> gethostbyname does something similar for the members of the hostent 
> struct; would you like it if I reformatted it like that?).

No.

> I can name
> two advantages:
> -    It makes it easier to quickly locate information
> -    It immediately highlighted the fact that the "ret" argument was not
>     documented at all (which is something I've corrected in this patch)

Okay -- I already fixed that in my revision of the page.
(But I got the name wrong: s/retval/ret/)

>> Also, you've removed the
>> ..SH RETURN VALUE
>> section, which really should be present in every .2 and .3 page
>> (though it is currently missing from several).
> 
>     I've divided the Return Value into two separate sections, as you've 
> seen.  This is one of the reasons why I was wondering if there shouldn't 
> be at least two separate man pages here; one for hsearch/hsearch_r, and 
> one for everything else.

One could debate the point in either direction (and man-pages
has examples of doing things both ways).  In this case, I think
the information can be conveyed compactly enough that it makes sense
to describe everything on one page.

>     If your objection is that it's not marked ".SS", that's probably 
> because I know nothing about groff.  Visually (with nroff -man), it 
> somewhat resembles the information on the printf page.

There is no point in citing the strange exceptions.  (Many things in
printf.3 could be tidied.)  I'm interested in consistency with
the general layout in man-pages, also described in man-pages(7).
I'm not inclined (without very good reason) to accept changes that
create more divergence from the "standard" layout.

>>>  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
>>
>> Why must it be *malloc'd*?  Surely allocation anywhere (stack, heap) 
>> will do?
> 
>     Sorry.  If you ever find out what I was thinking when I wrote this, 
> let me know, 'cause I don't know what I was thinking :).
> 
>     To me, the ideal situation for the man pages around the hash table 
> management would be at least 3 separate man pages:
> -    hsearch/hsearch_r
> -    hcreate/hcreate_r
> -    An overview of the hashing functions (referring to the other two man
>     pages)

I disagree.  I think that the info is short enough that everything can
be in one page.

>     I'm not sure where hdestroy/hdestroy_r should go; probably in its 
> own page, possibly with the overview, and possibly with hcreate & 
> friends.  I'm also not pushing for this change, but if you like the idea 
> better than the way I've done things at the moment, then I'm happy to 
> format things that way too (although then I'd probably need a suggestion 
> on what man section the overview page would go best in).
> 
>     In review, it seems to me like I agree with you, except for:
> -    I think re-entrant functions should be discussed with their brethren,
>     rather than being discussed afterwards

Okay -- I'm not averse to that change.  I'll revise the page in that
way and see how it looks.

> -    I think there's some sort of sectioning needed, which you're not sure
>     of

Oh -- I'm sure: I don't want that ;-).

Cheers,

Michael

>     Thanks for your careful review of the patch.
> 
>     :)
> 
> 
> ---------------------------------------------------------------------
> | Name: Tim Nelson                 | Because the Creator is,        |
> | E-mail: wayland-r28gBBs99rhWo+R/V/U2/g@public.gmane.org    | 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-----
> 
> 

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Patch to hsearch.3 from man-pages-3.08

[Michael Kerrisk]

And, a further revision:

.\" Hey Emacs! This file is -*- nroff -*- source.
.\" Copyright 1993 Ulrich Drepper (drepper-R/BzpT9BeSbQ/dyy7Hk5pA@public.gmane.org)
.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
.\"     <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\" References consulted:
.\"     SunOS 4.1.1 man pages
.\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt <jrv-krxCGfS0CTlN0jTZmbxGZA@public.gmane.org>
.\" Remarks from dhw-iOD1Ui1JDHCMQhOLUu48bZQCsf4PZ8us@public.gmane.org Fri Jun 19 06:46:31 1998
.\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb
.\" 2008-09-02, mtk: various additions and rewrites
.\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from
.\"     Timothy S. Nelson <wayland-r28gBBs99rhWo+R/V/U2/g@public.gmane.org>
.\"
.TH HSEARCH 3 2008-09-03 "GNU" "Linux Programmer's Manual"
.SH NAME
hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r,
hsearch_r \- hash table management
.SH SYNOPSIS
.nf
.B #include <search.h>
.sp
.BI "int hcreate(size_t " nel );
.sp
.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action );
.sp
.B "void hdestroy(void);"
.sp
.B #define _GNU_SOURCE
.br
.B #include <search.h>
.sp
.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab );
.sp
.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval ,
.BI "              struct hsearch_data *" htab );
.sp
.BI "void hdestroy_r(struct hsearch_data *" htab );
.fi
.SH DESCRIPTION
The three functions
.BR hcreate (),
.BR hsearch (),
and
.BR hdestroy ()
allow the caller to create and manage a hash table
containing entries, each of which consists of a key (a string)
and associated data.
Using these functions, only one hash table can be used at a time.

The three functions
.BR hcreate_r (),
.BR hsearch_r (),
.BR hdestroy_r ()
are reentrant versions that allow a program to use
more than one table at the same time.
The last argument,
.IR htab ,
points to a structure that describes the table
on which the function is to operate.
The programmer should treat this structure as opaque
(i.e., do not attempt to directly access or modify
the fields in this structure).

First a hash table must be created using
.BR hcreate ().
The argument \fInel\fP specifies the maximum number of entries
in the table.
(This maximum cannot be changed later, so choose it wisely.)
The implementation may adjust this value upward to improve the
performance of the resulting hash table.
.\" e.g., in glibc it is raised to the next higher prime number

The
.BR hcreate_r ()
function performs the same task as
.BR hcreate (),
but for the table described by the structure
.IR *htab .
The structure pointed to by
.I htab
must be zeroed before the first call to
.BR hcreate_r ().

The function
.BR hdestroy ()
frees the memory occupied by the hash table that was created by
.BR hcreate ().
After calling
.BR hdestroy ()
a new hash table can be created using
.BR hcreate ().
The
.BR hdestroy_r ()
function performs the analogous task for the hash table described by
.IR *htab .

The
.BR hsearch ()
function 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.

The argument \fIitem\fP is of type \fIENTRY\fP, which is defined in
\fI<search.h>\fP as follows:
.in +4n
.sp
.nf
typedef struct entry {
     char *key;
     void *data;
} ENTRY;
.in
.fi
.sp
The field \fIkey\fP points to a null-terminated string which is the
search key.
The field \fIdata\fP points to data that is associated with that key.

The argument \fIaction\fP determines what
.BR hsearch ()
does after an unsuccessful search.
This argument must either have the value
.BR ENTER ,
meaning insert a copy of
.IR item
(and return a pointer to the new hash table entry as the function result),
or the value
.BR FIND ,
meaning that NULL should be returned.
(If
.I action
is
.BR FIND ,
then
.I data
is ignored.)

The
.BR hsearch_r ()
function is like
.BR hsearch ()
but operates on the hash table described by
.IR *htab .
The
.BR hsearch_r ()
function differs from
.BR hsearch ()
in that a pointer to the found item is returned in
.IR *retval ,
rather than as the function result.
.SH "RETURN VALUE"
.BR hcreate ()
and
.BR hcreate_r ()
return non-zero on success.
They return 0 on error.

On success,
.BR hsearch ()
returns a pointer to an entry in the hash table.
.BR hsearch ()
returns NULL on error, that is,
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.
.BR hsearch_r ()
returns non-zero on success, and 0 on error.
.SH ERRORS
.LP
.BR hcreate ()
and
.BR hcreate_r ()
can fail for the following reasons:
.TP
.B EINVAL
.RB ( hcreate_r ())
.I htab
is NULL.
.TP
.B ENOMEM
Table full with \fIaction\fP set to \fBENTER\fP.
.TP
.B ESRCH
The \fIaction\fP argument is \fBFIND\fP and no corresponding element
is found in the table.
.\" hdestroy_r() can set errno to EINVAL if 'tab' is NULL.
.PP
.BR hsearch ()
and
.BR hsearch_r ()
can fail for the following reasons:
.TP
.B ENOMEM
.I action
was
.BR ENTER ,
.I key
was not found in the table,
and there was no room in the table to add a new entry.
.TP
.B ESRCH
.I action
was
.BR FIND ,
and
.I key
was not found in the table.
.PP
POSIX.1-2001 only specifies the
.B ENOMEM
error.
.SH "CONFORMING TO"
The functions
.BR hcreate (),
.BR hsearch (),
and
.BR hdestroy ()
are from SVr4, and are described in POSIX.1-2001.
The functions
.BR hcreate_r (),
.BR hsearch_r (),
and
.BR hdestroy_r ()
are GNU extensions.
.SH NOTES
Hash table implementations are usually more efficient when the
table contains enough free space to minimize collisions.
Typically, this means that
.I nel
should be at least 25% larger than the maximum number of elements
that the caller expects to store in the table.

The
.BR hdestroy ()
and
.BR hdestroy _r()
functions do not free the buffers pointed to by the
.I key
and
.I data
elements of the hash table entries.
(It can't do this because it doesn't know
whether these buffers were allocated dynamically.)
If these buffers need to be freed (perhaps because the program
is repeatedly creating and destroying hash tables,
rather than creating a single table whose lifetime
matches that of the program),
then the program must maintain bookkeeping data structures that
allow it to free them.
.SH BUGS
SVr4 and POSIX.1-2001 specify that \fIaction\fP
is significant only for unsuccessful searches, so that an \fBENTER\fP
should not do anything for a successful search.
In libc and glibc (before version 2.3), the
implementation violates the specification,
updating the \fIdata\fP for the given \fIkey\fP in this case.

Individual hash table entries can be added, but not deleted.
.SH EXAMPLE
.PP
The following program inserts 24 items into a hash table, then prints
some of them.
.nf

#include <stdio.h>
#include <stdlib.h>
#include <search.h>

char *data[] = { "alpha", "bravo", "charlie", "delta",
      "echo", "foxtrot", "golf", "hotel", "india", "juliet",
      "kilo", "lima", "mike", "november", "oscar", "papa",
      "quebec", "romeo", "sierra", "tango", "uniform",
      "victor", "whisky", "x\-ray", "yankee", "zulu"
};

int
main(void)
{
     ENTRY e, *ep;
     int i;

     hcreate(30);

     for (i = 0; i < 24; i++) {
         e.key = data[i];
         /* data is just an integer, instead of a
            pointer to something */
         e.data = (void *) i;
         ep = hsearch(e, ENTER);
         /* there should be no failures */
         if (ep == NULL) {
             fprintf(stderr, "entry failed\\n");
             exit(EXIT_FAILURE);
         }
     }

     for (i = 22; i < 26; i++) {
         /* print two entries from the table, and
            show that two are not in the table */
         e.key = data[i];
         ep = hsearch(e, FIND);
         printf("%9.9s \-> %9.9s:%d\\n", e.key,
                ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0);
     }
     exit(EXIT_SUCCESS);
}
.fi
.SH "SEE ALSO"
.BR bsearch (3),
.BR lsearch (3),
.BR malloc (3),
.BR tsearch (3),
.BR feature_test_macros (7)

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] hsearch.3: Reorder entire page for readability, add information for completeness

[Timothy S. Nelson]

On Wed, 3 Sep 2008, Michael Kerrisk wrote:

> Timothy S. Nelson wrote:
>> On Tue, 2 Sep 2008, Michael Kerrisk wrote:
>> 
>>> Hello Timothy,
>>> 
>>> Timothy S. Nelson wrote:
>>>>     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
>>> 
>>> This is wrong.  See <feature.h> and feature_test_macros(7).
>>
>>     Great!  Thanks.  I'll update the patch so that it tells people to 
>> #include <feature.h>.
>
> From feature_test_macros(7):
>
>   NOTES
>       <features.h>  is  a  Linux/glibc-specific  header   file.
>       Other  systems have an analogous file, but typically with
>       a different name.   This  header  file  is  automatically
>       included  by  other  header  files as required: it is not
>       necessary to explicitly include it  in  order  to  employ
>       feature test macros.
>
>>>> b)    Reading the documentation:
>>>>     http://www.gnu.org/software/libc/manual/html_node/Hash-Search-Function.html#Hash-Search-Function 
>>> 
>>> 
>>> Your mail contains no description of what changes your patch makes,
>>> or why they should be useful.  (I am not a mind reader ;-).)
>>
>>     I guess I assumed you'd take a skim over the patch to find that out, 
>> but I can see why you wouldn't :).
>>
>>     Here's a summary of the changes:
>> -    _GNU_SOURCE didn't work for me, so I'm updating the documentation so
>>     that it will work for others (now #include <feature.h>)
>
> If it didn't work for you then you probably didn't define the FTM before
> including *any* header file.  Including <features.h> should never be
> necessary.

------------------------------------------------------------
#include        <stdio.h>
#include        <stdlib.h>

/* #define              __USE_GNU */
#define         _GNU_SOURCE
#include        <search.h> /* hcreate, etc */

int     main(void) {
         void    *memspace;

         memspace = malloc(sizeof(struct hsearch_data));

         return;
}
------------------------------------------------------------

 	The code above produces this on my Fedora 6 box:

hashexample.c: In function 'main':
hashexample.c:11: error: invalid application of 'sizeof' to incomplete type 
'struct hsearch_data'


 	If I change it to __USE_GNU, it works.  #including features.h makes no 
difference either way.  I'm not sure who's to blame for this, but it'd be nice 
if the man page made some appropriate comment :).

>> I can name
>> two advantages:
[to using subheadings]
>> -    It makes it easier to quickly locate information
>> -    It immediately highlighted the fact that the "ret" argument was not
>>     documented at all (which is something I've corrected in this patch)
>
> Okay -- I already fixed that in my revision of the page.
> (But I got the name wrong: s/retval/ret/)

 	Yeah, I saw that later; that's why it didn't show up.  I was thinking 
more along the lines of general principles, though -- if there are 4 args, and 
4 headings, then something is right :).  But if that's not The Man Page 
Way(TM), then I'm sure I'll cope :).

>>> Also, you've removed the
>>> ..SH RETURN VALUE
>>> section, which really should be present in every .2 and .3 page
>>> (though it is currently missing from several).
>>
>>     I've divided the Return Value into two separate sections, as you've 
>> seen.  This is one of the reasons why I was wondering if there shouldn't be 
>> at least two separate man pages here; one for hsearch/hsearch_r, and one 
>> for everything else.
>
> One could debate the point in either direction (and man-pages
> has examples of doing things both ways).  In this case, I think
> the information can be conveyed compactly enough that it makes sense
> to describe everything on one page.

 	Ok.  I think I would've preferred a longer, more descriptive page, but 
then, I'm a Perl programmer :).  That idea (of the longer, more descriptive 
page, plus probably the Unix "one task, one tool" philosophy) led me in the 
direction of more pages with more information.  But with the rewrite you did, 
plus the reorg below, I'm not too fussed; it's much improved already :).

>>     If your objection is that it's not marked ".SS", that's probably 
>> because I know nothing about groff.  Visually (with nroff -man), it 
>> somewhat resembles the information on the printf page.
>
> There is no point in citing the strange exceptions.  (Many things in
> printf.3 could be tidied.)  I'm interested in consistency with
> the general layout in man-pages, also described in man-pages(7).
> I'm not inclined (without very good reason) to accept changes that
> create more divergence from the "standard" layout.

 	Sure, no worries :).

>>     In review, it seems to me like I agree with you, except for:
>> -    I think re-entrant functions should be discussed with their brethren,
>>     rather than being discussed afterwards
>
> Okay -- I'm not averse to that change.  I'll revise the page in that
> way and see how it looks.

 	Sounds good.  Let me know if you want me to review it when you're 
done.

 	It seems like the only remaining point of discussion is the 
_GNU_SOURCE business above.

 	HTH,


---------------------------------------------------------------------
| Name: Tim Nelson                 | Because the Creator is,        |
| E-mail: wayland-r28gBBs99rhWo+R/V/U2/g@public.gmane.org    | 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-----

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] hsearch.3: Reorder entire page for readability, add information for completeness

[Michael Kerrisk]

On Fri, Sep 5, 2008 at 11:32 AM, Timothy S. Nelson
<wayland-r28gBBs99rhWo+R/V/U2/g@public.gmane.org> wrote:
> On Wed, 3 Sep 2008, Michael Kerrisk wrote:
>
>> Timothy S. Nelson wrote:
>>>
>>> On Tue, 2 Sep 2008, Michael Kerrisk wrote:
>>>
>>>> Hello Timothy,
>>>>
>>>> Timothy S. Nelson wrote:
>>>>>
>>>>>    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
>>>>
>>>> This is wrong.  See <feature.h> and feature_test_macros(7).
>>>
>>>    Great!  Thanks.  I'll update the patch so that it tells people to
>>> #include <feature.h>.
>>
>> From feature_test_macros(7):
>>
>>  NOTES
>>      <features.h>  is  a  Linux/glibc-specific  header   file.
>>      Other  systems have an analogous file, but typically with
>>      a different name.   This  header  file  is  automatically
>>      included  by  other  header  files as required: it is not
>>      necessary to explicitly include it  in  order  to  employ
>>      feature test macros.
>>
>>>>> b)    Reading the documentation:
>>>>>
>>>>>  http://www.gnu.org/software/libc/manual/html_node/Hash-Search-Function.html#Hash-Search-Function
>>>>
>>>>
>>>> Your mail contains no description of what changes your patch makes,
>>>> or why they should be useful.  (I am not a mind reader ;-).)
>>>
>>>    I guess I assumed you'd take a skim over the patch to find that out,
>>> but I can see why you wouldn't :).
>>>
>>>    Here's a summary of the changes:
>>> -    _GNU_SOURCE didn't work for me, so I'm updating the documentation so
>>>    that it will work for others (now #include <feature.h>)
>>
>> If it didn't work for you then you probably didn't define the FTM before
>> including *any* header file.  Including <features.h> should never be
>> necessary.

Please read the preceding paragraph carefully.  The same information
is provided in the second paragraph of  feature_test_macros(7), which
I already suggested you read a couple of times.

> ------------------------------------------------------------

#define         _GNU_SOURCE

> #include        <stdio.h>
> #include        <stdlib.h>
>
> /* #define              __USE_GNU */
> #define         _GNU_SOURCE
> #include        <search.h> /* hcreate, etc */
>
> int     main(void) {
>        void    *memspace;
>
>        memspace = malloc(sizeof(struct hsearch_data));
>
>        return;
> }
> ------------------------------------------------------------
>
>        The code above produces this on my Fedora 6 box:
>
> hashexample.c: In function 'main':
> hashexample.c:11: error: invalid application of 'sizeof' to incomplete type
> 'struct hsearch_data'
>
>
>        If I change it to __USE_GNU, it works.  #including features.h makes
> no difference either way.  I'm not sure who's to blame for this, but it'd be
> nice if the man page made some appropriate comment :).
>
>>> I can name
>>> two advantages:
>
> [to using subheadings]
>>>
>>> -    It makes it easier to quickly locate information
>>> -    It immediately highlighted the fact that the "ret" argument was not
>>>    documented at all (which is something I've corrected in this patch)
>>
>> Okay -- I already fixed that in my revision of the page.
>> (But I got the name wrong: s/retval/ret/)
>
>        Yeah, I saw that later; that's why it didn't show up.  I was thinking
> more along the lines of general principles, though -- if there are 4 args,
> and 4 headings, then something is right :).  But if that's not The Man Page
> Way(TM), then I'm sure I'll cope :).
>
>>>> Also, you've removed the
>>>> ..SH RETURN VALUE
>>>> section, which really should be present in every .2 and .3 page
>>>> (though it is currently missing from several).
>>>
>>>    I've divided the Return Value into two separate sections, as you've
>>> seen.  This is one of the reasons why I was wondering if there shouldn't be
>>> at least two separate man pages here; one for hsearch/hsearch_r, and one for
>>> everything else.
>>
>> One could debate the point in either direction (and man-pages
>> has examples of doing things both ways).  In this case, I think
>> the information can be conveyed compactly enough that it makes sense
>> to describe everything on one page.
>
>        Ok.  I think I would've preferred a longer, more descriptive page,
> but then, I'm a Perl programmer :).  That idea (of the longer, more
> descriptive page, plus probably the Unix "one task, one tool" philosophy)
> led me in the direction of more pages with more information.  But with the
> rewrite you did, plus the reorg below, I'm not too fussed; it's much
> improved already :).
>
>>>    If your objection is that it's not marked ".SS", that's probably
>>> because I know nothing about groff.  Visually (with nroff -man), it somewhat
>>> resembles the information on the printf page.
>>
>> There is no point in citing the strange exceptions.  (Many things in
>> printf.3 could be tidied.)  I'm interested in consistency with
>> the general layout in man-pages, also described in man-pages(7).
>> I'm not inclined (without very good reason) to accept changes that
>> create more divergence from the "standard" layout.
>
>        Sure, no worries :).
>
>>>    In review, it seems to me like I agree with you, except for:
>>> -    I think re-entrant functions should be discussed with their
>>> brethren,
>>>    rather than being discussed afterwards
>>
>> Okay -- I'm not averse to that change.  I'll revise the page in that
>> way and see how it looks.
>
>        Sounds good.  Let me know if you want me to review it when you're
> done.
>
>        It seems like the only remaining point of discussion is the
> _GNU_SOURCE business above.
>
>        HTH,
>
>
> ---------------------------------------------------------------------
> | Name: Tim Nelson                 | Because the Creator is,        |
> | E-mail: wayland-r28gBBs99rhWo+R/V/U2/g@public.gmane.org    | 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-----
>
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] hsearch.3: Reorder entire page for readability, add information for completeness

[Timothy S. Nelson]

On Fri, 5 Sep 2008, Michael Kerrisk wrote:

>>> If it didn't work for you then you probably didn't define the FTM before
>>> including *any* header file.  Including <features.h> should never be
>>> necessary.
>
> Please read the preceding paragraph carefully.  The same information
> is provided in the second paragraph of  feature_test_macros(7), which
> I already suggested you read a couple of times.

 	Ouch!  Thanks.  I looked at that page, but just skipped to the 
_GNU_SOURCE section :).  Now I understand what needs to happen.  Thanks.


---------------------------------------------------------------------
| Name: Tim Nelson                 | Because the Creator is,        |
| E-mail: wayland-r28gBBs99rhWo+R/V/U2/g@public.gmane.org    | 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-----

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html