[Bug manual/17183] New: description of ENTRY struct in <search.h> in glibc manual is incorrect

[Bug manual/17183] New: description of ENTRY struct in <search.h> in glibc manual is incorrect

[iep1ungo at yopmail dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=17183

            Bug ID: 17183
           Summary: description of ENTRY struct in <search.h> in glibc
                    manual is incorrect
           Product: glibc
           Version: unspecified
            Status: NEW
          Severity: normal
          Priority: P2
         Component: manual
          Assignee: unassigned at sourceware dot org
          Reporter: iep1ungo at yopmail dot com
                CC: mtk.manpages at gmail dot com, roland at gnu dot org

The glibc manual incorrectly describes the ENTRY struct defined in <search.h>
(the hash table entries used by hsearch().

The manual states that both the key and the data fields of the ENTRY struct are
char pointers.
( here
https://www.gnu.org/software/libc/manual/html_node/Hash-Search-Function.html )

This is incorrect. The "key" field is a char* and the "data" field is a null*.

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug manual/17183] description of ENTRY struct in <search.h> in glibc manual is incorrect

[iep1ungo at yopmail dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=17183

iep1ungo at yopmail dot com changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
            Version|unspecified                 |2.19

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug manual/17183] description of ENTRY struct in <search.h> in glibc manual is incorrect

[kevinwmatthews.bugzilla at gmail dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=17183

Kevin <kevinwmatthews.bugzilla at gmail dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |kevinwmatthews.bugzilla@gma
                   |                            |il.com

--- Comment #1 from Kevin <kevinwmatthews.bugzilla at gmail dot com> ---
Created attachment 13176
  --> https://sourceware.org/bugzilla/attachment.cgi?id=13176&action=edit
hsearch ENTRY docs

I also encountered this bug: the docs state that ENTRY's data element is a char
*, but it is in fact a void *.

Additionally, the docs state that the data element can not point to general
binary data. This appears to be incorrect; the key must be a null-terminated
string, but the data can be arbitrary.

For reference, the current POSIX spec states:

> item.key points to the comparison key (a char *),
> and item.data (a void *) points to any other data to be
> associated with that key.

I've attached a idea for a patch to the docs, but feedback is quite welcome;
I'm still learning glibc's process.

Background info is below. The current glibc docs state that ENTRY structs:

> [..] can only be used for data sets which use
> the NUL character always and solely to terminate the records.  It is not
> possible to handle general binary data.

In the current implementation, hsearch uses strcmp() on the key:

// From misc/hsearch_r.c
/* If entry is found use it. */
if (htab->table[idx].used == hval
  && strcmp (item.key, htab->table[idx].entry.key) == 0)

The data pointer is never directly referenced. It is copied along with the
entire struct, both when copied into the hash table:

if (action == ENTER)
  {
  /* .. */
  htab->table[idx].entry = item;

and when returned:

*retval = &htab->table[idx].entry;

It should be safe to pass binary data using the pointer.

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug manual/17183] description of ENTRY struct in <search.h> in glibc manual is incorrect

[fweimer at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=17183

Florian Weimer <fweimer at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |ASSIGNED
           Assignee|unassigned at sourceware dot org   |fweimer at redhat dot com
                 CC|                            |fweimer at redhat dot com

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug manual/17183] description of ENTRY struct in <search.h> in glibc manual is incorrect

[fweimer at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=17183

--- Comment #2 from Florian Weimer <fweimer at redhat dot com> ---
Patch posted:
https://sourceware.org/pipermail/libc-alpha/2021-February/122184.html

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug manual/17183] description of ENTRY struct in <search.h> in glibc manual is incorrect

[fweimer at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=17183

Florian Weimer <fweimer at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Resolution|---                         |FIXED
             Status|ASSIGNED                    |RESOLVED

--- Comment #3 from Florian Weimer <fweimer at redhat dot com> ---
Fixed for glibc 2.34 via:

commit 2d8a22cdecca225068f56bcfee862696d5b4a83b
Author: Florian Weimer <fweimer@redhat.com>
Date:   Thu Feb 4 15:02:38 2021 +0100

    manual: Correct description of ENTRY [BZ #17183]

    The struct tag is actually entry (not ENTRY).  The data member has
    type void *, and it can point to binary data.  Only the key member is
    required to be a null-terminated string.

    Reviewed-by: Arjun Shankar <arjun@redhat.com>

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug manual/17183] description of ENTRY struct in <search.h> in glibc manual is incorrect

[fweimer at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=17183

Florian Weimer <fweimer at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
   Target Milestone|---                         |2.34

-- 
You are receiving this mail because:
You are on the CC list for the bug.