LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

tsearch.3: Clarify items vs nodes 

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@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Jann Horn 2018-03-21 17:44:58 +01:00 committed by Michael Kerrisk
parent 19d371260e
commit f119ba87ea
1 changed files with 14 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
man3/tsearch.3
View File

@ -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 (),