svn commit: r261015 - stable/10/share/man/man3

[Gleb Smirnoff]

Author: glebius
Date: Wed Jan 22 09:59:49 2014
New Revision: 261015
URL: http://svnweb.freebsd.org/changeset/base/261015

Log:
  Merge 257643: Document RB_FOREACH_SAFE() and RB_FOREACH_REVERSE_SAFE().

Modified:
  stable/10/share/man/man3/tree.3
Directory Properties:
  stable/10/   (props changed)

Modified: stable/10/share/man/man3/tree.3
==============================================================================
--- stable/10/share/man/man3/tree.3	Wed Jan 22 09:57:26 2014	(r261014)
+++ stable/10/share/man/man3/tree.3	Wed Jan 22 09:59:49 2014	(r261015)
@@ -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.