Fifth draft of the Y2038 design document

[Paul Eggert]

A few comments:

The spec should clearly state at the start whether it's about the API, 
or the ABI, or both. Although it appears to be about the API, a lot of 
ABI concerns are leaking in. If the spec is about both API and ABI, the 
distinction should be kept clear throught the document.

The API spec should address only symbols that are part of the API. For 
example, it should say "pid_t", not "__pid_t", as user code shouldn't 
know about or use __pid_t. You should go through every 
leading-underscore symbol in the API spec and decide whether it really 
needs to be there (as in _TIME_BITS) or should be rewritten (as in __pid_t).

In the current spec, if _TIME_BITS is not defined the implementation 
must behave as if _TIME_BITS==32. This is not future-proof, and will be 
a bad default in the not-too-distant future. Instead, the spec should 
say that the default value of _TIME_BITS is implementation-defined. This 
will let current implementations default _TIME_BITS to 32 now (for 
backward compatibility to older platforms) while letting future 
implementations default to 64 (when 32 will make no sense).

Some function prototypes have identifiers in the argument names; others 
don't. Please be consistent and either avoid them everywhere or use them 
everywhere.

I don't get the point about "a possible implementation" for struct 
timespec on little-endian vs struct timespec64 on big-endian systems. 
The implementations are identical.

I don't understand the table labeled "Internal changes" with entries 
like "main(int, char **)" and "xcalloc(int, int)". What do these entries 
have to do with time? Which "main" and "xcalloc" are we talking about?

Misspellings: "linux" (should be "Linux"), "adde", "whould", 
"implementaters", "implementors", "tyime", "clocksettime", 
"Concersively". Please run a spelling check on it just before the next 
review.