[PROPOSED PATCH 1/4] Document thread-safe functions in man pages.
* 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
This is for compatibility with POSIX. --- private.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/private.h b/private.h index 529b1dc..14a9d53 100644 --- a/private.h +++ b/private.h @@ -308,7 +308,7 @@ time_t time(time_t *); */ #ifndef asctime_r -extern char * asctime_r(struct tm const *, char *); +extern char * asctime_r(struct tm const *restrict, char *restrict); #endif /* -- 1.9.1
(gmtcheck): Lock only if !gmt_is_set. (gmtime_r, offtime, timeoff): Do not lock; gmtcheck now does this. --- localtime.c | 22 +++------------------- 1 file changed, 3 insertions(+), 19 deletions(-) diff --git a/localtime.c b/localtime.c index 67b1d78..8260625 100644 --- a/localtime.c +++ b/localtime.c @@ -1244,12 +1244,15 @@ gmtcheck(void) { if (gmt_is_set) return; + if (lock() != 0) + return; #ifdef ALL_STATE gmtptr = malloc(sizeof *gmtptr); #endif if (gmtptr) gmtload(gmtptr); gmt_is_set = true; + unlock(); } /* @@ -1404,14 +1407,8 @@ gmtime(const time_t *const timep) struct tm * gmtime_r(const time_t *const timep, struct tm *tmp) { - int err = lock(); - if (err) { - errno = err; - return NULL; - } gmtcheck(); tmp = gmtsub(timep, 0, tmp); - unlock(); return tmp; } @@ -1421,14 +1418,8 @@ struct tm * offtime(const time_t *const timep, const long offset) { struct tm *tmp; - int err = lock(); - if (err) { - errno = err; - return NULL; - } gmtcheck(); tmp = gmtsub(timep, offset, &tm); - unlock(); return tmp; } @@ -1996,17 +1987,10 @@ time_t timeoff(struct tm *const tmp, const long offset) { time_t t; - int err; if (tmp) tmp->tm_isdst = 0; - err = lock(); - if (err) { - errno = err; - return -1; - } gmtcheck(); t = time1(tmp, gmtsub, offset); - unlock(); return t; } -- 1.9.1
The Mach project has been inactive for decades, and mktime has evidently replaced gtime. * Makefile: Remove comment about CMUCS. * localtime.c (gtime) [CMUCS]: Remove. * NEWS: Document the above. --- Makefile | 5 ----- NEWS | 2 ++ localtime.c | 19 ------------------- 3 files changed, 2 insertions(+), 24 deletions(-) diff --git a/Makefile b/Makefile index d36bc43..99d2826 100644 --- a/Makefile +++ b/Makefile @@ -199,11 +199,6 @@ GCC_DEBUG_FLAGS = -Dlint -g3 -O3 -fno-common -fstrict-aliasing \ # to the end of the "CFLAGS=" line. # This variable is not described in X3J11's work. # -# If you want a "gtime" function (a la MACH), add -# -DCMUCS -# to the end of the "CFLAGS=" line -# This function is not described in X3J11's work. -# # NIST-PCTS:151-2, Version 1.4, (1993-12-03) is a test suite put # out by the National Institute of Standards and Technology # which claims to test C and Posix conformance. If you want to pass PCTS, add diff --git a/NEWS b/NEWS index 0d31a1f..7f15887 100644 --- a/NEWS +++ b/NEWS @@ -69,6 +69,8 @@ Unreleased, experimental changes For easier maintenance later, some C code has been simplified and some lint has been removed. + The long-obsolete 'gtime' function has been removed. + Changes affecting distribution tarballs The files checktab.awk and zoneinfo2tdf.pl are now distributed in diff --git a/localtime.c b/localtime.c index 8260625..0d30453 100644 --- a/localtime.c +++ b/localtime.c @@ -1996,25 +1996,6 @@ timeoff(struct tm *const tmp, const long offset) #endif /* defined STD_INSPIRED */ -#ifdef CMUCS - -/* -** The following is supplied for compatibility with -** previous versions of the CMUCS runtime library. -*/ - -long -gtime(struct tm *const tmp) -{ - const time_t t = mktime(tmp); - - if (t == WRONG) - return -1; - return t; -} - -#endif /* defined CMUCS */ - /* ** XXX--is the below the right way to conditionalize?? */ -- 1.9.1
participants (1)
-
Paul Eggert