From owner-cvs-src@FreeBSD.ORG  Tue May 13 03:17:47 2003
Return-Path: <owner-cvs-src@FreeBSD.ORG>
Delivered-To: cvs-src@freebsd.org
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP
	id 4675D37B401; Tue, 13 May 2003 03:17:47 -0700 (PDT)
Received: from mailman.zeta.org.au (mailman.zeta.org.au [203.26.10.16])
	by mx1.FreeBSD.org (Postfix) with ESMTP
	id F053C43FD7; Tue, 13 May 2003 03:17:44 -0700 (PDT)
	(envelope-from bde@zeta.org.au)
Received: from katana.zip.com.au (katana.zip.com.au [61.8.7.246])
	by mailman.zeta.org.au (8.9.3p2/8.8.7) with ESMTP id UAA20556;
	Tue, 13 May 2003 20:17:41 +1000
Date: Tue, 13 May 2003 20:17:40 +1000 (EST)
From: Bruce Evans <bde@zeta.org.au>
X-X-Sender: bde@gamplex.bde.org
To: Doug Barton <dougb@FreeBSD.org>
In-Reply-To: <200305130810.h4D8A5rd086116@repoman.freebsd.org>
Message-ID: <20030513200107.R1096@gamplex.bde.org>
References: <200305130810.h4D8A5rd086116@repoman.freebsd.org>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
cc: cvs-src@FreeBSD.org
cc: src-committers@FreeBSD.org
cc: cvs-all@FreeBSD.org
Subject: Re: cvs commit: src/lib/libc/sys stat.2
X-BeenThere: cvs-src@freebsd.org
X-Mailman-Version: 2.1.1
Precedence: list
List-Id: CVS commit messages for the src tree <cvs-src.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/cvs-src>,
	<mailto:cvs-src-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/cvs-src>
List-Post: <mailto:cvs-src@freebsd.org>
List-Help: <mailto:cvs-src-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/cvs-src>,
	<mailto:cvs-src-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Tue, 13 May 2003 10:17:47 -0000

On Tue, 13 May 2003, Doug Barton wrote:

> dougb       2003/05/13 01:10:05 PDT
>
>   FreeBSD src repository
>
>   Modified files:
>     lib/libc/sys         stat.2
>   Log:
>   * The copy of the stat struct in the man page has rotted, so remove it.
>   Those who really need this information can find it in the include file.

Er, I think standard structs like this are among the few structs that
should be documented in man pages.  The man page still has references
to some of the fields in the struct.  POSIX.1 documents the fields
in detail in its specification of <stat.h> (its specification of stat(2)
just names the required fields).  This is organized like:

    The stat struct shall contain ...
    dev_t   st_dev    Device ID ...
    ...

WHat man pages shouldn't have so much of is a verbatim copy of the header
that gives implementation details like S_IFREG, at least when the
corresponding portable interfaces like S_ISREG() are undocumented.
S_ISREG() has only been standard for 15 years.

Bruce