From hg@cally.south.mpcs.com Wed Nov 17 08:04:23 1999
Return-Path: <hg@cally.south.mpcs.com>
Received: from cc1017255-a.srst1.fl.home.com (cc1017255-a.srst1.fl.home.com [24.3.122.197])
	by hub.freebsd.org (Postfix) with ESMTP id 1DAD214A15
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 17 Nov 1999 08:04:21 -0800 (PST)
	(envelope-from hg@cally.south.mpcs.com)
Received: from cally.south.mpcs.com (cally [172.16.0.6])
	by cc1017255-a.srst1.fl.home.com (Postfix) with ESMTP id 6D8841E5A
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 17 Nov 1999 11:04:21 -0500 (EST)
Received: by cally.south.mpcs.com (Postfix, from userid 1000)
	id 08E2522D; Wed, 17 Nov 1999 11:04:20 -0500 (EST)
Message-Id: <19991117160420.08E2522D@cally.south.mpcs.com>
Date: Wed, 17 Nov 1999 11:04:20 -0500 (EST)
From: hgoldste@bbs.mpcs.com
Sender: hg@cally.south.mpcs.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: <Synopsis of the problem (one line)> queue(3) STAILQ_INSERT_TAIL is suprising when the queue is empty
X-Send-Pr-Version: 3.2

>Number:         14950
>Category:       kern
>Synopsis:       queue(3) STAILQ_INSERT_TAIL is suprising when the queue is empty
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    gnats-admin
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Nov 17 08:10:00 PST 1999
>Closed-Date:    Wed Nov 17 11:31:48 PST 1999
>Last-Modified:  Wed Oct 26 06:18:58 GMT 2005
>Originator:     Howard Goldstein
>Release:        FreeBSD 3.3-STABLE i386
>Organization:
>Environment:

	

cally:/usr/cally/home/hg$ ident /usr/include/sys/queue.h 
/usr/include/sys/queue.h:
     $FreeBSD: src/sys/sys/queue.h,v 1.24.2.1 1999/08/29 16:32:39 peter Exp $


	<Precise description of the problem (multiple lines)>

The handy STAILQ macro collection's STAILQ_INSERT_TAIL is broken
for empty queue (fails to initialize the queue head's stqh_first field).
If the code is not broken then the docs should probably point out
the STAILQ_INSERT_TAIL's dependancy on !STAILQ_EMPTY

>Description:
>How-To-Repeat:

	
Create an empty tail queue with STAILQ_INIT.  Then use STAILQ_INSERT_TAIL
to add an entry to the queue.  Then test STAILQ_EMPTY which will report
empty.  Note that further use of _INSERT_TAIL on this queue will correctly
link the new records together except that the head node continues to point
to NULL
 
>Fix:
	
	
Work around:
if STAILQ_EMPTY
  Use STAILQ_INSERT_HEAD 
else
  Use STAILQ_INSERT_TAIL



>Release-Note:
>Audit-Trail:

From: "Justin T. Gibbs" <gibbs@FreeBSD.org>
To: hgoldste@bbs.mpcs.com
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: pending/14950: <Synopsis of the problem (one line)> queue(3) 
 STAILQ_INSERT_TAIL is suprising when the queue is empty
Date: Wed, 17 Nov 1999 08:18:37 -0700

 >>Synopsis:       queue(3) STAILQ_INSERT_TAIL is suprising when the queue is 
 empty
 
 ...
 
 >The handy STAILQ macro collection's STAILQ_INSERT_TAIL is broken
 >for empty queue (fails to initialize the queue head's stqh_first field).
 >If the code is not broken then the docs should probably point out
 >the STAILQ_INSERT_TAIL's dependancy on !STAILQ_EMPTY
 
 When an STAILQ is empty, head->stqh_last = &(head)->stqh_first.
 Thus, STAILQ_INSERT_TAIL initializes head->stqh_first through the
 stqh_last member:
 
 #define STAILQ_INSERT_TAIL(head, elm, field) do {                       \
         (elm)->field.stqe_next = NULL;                                  \
         *(head)->stqh_last = (elm);                                     \
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^
         (head)->stqh_last = &(elm)->field.stqe_next;                    \
 } while (0)
 
 Of course if you fail to properly initialize an STAILQ, this assumption
 will fail and the macro will not do the right thing. Do you have a
 code example that displays a problem with the macros?  From inspection,
 the macros look correct.
 
 --
 Justin
 
 
 

From: Howard Goldstein <hgoldste@bbs.mpcs.com>
To: "Justin T. Gibbs" <gibbs@FreeBSD.org>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: pending/14950: <Synopsis of the problem (one line)> queue(3) 
 STAILQ_INSERT_TAIL is suprising when the queue is empty
Date: Wed, 17 Nov 1999 14:29:31 -0500 (EST)

 Justin T. Gibbs writes:
  > >>Synopsis:       queue(3) STAILQ_INSERT_TAIL is suprising when the queue is 
  > empty
 ...
  > Of course if you fail to properly initialize an STAILQ, this assumption
  > will fail and the macro will not do the right thing. Do you have a
  > code example that displays a problem with the macros?  From inspection,
  > the macros look correct.
 
 Thank you Justin.  You're entirely correct on all counts.  Since you
 took the trouble to verify queue.h you're at least entitled to a post
 mortem on the problem (if you're interested).  If not interested,
 please accept my thanks again and do feel free to close the PR out...
 
 (prob: as you indicated, failure to initialize.  Not only was
 _INSERT_TAIL called before it was _INITd but so was the state machine
 (implementing the protocol to talk to a GPS board) that called
 _INSERT_TAIL.  It's quite likely the unit'd state machine clobbered
 other program data but in a way that wasn't apparent)
 
State-Changed-From-To: open->closed 
State-Changed-By: gibbs 
State-Changed-When: Wed Nov 17 11:31:48 PST 1999 
State-Changed-Why:  
Originator confirms that the bug was elsewhere in his code. 
>Unformatted:
