svn commit: r257643 - head/share/man/man3

[Gleb Smirnoff]

Author: glebius
Date: Mon Nov  4 16:56:35 2013
New Revision: 257643
URL: http://svnweb.freebsd.org/changeset/base/257643

Log:
  Document RB_FOREACH_SAFE() and RB_FOREACH_REVERSE_SAFE().
  
  Submitted by:	Mikhail <mp lenta.ru>

Modified:
  head/share/man/man3/tree.3

Modified: head/share/man/man3/tree.3
==============================================================================
--- head/share/man/man3/tree.3	Mon Nov  4 16:52:27 2013	(r257642)
+++ head/share/man/man3/tree.3	Mon Nov  4 16:56:35 2013	(r257643)
@@ -30,7 +30,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd December 27, 2007
+.Dd November 4, 2013
 .Dt TREE 3
 .Os
 .Sh NAME
@@ -70,7 +70,9 @@
 .Nm RB_RIGHT ,
 .Nm RB_PARENT ,
 .Nm RB_FOREACH ,
+.Nm RB_FOREACH_SAFE ,
 .Nm RB_FOREACH_REVERSE ,
+.Nm RB_FOREACH_REVERSE_SAFE ,
 .Nm RB_INIT ,
 .Nm RB_INSERT ,
 .Nm RB_REMOVE
@@ -135,7 +137,9 @@
 .Ft "struct TYPE *"
 .Fn RB_PARENT "struct TYPE *elm" "RB_ENTRY NAME"
 .Fn RB_FOREACH VARNAME NAME "RB_HEAD *head"
+.Fn RB_FOREACH_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME"
 .Fn RB_FOREACH_REVERSE VARNAME NAME "RB_HEAD *head"
+.Fn RB_FOREACH_REVERSE_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME"
 .Ft void
 .Fn RB_INIT "RB_HEAD *head"
 .Ft "struct TYPE *"
@@ -454,6 +458,18 @@ macro:
 .Fn RB_FOREACH np NAME head
 .Ed
 .Pp
+The macros
+.Fn RB_FOREACH_SAFE
+and
+.Fn RB_FOREACH_REVERSE_SAFE
+traverse the tree referenced by head
+in a forward or reverse direction respectively,
+assigning each element in turn to np.
+However, unlike their unsafe counterparts,
+they permit both the removal of np
+as well as freeing it from within the loop safely
+without interfering with the traversal.
+.Pp
 The
 .Fn RB_EMPTY
 macro should be used to check whether a red-black tree is empty.