This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: Don't document the types of standard typedefs
On Sun, 26 Feb 2012, Paul Eggert wrote:
> On 02/26/2012 04:31 PM, Joseph S. Myers wrote:
>
> > @deftp {Data Type} mode_t
> > -This is an integer data type used to represent file modes. In the
> > -GNU system, this is equivalent to @code{unsigned int}.
> > +This is an integer data type used to represent file modes.
> > @end deftp
>
> It's helpful for application writers to know that on GNU systems
> mode_t is no narrower than int (so that the usual stdarg code works with
> mode_t values), and it might be helpful to know that mode_t is unsigned
> (so that app writers need not worry about undefined behavior
> shifting mode_t values). So I suggest saying that on GNU systems,
> mode_t is an unsigned type no narrower than unsigned int.
Is this saying that any system on which mode_t does not have those
properties would never be considered a GNU system (as per
<http://sourceware.org/ml/libc-alpha/2012-02/msg00454.html>)? Or should
we actually say that, whatever the underlying kernel interface, the GNU C
Library will provide an interface to applications with those properties
(various types on GNU/Linux were deliberately made wider than in the
kernel, for future-proofing)? That is, "In the GNU C Library, this is an
unsigned type no narrower than @code{unsigned int}.".
> > @@ -1780,7 +1779,6 @@ GNU system, this is equivalent to @code{unsigned int}.
> > @deftp {Data Type} ino_t
> > This is an arithmetic data type used to represent file serial numbers.
> > (In Unix jargon, these are sometimes called @dfn{inode numbers}.)
> > -In the GNU system, this type is equivalent to @code{unsigned long int}.
>
> It's helpful in the GNU system to know that ino_t is an integer
> type (as opposed to a floating point type) and that it is no
> narrower than 'int'. Similarly for ino64_t, dev_t, blkcnt_t,
> blkcnt64_t, off_t, off64_t. Also, when it's known whether the
> integer type is signed (e.g., with off_t) on a GNU system, it's
> useful for that to be stated.
Same question about whether this is something about GNU systems or
something the GNU C Library will provide on all systems.
POSIX says ino_t is "Unsigned integer type used for file serial numbers."
and off_t is "Signed integer type used for file sizes." so I think we can
make those assertions (if not those about relations to "int")
unconditionally.
FWIW there are other places in the manual that *do* describe types in
terms of what they are in glibc rather than "GNU system": uid_t, gid_t,
pid_t.
--
Joseph S. Myers
joseph@codesourcery.com