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. 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 (), -- 2.16.2.804.g6dcf76e118-goog -- 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
