From owner-cvs-all  Wed Jan  2  6:37: 4 2002
Delivered-To: cvs-all@freebsd.org
Received: from mongrel.pacific.net.au (mongrel.pacific.net.au [61.8.0.107])
	by hub.freebsd.org (Postfix) with ESMTP
	id 0BCF537B41B; Wed,  2 Jan 2002 06:36:53 -0800 (PST)
Received: from dungeon.home (ppp38.dyn248.pacific.net.au [203.143.248.38])
	by mongrel.pacific.net.au (8.9.3/8.9.3/Debian 8.9.3-21) with ESMTP id BAA25535;
	Thu, 3 Jan 2002 01:30:47 +1100
X-Authentication-Warning: mongrel.pacific.net.au: Host ppp38.dyn248.pacific.net.au [203.143.248.38] claimed to be dungeon.home
Received: from dungeon.home (localhost [127.0.0.1])
	by dungeon.home (8.11.3/8.11.1) with ESMTP id g02Eess11512;
	Thu, 3 Jan 2002 00:40:54 +1000 (EST)
	(envelope-from mckay)
Message-Id: <200201021440.g02Eess11512@dungeon.home>
To: Julian Elischer <julian@elischer.org>
Cc: John Baldwin <jhb@FreeBSD.org>,
	Poul-Henning Kamp <phk@critter.freebsd.dk>, cvs-all@FreeBSD.org,
	cvs-committers@FreeBSD.org, Julian Elischer <julian@FreeBSD.org>,
	Greg Lehey <grog@FreeBSD.org>, mckay@thehub.com.au
Subject: Re: cvs commit: src/share/man/man3 queue.3 
References: <20011231165233.A408@dhcp01.pn.xcllnt.net> <Pine.BSF.4.21.0112311706450.10883-100000@InterJet.elischer.org>
In-Reply-To: <Pine.BSF.4.21.0112311706450.10883-100000@InterJet.elischer.org>
    from Julian Elischer at "Tue, 01 Jan 2002 01:14:08 +0000"
Date: Thu, 03 Jan 2002 00:40:54 +1000
From: Stephen McKay <mckay@thehub.com.au>
Sender: owner-cvs-all@FreeBSD.ORG
Precedence: bulk
List-ID: <cvs-all.FreeBSD.ORG>
List-Archive: <http://docs.freebsd.org/mail/> (Web Archive)
List-Help: <mailto:majordomo@FreeBSD.ORG?subject=help> (List Instructions)
List-Subscribe: <mailto:majordomo@FreeBSD.ORG?subject=subscribe%20cvs-all>
List-Unsubscribe: <mailto:majordomo@FreeBSD.ORG?subject=unsubscribe%20cvs-all>
X-Loop: FreeBSD.ORG

On Tuesday, 1st January 2002, Julian Elischer wrote:

>> >          TAILQ_FOREACH(p, &list, p_next)
>
>So you think that the final value of p should be undefined,
>and there is no  built in way to see if there were any elements in the
>list at all or whether we completed the list?

I'd have to say, "Yes".  I expect p to be undefined when the TAILQ_FOREACH
completes.  It's an internal implementation detail.  Similarly, I wouldn't
depend on p == head for CIRCLEQ_FOREACH.  You can roll your own loop if
you want special behaviour.

>I'm just documenting what the code does, and how people have used it.
>if you think that phk is correct we should add an example to the man page 
>showing:

Perhaps Marcel's good example instead:

>        TAILQ_FOREACH(p, &list, p_next) {
>                if (some_test_on(p)) {
>                        /* Do something */
>                        break; /* optional */
>                }
>        }

The man page should explicitly state that p is undefined after the loop
completes unless the user breaks out.  Oh, and explicitly stating that it
is OK to break out at all might be nice too. :-)

Stephen.

To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe cvs-all" in the body of the message