I’ve been gifted with a lot of help on my draft of Time, Clock, and Calendar Programming In C. I think it’s almost time to ship 1.0, and plan to do so this weekend. Get your last-minute fixes in now!
I will of course continue to accept corrections and additions after 1.0. Thanks to everyone who contributed. My blog and G+ followers were very diligent in spotting typos, helping fill in and correct standards history, and pointing out the more obscure gotchas in the API.
What I’ve discovered is that the Unix calendar-related API is a pretty wretched shambles. Which leads directly to the topic of my next blog entry…
I’d like to repeat the complaint that function declarations lack (meaningful) parameter names, for example the document uses ‘char *ctime_r(const time_t *, char *);’ and ‘struct tm *gmtime_r(const time_t *, struct tm *);’ instead of ‘char *ctime_r(const time_t *timep, char *buf);’ and ‘struct tm *gmtime_r(const time_t *timep, struct tm *result);’.
Also, couldn’t you use better names that the ones in ‘int nanosleep(const struct timespec *rqtp, struct timespec *rmtp);’? rqtp and rmtp – WTF?
>Also, couldn’t you use better names that the ones in ‘int nanosleep(const struct timespec *rqtp, struct timespec *rmtp);’? rqtp and rmtp – WTF?
Which neatly illustrates why I’m removing all the parameter names rather than trying to add “meaningful” ones. Then I’d have to explain the meaningful ones. Out of scope: that’s what manual pages are for.
There is formatting error in second paragraph of “Timezone selection and representation on Unix” section. The second to last paragraph in said section has embedded rather than linked footnote (another formatting error).
Perhaps it would be worth mentioning that old timezone names like EST and EDT are not ambiguous, in both directions: there are different timezone with the same abbreviation, and there are different abbreviations for the same timezone.
Probably it is not worth repeating the information in other sources about “Europe/Vienna” naming: they name regions with the same time since 1970, naming was chosen to be independent from country names (which change), it uses ‘_’ in place of space with the few exceptions, and it uses English to be international.
“Unix date formats”
Note that ISO-8601 can include nanoseconds and timezone in the following format:
$ date –iso-8601=ns
2014-10-03T16:29:10,602730144+0200
The date(1) command extends RFC-3339 with timezone in slightly different format;
$ date –rfc-3339=ns
2014-10-03 16:29:30.270412822+02:00
Perhaps the “HTTP-date” format, defined by RFC 7231, could be mentioned – there is subtle difference between it and RFC-822/RFC-2822 in that one uses leading zero and one doesn’t.
>2014-10-03T16:29:10,602730144+0200
Does ISO-8601 really mandate that perverse decimal comma?
@Jakub Narebski: The HTTP-date format also requires UTC time, while RFC-[2]822 permits and recommends local time with time zone.
It might be worth noting that Windows is no better in time handling.
> Which neatly illustrates why I’m removing all the parameter names rather than trying to add “meaningful” ones. Then I’d have to explain the meaningful ones. Out of scope: that’s what manual pages are for.
There are some cases where it is obvious what parameters are. There are cases where manpages has non-explaining names of parameters. And there are cases where it is hard to understand the API without parameter names, like in the case of strftime().
And you didn’t remove parameter names everywhere… I’d rather you add parameter names (perhaps copying from manpages); it helps even without explanation.
>> 2014-10-03T16:29:10,602730144+0200
> Does ISO-8601 really mandate that perverse decimal comma?
This might be locale-dependent… or date (GNU coreutils) 8.21 has a bug that makes the `date –iso-8601=ns` output locale dependent (LANG=pl_PL.UTF-8).
ISO 8601 defines a large variety of formats, I wouldn’t be surprised if it permits either, particularly since I can’t think of any format with a need for either character in any other meaning.
> Does ISO-8601 really mandate that perverse decimal comma?
Sadly, it seems it does. From Wikipedia:
> A decimal mark, either a comma or a dot (without any preference as stated in resolution 10 of the 22nd General Conference CGPM in 2003,[18] but with a preference for a comma according to ISO 8601:2004)[19] is used as a separator between the time element and its fraction.
Nice document. I’ve fought with the time tools myself.
The document might benefit from a REFERENCE or SUMMARY section listing only those functions that are safe to use, along with one-liner hints.
Please keep the meaningful parameter names. They help with the understanding of the document you are writing. For you to say “that’s what the man pages are for” makes me want to cry. Why spend the time you did, all of the proof readers time, etc. to punt back “read the man page”?
Thanks!