From owner-svn-src-head@FreeBSD.ORG  Mon Nov  4 16:56:36 2013
Return-Path: <owner-svn-src-head@FreeBSD.ORG>
Delivered-To: svn-src-head@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org
 [IPv6:2001:1900:2254:206a::19:1])
 (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
 (No client certificate requested)
 by hub.freebsd.org (Postfix) with ESMTP id 82BB24AC;
 Mon,  4 Nov 2013 16:56:36 +0000 (UTC)
 (envelope-from glebius@FreeBSD.org)
Received: from svn.freebsd.org (svn.freebsd.org
 [IPv6:2001:1900:2254:2068::e6a:0])
 (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
 (No client certificate requested)
 by mx1.freebsd.org (Postfix) with ESMTPS id 6F77A2365;
 Mon,  4 Nov 2013 16:56:36 +0000 (UTC)
Received: from svn.freebsd.org ([127.0.1.70])
 by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id rA4Guab0053723;
 Mon, 4 Nov 2013 16:56:36 GMT (envelope-from glebius@svn.freebsd.org)
Received: (from glebius@localhost)
 by svn.freebsd.org (8.14.7/8.14.5/Submit) id rA4GuaeC053722;
 Mon, 4 Nov 2013 16:56:36 GMT (envelope-from glebius@svn.freebsd.org)
Message-Id: <201311041656.rA4GuaeC053722@svn.freebsd.org>
From: Gleb Smirnoff <glebius@FreeBSD.org>
Date: Mon, 4 Nov 2013 16:56:36 +0000 (UTC)
To: src-committers@freebsd.org, svn-src-all@freebsd.org,
 svn-src-head@freebsd.org
Subject: svn commit: r257643 - head/share/man/man3
X-SVN-Group: head
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-BeenThere: svn-src-head@freebsd.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: SVN commit messages for the src tree for head/-current
 <svn-src-head.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/svn-src-head>,
 <mailto:svn-src-head-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/svn-src-head>
List-Post: <mailto:svn-src-head@freebsd.org>
List-Help: <mailto:svn-src-head-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/svn-src-head>,
 <mailto:svn-src-head-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Mon, 04 Nov 2013 16:56:36 -0000

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.