* NEWS, newctime.3, newstrftime.3, newtzset.3, time2posix.3: Mention localtime_r etc. Also, use function prototypes rather than K&R style, and use 'restrict' where POSIX does. --- NEWS | 3 +++ newctime.3 | 62 ++++++++++++++++++++++++++++++++++++++--------------------- newstrftime.3 | 8 ++------ newtzset.3 | 4 +++- time2posix.3 | 7 ++----- 5 files changed, 50 insertions(+), 34 deletions(-) diff --git a/NEWS b/NEWS index 7bc8b05..0d31a1f 100644 --- a/NEWS +++ b/NEWS @@ -85,6 +85,9 @@ Unreleased, experimental changes A new file CONTRIBUTING is distributed. (Thanks to Tim Parenti for suggesting a CONTRIBUTING file, and to Walter Harms for debugging it.) + The man pages have been updated to use function prototypes, and + to document thread-safe variants like localtime_r. + The fields in Link lines have been renamed to be more descriptive and more like the parameters of 'ln'. LINK-FROM has become TARGET, and LINK-TO has become LINK-NAME. diff --git a/newctime.3 b/newctime.3 index e9090d5..accefa5 100644 --- a/newctime.3 +++ b/newctime.3 @@ -5,32 +5,32 @@ asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time .nf .ie \n(.g .ds - \f(CW-\fP .el ds - \- +.B #include <time.h> +.PP .B extern char *tzname[2]; .PP -.B void tzset() +.B char *ctime(time_t const *clock); .PP -.B #include <sys/types.h> +.B char *ctime_r(time_t const *clock, char *buf); .PP -.B char *ctime(clock) -.B const time_t *clock; +.B double difftime(time_t time1, time_t time0); .PP -.B double difftime(time1, time0) -.B time_t time1; -.B time_t time0; +.B char *asctime(struct tm const *tm); .PP -.B #include <time.h> +.B "char *asctime_r(struct tm const *restrict tm," +.B " char *restrict result);" .PP -.B char *asctime(tm) -.B const struct tm *tm; +.B struct tm *localtime(time_t const *clock); .PP -.B struct tm *localtime(clock) -.B const time_t *clock; +.B "struct tm *localtime_r(time_t const *restrict clock," +.B " struct tm *restrict result);" .PP -.B struct tm *gmtime(clock) -.B const time_t *clock; +.B struct tm *gmtime(time_t const *clock); .PP -.B time_t mktime(tm) -.B struct tm *tm; +.B "struct tm *gmtime_r(time_t const *restrict clock," +.B " struct tm *restrict result);" +.PP +.B time_t mktime(struct tm *tm); .PP .B cc ... \*-ltz .fi @@ -110,6 +110,14 @@ structure to a string, as shown in the above example, and returns a pointer to the string. .PP +.IR Ctime_r , +.IR localtime_r , +.IR gmtime_r , +and +.I asctime_r +are like their unsuffixed counterparts, except that they accept an +additional argument specifying where to store the result if successful. +.PP .I Mktime converts the broken-down time, expressed as local time, @@ -234,25 +242,35 @@ newtzset(3), time(2), tzfile(5) .SH NOTES -The return values point to static data +The return values of +.IR asctime , +.IR ctime , +.IR gmtime , +and +.I localtime +point to static data overwritten by each call. The .B tm_zone field of a returned .B "struct tm" points to a static array of characters, which -will also be overwritten at the next call -(and by calls to -.IR tzset ). +can be overwritten by later calls to +.IR tzset . +The remaining functions and data are thread-safe. .PP -.I Asctime +.IR Asctime , +.IR asctime_r , +.IR ctime , and -.I ctime +.I ctime_r behave strangely for years before 1000 or after 9999. The 1989 and 1999 editions of the C Standard say that years from \-99 through 999 are converted without extra spaces, but this conflicts with longstanding tradition and with this implementation. +The 2011 edition says that the behavior +is undefined if the year is before 1000 or after 9999. Traditional implementations of these two functions are restricted to years in the range 1900 through 2099. To avoid this portability mess, new programs should use diff --git a/newstrftime.3 b/newstrftime.3 index 7dd125c..6afc948 100644 --- a/newstrftime.3 +++ b/newstrftime.3 @@ -44,14 +44,10 @@ strftime \- format date and time .nf .ie \n(.g .ds - \f(CW-\fP .el ds - \- -.B #include <sys/types.h> .B #include <time.h> .PP -.B size_t strftime(buf, maxsize, format, timeptr) -.B char *buf; -.B size_t maxsize; -.B const char *format; -.B const struct tm *timeptr +.B "size_t strftime(char *restrict buf, size_t maxsize," +.B " char const *restrict format, struct tm const *restrict timeptr);" .PP .B cc ... \-ltz .fi diff --git a/newtzset.3 b/newtzset.3 index 46410bb..51c4197 100644 --- a/newtzset.3 +++ b/newtzset.3 @@ -5,7 +5,9 @@ tzset \- initialize time conversion information .nf .ie \n(.g .ds - \f(CW-\fP .el ds - \- -.B void tzset() +.B #include <time.h> +.PP +.B void tzset(void); .PP .B cc ... \*-ltz .fi diff --git a/time2posix.3 b/time2posix.3 index 75d8097..e4b8e81 100644 --- a/time2posix.3 +++ b/time2posix.3 @@ -5,14 +5,11 @@ time2posix, posix2time \- convert seconds since the Epoch .nf .ie \n(.g .ds - \f(CW-\fP .el ds - \- -.B #include <sys/types.h> .B #include <time.h> .PP -.B time_t time2posix(t) -.B time_t t +.B time_t time2posix(time_t t); .PP -.B time_t posix2time(t) -.B time_t t +.B time_t posix2time(time_t t); .PP .B cc ... \*-ltz .fi -- 1.9.1