[RFC v6] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval

[Alejandro Colomar]

Hi Thorsten,

 >> POSIX does more or less the same:
 >> It has a ¿main? header where the type is defined
 >
 > It does?

It doesn't explicitly say so (AFACS; I didn't read the standard so deep).

But it hints so.

 > When I look at one of the headers, for example…
 > https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_time.h.html
 > … I see a number of types being defined, but the types don’t have
 > their own pages nor is described which is the “main” header (the same
 > goes for constants, e.g. NULL is defined by several headers).
 >
 > Or is wording like…
 >
 >      The <stdlib.h> header shall define NULL as described in 
[10]<stddef.h>.

Yes, the POSIX standard defines types (and in general everything) in
one header.  And then other headers refer the definition to that header,
with that wording you extracted.

The C standard does more or less the same thing:

Extracts from C18:

§ 6.5.3.3 (5)
"The value of the result of both operators is implementation-defined,
and its type (an unsignedinteger type) is size_t, defined
in <stddef.h> (and other headers)."

§ 7.19
"  Common definitions <stddef.h>
The header <stddef.h> defines the following macros and declares the
following types. Some are also defined in other headers, as noted in
their respective subclauses.

The types are
[...]
size_t
which is the unsigned integer type of the result of the sizeof operator;
[...]
"

§ 7.21
"  Input/output <stdio.h>
Introduction
The header <stdio.h> defines several macros, and declares three types
and many functions for performing input and output.
The types declared are size_t (described in 7.19);
[...]
"


 > … where you get the notion of a “main header” from?
 > If so, where in the standard is this expectation documented?

It's not that the standards document it, but in practice it is so.

The main point of differentiating those headers from the rest would be:

- It is likely that it's the lightest header you need to get that type
   (usually most types are in <stddef.h> or <sys/types.h> or <sys/time.h>
   or <stdint.h>, which are very light headers, and the rest of the
   headers just need the types the many function prototypes, which
   you don't need).

- If one wants to find the actual documentation for a type, it's easier
   if you know which header you should look at, although I have to admit
   that if you see any of the other headers, it clearly redirects you,
   so not very important.

- If you just include any of the headers in the list for just getting
   one type (e.g., you included <monetary.h> to get 'ssize_t'),
   a reader of the code might spend a few minutes wondering why the hell
   is that header included.  It's ok if you need monetary for something
   else, and you also happen to need 'ssize_t' and omit <sys/types.h>
   because you happen to have the definition already, but including that
   header just for 'ssize_t' would be a shooting offense, IMO.


Thanks,

Alex