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_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>
@@ -153,6 +157,16 @@ Thus, the choice of name
 .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 ,
@@ -193,6 +207,9 @@ also
 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).
@@ -211,14 +228,19 @@ 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.
-The function
+The functions
 .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