Hello Jann, On 03/21/2018 05:44 PM, Jann Horn wrote: > The manpage claimed that tsearch() returns a pointer to a data item. This > is incorrect; tsearch() returns a pointer to the corresponding tree node, > which can also be interpreted as a pointer to a pointer to the data item. > > Since this API is quite unintuitive, also add a clarifying sentence. Thanks! Patch applied. Cheers, Michael > Signed-off-by: Jann Horn <jannh@xxxxxxxxxx> > --- > man3/tsearch.3 | 25 ++++++++++++++----------- > 1 file changed, 14 insertions(+), 11 deletions(-) > > diff --git a/man3/tsearch.3 b/man3/tsearch.3 > index a5aa962af..5cbc8b7a4 100644 > --- a/man3/tsearch.3 > +++ b/man3/tsearch.3 > @@ -24,7 +24,7 @@ > .\" > .TH TSEARCH 3 2015-08-08 "GNU" "Linux Programmer's Manual" > .SH NAME > -tsearch, tfind, tdelete, twalk, tdestroy \- manage a binary tree > +tsearch, tfind, tdelete, twalk, tdestroy \- manage a binary search tree > .SH SYNOPSIS > .nf > .B #include <search.h> > @@ -54,7 +54,7 @@ tsearch, tfind, tdelete, twalk, tdestroy \- manage a binary tree > and > .BR tdelete () > manage a > -binary tree. > +binary search tree. > They are generalized from Knuth (6.2.2) Algorithm T. > The first field in each node of the tree is a pointer to the > corresponding data item. > @@ -79,11 +79,14 @@ points to should be set to NULL. > If the item is found in the tree, then > .BR tsearch () > returns a pointer > -to it. > -If it is not found, then > +to the corresponding tree node. > +(In other words, > +.BR tsearch () > +returns a pointer to a pointer to the data item.) > +If the item is not found, then > .BR tsearch () > adds it, and returns a > -pointer to the newly added item. > +pointer to the corresponding tree node. > .PP > .BR tfind () > is like > @@ -165,17 +168,17 @@ must point to a function > doing nothing. > .SH RETURN VALUE > .BR tsearch () > -returns a pointer to a matching item in the tree, or to > -the newly added item, or NULL if there was insufficient memory > +returns a pointer to a matching node in the tree, or to > +the newly added node, or NULL if there was insufficient memory > to add the item. > .BR tfind () > -returns a pointer to the item, or > +returns a pointer to the node, or > NULL if no match is found. > -If there are multiple elements that match the key, > -the element returned is unspecified. > +If there are multiple items that match the key, > +the item whose node is returned is unspecified. > .PP > .BR tdelete () > -returns a pointer to the parent of the item deleted, or > +returns a pointer to the parent of the node deleted, or > NULL if the item was not found. > .PP > .BR tsearch (), > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
