tsearch.3: Document the twalk_r() function added in glibc 2.30

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man3/tsearch.3 b/man3/tsearch.3
index 494c7839fe40c9bd19beb489efecbe992e975e78..769bfe28674d592a40325de70eccef0dff2efed7 100644 (file)
--- a/man3/tsearch.3
+++ b/man3/tsearch.3
@@ -42,6 +42,10 @@ tsearch, tfind, tdelete, twalk, tdestroy \- manage a binary search tree
 .PP
 .BI "void twalk(const void *" root ", void (*" action ")(const void *" nodep ,
 .BI "                                   VISIT " which ", int " depth "));"
 .PP
 .BI "void twalk(const void *" root ", void (*" action ")(const void *" nodep ,
 .BI "                                   VISIT " which ", int " depth "));"

+.PP
+.BI "void twalk_r(const void *" root ", void (*" action ")(const void *" np ,
+.BI "                                   VISIT " which ", void *" closure "),
+.BI "                                   void *" closure);"

 
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 .B #include <search.h>
 
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 .B #include <search.h>


@@ -153,6 +157,16 @@ Thus, the choice of name
 .B post\%order
 is rather confusing.)
 .PP
 .B post\%order
 is rather confusing.)
 .PP

+.BR twalk_r ()
+is similar to
+.BR twalk (),
+but instead of the leval argument, the
+.I closure
+argument pointer is passed to each invocation of the action callback,
+unchanged.  This pointer can be used to pass information to and from
+to the callback function in a thread-safe fashion, without resorting
+to global variables.
+.PP

 .BR tdestroy ()
 removes the whole tree pointed to by
 .IR root ,
 .BR tdestroy ()
 removes the whole tree pointed to by
 .IR root ,


@@ -193,6 +207,9 @@ also
 return NULL if
 .I rootp
 was NULL on entry.
 return NULL if
 .I rootp
 was NULL on entry.

+.SH VERSIONS
+.BR twalk_r ()
+is available since glibc 2.30.

 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).


@@ -211,14 +228,19 @@ T{
 .BR twalk ()
 T}     Thread safety   MT-Safe race:root
 T{
 .BR twalk ()
 T}     Thread safety   MT-Safe race:root
 T{

+.BR twalk_r ()
+T}     Thread safety   MT-Safe race:root
+T{

 .BR tdestroy ()
 T}     Thread safety   MT-Safe
 .TE
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, SVr4.
 .BR tdestroy ()
 T}     Thread safety   MT-Safe
 .TE
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, SVr4.

-The function
+The functions

 .BR tdestroy ()
 .BR tdestroy ()

-is a GNU extension.
+and
+.BR twalk_r ()
+are GNU extensions.

 .SH NOTES
 .BR twalk ()
 takes a pointer to the root, while the other functions
 .SH NOTES
 .BR twalk ()
 takes a pointer to the root, while the other functions