git: b0d4b059cf84 - main - tdestroy(3) man page

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=b0d4b059cf8425cbe094f93362a61c56a26d45f3

commit b0d4b059cf8425cbe094f93362a61c56a26d45f3
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2025-12-26 18:27:32 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2025-12-29 17:18:55 +0000

    tdestroy(3) man page
    
    Reviewed by:    alc, emaste, ziaee
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D54365
---
 lib/libc/stdlib/Makefile.inc |  3 ++-
 lib/libc/stdlib/tsearch.3    | 25 +++++++++++++++++++++++--
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/lib/libc/stdlib/Makefile.inc b/lib/libc/stdlib/Makefile.inc
index e46a8d7340b2..c311ba3d2bcc 100644
--- a/lib/libc/stdlib/Makefile.inc
+++ b/lib/libc/stdlib/Makefile.inc
@@ -147,4 +147,5 @@ MLINKS+=strtoul.3 strtoull.3 \
 	strtoul.3 strtoumax.3
 MLINKS+=tsearch.3 tdelete.3 \
 	tsearch.3 tfind.3 \
-	tsearch.3 twalk.3
+	tsearch.3 twalk.3 \
+	tsearch.3 tdestroy.3
diff --git a/lib/libc/stdlib/tsearch.3 b/lib/libc/stdlib/tsearch.3
index edee01cafc52..f412c37a4ef0 100644
--- a/lib/libc/stdlib/tsearch.3
+++ b/lib/libc/stdlib/tsearch.3
@@ -36,6 +36,7 @@
 .In search.h
 .Ft void *
 .Fn tdelete "const void * restrict key" "posix_tnode ** restrict rootp" "int (*compar) (const void *, const void *)"
+.Fn tdestroy "posix_tnode *root" "(void (*node_free)(void *)"
 .Ft posix_tnode *
 .Fn tfind "const void *key" "posix_tnode * const *rootp" "int (*compar) (const void *, const void *)"
 .Ft posix_tnode *
@@ -45,6 +46,7 @@
 .Sh DESCRIPTION
 The
 .Fn tdelete ,
+.Fn tdestroy ,
 .Fn tfind ,
 .Fn tsearch ,
 and
@@ -95,6 +97,13 @@ If the node to be deleted is the root of the binary search tree,
 will be adjusted.
 .Pp
 The
+.Fn tdestroy
+function destroys the whole search tree, freeing all allocated nodes.
+If tree keys need special handling on free, the
+.Fa node_free
+function can be provided, which is called on each key.
+.Pp
+The
 .Fn twalk
 function
 walks the binary search tree rooted in
@@ -128,7 +137,9 @@ is NULL or the datum cannot be found.
 .Pp
 The
 .Fn twalk
-function returns no value.
+and
+.Fn tdestroy
+functions return no value.
 .Sh EXAMPLES
 This example uses
 .Fn tsearch
@@ -184,6 +195,7 @@ main(void)
 	tdelete(four, &root, comp);
 
 	twalk(root, printwalk);
+	tdestroy(root, NULL);
 	return 0;
 }
 .Ed
@@ -192,8 +204,17 @@ main(void)
 .Xr hsearch 3 ,
 .Xr lsearch 3
 .Sh STANDARDS
-These functions conform to
+These
+.Fn tdelete ,
+.Fn tfind ,
+.Fn tsearch ,
+and
+.Fn twalk
+functions conform to
 .St -p1003.1-2008 .
+The
+.Fn tdestroy
+function is the glibc extension.
 .Pp
 The
 .Fa posix_tnode