diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 --- a/lib/libc/stdtime/ctime.3 +++ b/lib/libc/stdtime/ctime.3 @@ -30,7 +30,7 @@ .\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd March 6, 2023 +.Dd April 20, 2023 .Dt CTIME 3 .Os .Sh NAME @@ -52,81 +52,78 @@ .In time.h .Vt extern char *tzname[2] ; .Ft char * +.Fn asctime "const struct tm *tm" +.Ft char * +.Fn asctime_r "const struct tm *tm" "char *buf" +.Ft char * .Fn ctime "const time_t *clock" +.Ft char * +.Fn ctime_r "const time_t *clock" "char *buf" .Ft double .Fn difftime "time_t time1" "time_t time0" -.Ft char * -.Fn asctime "const struct tm *tm" +.Ft struct tm * +.Fn gmtime "const time_t *clock" +.Ft struct tm * +.Fn gmtime_r "const time_t *clock" "struct tm *result" .Ft struct tm * .Fn localtime "const time_t *clock" .Ft struct tm * -.Fn gmtime "const time_t *clock" +.Fn localtime_r "const time_t *clock" "struct tm *result" .Ft time_t .Fn mktime "struct tm *tm" .Ft time_t .Fn timegm "struct tm *tm" -.Ft char * -.Fn ctime_r "const time_t *clock" "char *buf" -.Ft struct tm * -.Fn localtime_r "const time_t *clock" "struct tm *result" -.Ft struct tm * -.Fn gmtime_r "const time_t *clock" "struct tm *result" -.Ft char * -.Fn asctime_r "const struct tm *tm" "char *buf" .Sh DESCRIPTION -The functions +The .Fn ctime , -.Fn gmtime +.Fn gmtime , and .Fn localtime -all take as an argument a time value representing the time in seconds since -the Epoch (00:00:00 -.Tn UTC , -January 1, 1970; see +functions all take as argument a pointer to a time value representing +the time in seconds since the Epoch (00:00:00 UTC on January 1, 1970; +see .Xr time 3 ) . .Pp -The function +The .Fn localtime -converts the time value pointed at by +function converts the time value pointed to by .Fa clock , and returns a pointer to a -.Dq Fa struct tm +.Vt struct tm (described below) which contains the broken-out time information for the value after adjusting for the current -time zone (and any other factors such as Daylight Saving Time). +time zone (see +.Xr tzset 3 ) . When the specified time translates to a year that will not fit in an -.Dv int , +.Vt int , .Fn localtime -returns NULL. -Time zone adjustments are performed as specified by the -.Ev TZ -environment variable (see -.Xr tzset 3 ) . -The function +returns +.Dv NULL . +The .Fn localtime -uses +function uses .Xr tzset 3 to initialize time conversion information if .Xr tzset 3 has not already been called by the process. .Pp -After filling in the tm structure, +After filling in the +.Vt struct tm , .Fn localtime sets the -.Fa tm_isdst Ns 'th +.Va tm_isdst Ns 'th element of -.Fa tzname -to a pointer to an -.Tn ASCII -string that is the time zone abbreviation to be +.Va tzname +to a pointer to an ASCII string that is the time zone abbreviation to be used with .Fn localtime Ns 's return value. .Pp -The function +The .Fn gmtime -similarly converts the time value, but without any time zone adjustment, -and returns a pointer to a tm structure (described below). +function similarly converts the time value, but without any time zone +adjustment, and returns a pointer to a +.Vt struct tm . .Pp The .Fn ctime @@ -141,65 +138,58 @@ All the fields have constant width. .Pp The +.Fn asctime +function converts the broken down time in the +.Vt struct tm +pointed to by +.Fa tm +to the form shown in the example above. +.Pp +The .Fn ctime_r -function -provides the same functionality as +and +.Fn asctime_r +functions +provide the same functionality as .Fn ctime +and +.Fn asctime except the caller must provide the output buffer -.Fa buf -to store the result, which must be at least 26 characters long. +.Fa buf , +which must be at least 26 characters long, to store the result in. The .Fn localtime_r and .Fn gmtime_r -functions -provide the same functionality as +functions provide the same functionality as .Fn localtime and .Fn gmtime respectively, except the caller must provide the output buffer .Fa result . .Pp -The -.Fn asctime -function -converts the broken down time in the structure -.Fa tm -pointed at by -.Fa *tm -to the form -shown in the example above. -.Pp -The -.Fn asctime_r -function -provides the same functionality as -.Fn asctime -except the caller provide the output buffer -.Fa buf -to store the result, which must be at least 26 characters long. -.Pp The functions .Fn mktime and .Fn timegm -convert the broken-down time in the structure -pointed to by tm into a time value with the same encoding as that of the -values returned by the +convert the broken-down time in the +.Vt struct tm +pointed to by +.Fa tm +into a time value with the same encoding as that of the values +returned by the .Xr time 3 -function (that is, seconds from the Epoch, -.Tn UTC ) . +function (that is, seconds from the Epoch, UTC). The .Fn mktime -function -interprets the input structure according to the current timezone setting -(see -.Xr tzset 3 ) . -The +function interprets the input structure according to the current +timezone setting (see +.Xr tzset 3 ) +while the .Fn timegm -function -interprets the input structure as representing Universal Coordinated Time -.Pq Tn UTC . +function interprets the input structure as representing Universal +Coordinated Time +.Pq UTC . .Pp The original values of the .Fa tm_wday @@ -228,7 +218,7 @@ .Fa tm_isdst causes the .Fn mktime -function to attempt to divine whether summer time is in effect for the +function to attempt to guess whether summer time is in effect for the specified time. The .Fa tm_isdst @@ -258,17 +248,19 @@ .Pp The .Fn difftime -function -returns the difference between two calendar times, -.Pf ( Fa time1 -- -.Fa time0 ) , -expressed in seconds. +function returns the difference in seconds between two time values, +.Fa time1 +\- +.Fa time0 . .Pp -External declarations as well as the tm structure definition are in the +External declarations as well as the definition of +.Vt struct tm +are in the .In time.h -include file. -The tm structure includes at least the following fields: +header. +The +.Vt tm +structure includes at least the following fields: .Bd -literal -offset indent int tm_sec; /* seconds (0 - 60) */ int tm_min; /* minutes (0 - 59) */ @@ -284,16 +276,14 @@ .Ed .Pp The -field .Fa tm_isdst -is non-zero if summer time is in effect. +field is non-zero if summer time is in effect. .Pp -The field +The .Fa tm_gmtoff -is the offset (in seconds) of the time represented from -.Tn UTC , -with positive -values indicating east of the Prime Meridian. +field is the offset in seconds of the time represented from UTC, +with positive values indicating a time zone ahead of UTC (east of the +Prime Meridian). .Sh SEE ALSO .Xr date 1 , .Xr clock_gettime 2 , @@ -359,13 +349,13 @@ .Fn timelocal in SunOS 4.0. .Pp -The functions +The .Fn asctime_r , .Fn ctime_r , -.Fn gmtime_r , +.Fn gmtime_r and .Fn localtime_r -have been available since +functions have been available since .Fx 8.0 . .Sh BUGS Except for @@ -380,13 +370,10 @@ function will modify the same object. .Pp The C Standard provides no mechanism for a program to modify its current -local timezone setting, and the -.Tn POSIX Ns No \&-standard +local timezone setting, and the POSIX-standard method is not reentrant. (However, thread-safe implementations are provided -in the -.Tn POSIX -threaded environment.) +in the POSIX threaded environment.) .Pp The .Va tm_zone