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.

---
This is for glibc 2.34.

 manual/search.texi | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)
  

Hi Florian,

> +This is a limiting restriction of the functionality of the
> +@code{hsearch} functions: They can only be used for data sets which
> +use the NUL character always and solely to terminate keys.  It is not
> +possible to handle general binary data for keys.

I thought there was a typo in "NUL character" but I see it appears in other
places. However in sunrpc/xdr.c there is "NULL character". Should this be
changed to "NUL character"?

Paul
  

* Paul Zimmermann:

>        Hi Florian,
>
>> +This is a limiting restriction of the functionality of the
>> +@code{hsearch} functions: They can only be used for data sets which
>> +use the NUL character always and solely to terminate keys.  It is not
>> +possible to handle general binary data for keys.
>
> I thought there was a typo in "NUL character" but I see it appears in other
> places. However in sunrpc/xdr.c there is "NULL character". Should this be
> changed to "NUL character"?

Maybe.  sunrpc is legacy code.  Changing it is not a priority to me.

Thanks,
Florian
  

On Feb 01 2021, Paul Zimmermann wrote:

>        Hi Florian,
>
>> +This is a limiting restriction of the functionality of the
>> +@code{hsearch} functions: They can only be used for data sets which
>> +use the NUL character always and solely to terminate keys.  It is not
>> +possible to handle general binary data for keys.
>
> I thought there was a typo in "NUL character" but I see it appears in other
> places. However in sunrpc/xdr.c there is "NULL character". Should this be
> changed to "NUL character"?

The null character has the ASCII abbrev NUL, and NULL doesn't fit here.

Andreas.
  

Hi Florian,

> Subject: [PATCH] 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.

> diff --git a/manual/search.texi b/manual/search.texi

> @@ -326,24 +326,28 @@ used until the end of the program run.
>  Entries of the hashing table and keys for the search are defined using
>  this type:
>  
> -@deftp {Data type} {struct ENTRY}
> -Both elements of this structure are pointers to zero-terminated strings.
> -This is a limiting restriction of the functionality of the
> -@code{hsearch} functions.  They 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.
> -
> +@deftp {Data type} ENTRY

This looks Okay. ENTRY is typedef for struct entry, and every sentence
in that paragraph you removed is incorrect.

>  @table @code
>  @item char *key
>  Pointer to a zero-terminated string of characters describing the key for
>  the search or the element in the hashing table.

Okay. Unchanged.

> -@item char *data
> -Pointer to a zero-terminated string of characters describing the data.
> -If the functions will be called only for searching an existing entry
> -this element might stay undefined since it is not used.

Okay. Removed incorrect description of `data'.

> +
> +This is a limiting restriction of the functionality of the
> +@code{hsearch} functions: They can only be used for data sets which
> +use the NUL character always and solely to terminate keys.  It is not
> +possible to handle general binary data for keys.

Okay. Continues to explain `key' and mentions how it should be a NUL
terminated string.

> +
> +@item void *data
> +Generic pointer for use by the application.  The hashing table
> +implementation preserves this pointer in entries, but does not use it
> +in any way otherwise.

Okay. New, correct description of `data'.

>  @end table
>  @end deftp
>  
> +@deftp {Data type} {struct entry}
> +The underlying type of @code{ENTRY}.
> +@end deftp
> +
>  @deftypefun {ENTRY *} hsearch (ENTRY @var{item}, ACTION @var{action})
>  @standards{SVID, search.h}
>  @safety{@prelim{}@mtunsafe{@mtasurace{:hsearch}}@asunsafe{}@acunsafe{@acucorrupt{/action==ENTER}}}

Okay.  ENTRY is a typedef for struct entry.

I applied your patch and verified that the result of `make info' was well
formed.

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

Cheers,
Arjun
  

On Feb 01 2021, Florian Weimer via Libc-alpha wrote:

> +@deftp {Data type} {struct entry}
> +The underlying type of @code{ENTRY}.
> +@end deftp

Does that need to be documented?  Nothing references it, and it isn't
part of the search.h interface.  It looks more like an implementation
detail.

Andreas.
  

* Andreas Schwab:

> On Feb 01 2021, Florian Weimer via Libc-alpha wrote:
>
>> +@deftp {Data type} {struct entry}
>> +The underlying type of @code{ENTRY}.
>> +@end deftp
>
> Does that need to be documented?  Nothing references it, and it isn't
> part of the search.h interface.  It looks more like an implementation
> detail.

The struct tag required by POSIX, and it is relevant for C++ name
mangling.  C programmers are also affected because they cannot defined
their own struct entry after including <search.h>.

Thanks,
Florian