Message ID | 87tuqwrth8.fsf@oldenburg.str.redhat.com |
---|---|
State | New |
Headers | show |
Series | manual: Correct description of ENTRY [BZ #17183] | expand |
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
diff --git a/manual/search.texi b/manual/search.texi index 60c851229c..5691bf2f2b 100644 --- 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 @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. -@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. + +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. + +@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. @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}}}