Re: Don't document the types of standard typedefs

[Paul Eggert <eggert at cs dot ucla dot edu>]

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.

>  @cindex inode number
> @@ -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.

nlink_t is similar, except there's no guarantee that it's
no narrower than 'int'.