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

@@ -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.

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 extern char *tzname[2];
-.PP
-.B void tzset()
-.PP
-.B #include <sys/types.h>
-.PP
-.B char *ctime(clock)
-.B const time_t *clock;
-.PP
-.B double difftime(time1, time0)
-.B time_t time1;
-.B time_t time0;
-.PP
 .B #include <time.h>
 .PP
-.B char *asctime(tm)
+.B extern char *tzname[2];
-.B const struct tm *tm;
 .PP
-.B struct tm *localtime(clock)
+.B char *ctime(time_t const *clock);
-.B const time_t *clock;
 .PP
-.B struct tm *gmtime(clock)
+.B char *ctime_r(time_t const *clock, char *buf);
-.B const time_t *clock;
 .PP
-.B time_t mktime(tm)
+.B double difftime(time_t time1, time_t time0);
-.B struct tm *tm;
+.PP
+.B char *asctime(struct tm const *tm);
+.PP
+.B "char *asctime_r(struct tm const *restrict tm,"
+.B "    char *restrict result);"
+.PP
+.B struct tm *localtime(time_t const *clock);
+.PP
+.B "struct tm *localtime_r(time_t const *restrict clock,"
+.B "    struct tm *restrict result);"
+.PP
+.B struct tm *gmtime(time_t const *clock);
+.PP
+.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
+can be overwritten by later calls to
-(and by calls to
+.IR tzset .
-.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

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 "size_t strftime(char *restrict buf, size_t maxsize,"
-.B char *buf;
+.B "    char const *restrict format, struct tm const *restrict timeptr);"
-.B size_t maxsize;
-.B const char *format;
-.B const struct tm *timeptr
 .PP
 .B cc ... \-ltz
 .fi

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

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 time2posix(time_t t);
-.B time_t t
 .PP
-.B time_t posix2time(t)
+.B time_t posix2time(time_t t);
-.B time_t t
 .PP
 .B cc ... \*-ltz
 .fi