From owner-freebsd-arch  Fri Oct 26 11:59:29 2001
Delivered-To: freebsd-arch@freebsd.org
Received: from mailman.zeta.org.au (mailman.zeta.org.au [203.26.10.16])
	by hub.freebsd.org (Postfix) with ESMTP
	id BB7B537B401; Fri, 26 Oct 2001 11:59:22 -0700 (PDT)
Received: from bde.zeta.org.au (bde.zeta.org.au [203.2.228.102])
	by mailman.zeta.org.au (8.9.3/8.8.7) with ESMTP id EAA06213;
	Sat, 27 Oct 2001 04:59:15 +1000
Date: Sat, 27 Oct 2001 04:58:18 +1000 (EST)
From: Bruce Evans <bde@zeta.org.au>
X-X-Sender:  <bde@delplex.bde.org>
To: Dag-Erling Smorgrav <des@ofug.org>
Cc: Ruslan Ermilov <ru@FreeBSD.ORG>, <arch@FreeBSD.ORG>
Subject: Re: "types" man page
In-Reply-To: <xzpsnc7vd9e.fsf@flood.ping.uio.no>
Message-ID: <20011027044359.H88870-100000@delplex.bde.org>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: owner-freebsd-arch@FreeBSD.ORG
Precedence: bulk
List-ID: <freebsd-arch.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%20freebsd-arch>
List-Unsubscribe: <mailto:majordomo@FreeBSD.ORG?subject=unsubscribe%20freebsd-arch>
X-Loop: FreeBSD.ORG

On 25 Oct 2001, Dag-Erling Smorgrav wrote:

> Ruslan Ermilov <ru@FreeBSD.ORG> writes:
> > On Wed, Oct 24, 2001 at 07:52:26PM +0200, Dag-Erling Smorgrav wrote:
> > > Ruslan, do you have a suggestion for the proper mdoc incantations for
> > > a types(7) entry, based on the items I listed in my original mail?
> > Just give me an example entry, and I will mark it up as needed.
>
> pid_t
>    Used to store a process ID.
>    Defined in <machine/ansi.h>.

This is a (wrong) implementation detail.  pid_t is defined in <sys/types.h>
(POSIX.1-1990 standard; perhaps in other places in POSIX.1-200x).
<machine/ansi.h> only defines _BSD_PID_T.  This should probably not be
documented here.

>    Equivalent to a signed int on all platforms.

Another implementation detail.  The standard specification shuld be
given at least as much weight as the implementation details here.

> The man page should also have a section that describes the
> relationships between the various headers (including but probably not
> limited to <machine/ansi.h>, <sys/cdefs.h>, <sys/inttypes.h>,
> <sys/types.h> and <sys/param.h>) that either define these types or

<sys/cdefs.h> is essentially irrelevant for types.

> include other headers which define them.  For instance, most programs
> will want to include <sys/types.h> or <sys/param.h> to define pid_t,
> though <sys/inttypes.h> or <machine/ansi.h> would do.

Neither <sys/inttypes.h> nor <machine/ansi.h> would do.  <sys/param.h>
would only do because of (documented) namespace pollution.  Types are
parameters.

There could be another man page giving relationships between headers.
It would need about 1000 lines just to list prerequisites for each
userland header.

Bruce


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