* newctime.3: Reorder so that functions are described in a more sensible order, e.g., asctime is explained first and ctime merely defers to it. Also put asctime and ctime later since they are deprecated. Mention that localtime and gmtime return a null pointer on failure. --- newctime.3 | 148 +++++++++++++++++++++++++---------------------------- 1 file changed, 71 insertions(+), 77 deletions(-) diff --git a/newctime.3 b/newctime.3 index 5e1b6148..9d09e5a5 100644 --- a/newctime.3 +++ b/newctime.3 @@ -7,38 +7,31 @@ asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time .nf .B #include <time.h> .PP -.B [[deprecated]] char *ctime(time_t const *clock); -.PP -/* Only in POSIX.1-2017 and earlier. */ -.B char *ctime_r(time_t const *clock, char *buf); -.PP -.B double difftime(time_t time1, time_t time0); -.PP -.B [[deprecated]] char *asctime(struct tm const *tm); -.PP -/* Only in POSIX.1-2017 and earlier. */ -.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 *localtime_rz(timezone_t restrict zone," .B " 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 "time_t mktime_z(timezone_t restrict zone," .B " struct tm *restrict tm);" .PP +.B double difftime(time_t time1, time_t time0); +.PP +.B [[deprecated]] char *asctime(struct tm const *tm); +.B [[deprecated]] char *ctime(time_t const *clock); +.PP +/* Only in POSIX.1-2017 and earlier. */ +.B char *ctime_r(time_t const *clock, char *buf); +.B "char *asctime_r(struct tm const *restrict tm," +.B " char *restrict result);" +.PP .B cc ... \-ltz .fi .SH DESCRIPTION @@ -52,82 +45,37 @@ asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time \\$3\*(lq\\$1\*(rq\\$2 .. The -.B ctime -function -converts a long integer, pointed to by -.IR clock , -and returns a pointer to a -string of the form -.br -.ce -.eo -Thu Nov 24 18:22:48 1986\n\0 -.br -.ec -Years requiring fewer than four characters are padded with leading zeroes. -For years longer than four characters, the string is of the form -.br -.ce -.eo -Thu Nov 24 18:22:48 81986\n\0 -.ec -.br -with five spaces before the year. -These unusual formats are designed to make it less likely that older -software that expects exactly 26 bytes of output will mistakenly output -misleading values for out-of-range years. -.PP -The -.BI * clock -timestamp represents the time in seconds since 1970-01-01 00:00:00 -Coordinated Universal Time (UTC). -The POSIX standard says that timestamps must be nonnegative -and must ignore leap seconds. -Many implementations extend POSIX by allowing negative timestamps, -and can therefore represent timestamps that predate the -introduction of UTC and are some other flavor of Universal Time (UT). -Some implementations support leap seconds, in contradiction to POSIX. -.PP -The -.B ctime -function is deprecated starting in C23. -Callers can use -.B localtime_r -and -.B strftime -instead. -.PP -The .B localtime and .B gmtime functions +convert an integer, pointed to by +.IR clock , +and return pointers to .q "tm" structures, described below. +If the integer is out of range for conversion, +these functions return a null pointer. The .B localtime function corrects for the time zone and any time zone adjustments (such as Daylight Saving Time in the United States). -.PP The .B gmtime -function -converts to Coordinated Universal Time. +function converts to Coordinated Universal Time. .PP The -.B asctime -function -converts a time value contained in a -.q "tm" -structure to a string, -as shown in the above example, -and returns a pointer to the string. -This function is deprecated starting in C23. -Callers can use -.B strftime -instead. +.BI * clock +timestamp represents the time in seconds since 1970-01-01 00:00:00 +Coordinated Universal Time (UTC). +The POSIX standard says that timestamps must be nonnegative +and must ignore leap seconds. +Many implementations extend POSIX by allowing negative timestamps, +and can therefore represent timestamps that predate the +introduction of UTC and are some other flavor of Universal Time (UT). +Some implementations support leap seconds, in contradiction to POSIX. .PP The .B mktime @@ -202,6 +150,52 @@ returns the difference between two calendar times, expressed in seconds. .PP The +.B asctime +function +converts a time value contained in a +.q "tm" +structure to a pointer to a +string of the form +.br +.ce +.eo +Thu Nov 24 18:22:48 1986\n\0 +.br +.ec +Years requiring fewer than four characters are padded with leading zeroes. +For years longer than four characters, the string is of the form +.br +.ce +.eo +Thu Nov 24 18:22:48 81986\n\0 +.ec +.br +with five spaces before the year. +This unusual format is designed to make it less likely that older +software that expects exactly 26 bytes of output will mistakenly output +misleading values for out-of-range years. +This function is deprecated starting in C23. +Callers can use +.B strftime +instead. +.PP +The +.B ctime +function is equivalent to calliing +.B localtime +and then calling +.B asctime +on the result. +Like +.BR asctime , +this function is deprecated starting in C23. +Callers can use +.B localtime +and +.B strftime +instead. +.PP +The .BR ctime_r , .BR localtime_r , .BR gmtime_r , -- 2.47.1