Date: Wed, 26 Apr 2023 11:11:23 GMT From: =?utf-8?Q?Dag-Erling=20Sm=C3=B8rgrav?= <des@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 6f3c2f41b18b - main - tzcode: Clean up the ctime(3) manual page. Message-ID: <202304261111.33QBBNcH086356@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by des: URL: https://cgit.FreeBSD.org/src/commit/?id=6f3c2f41b18b9a7a8feb3c50254a21db2d9908fd commit 6f3c2f41b18b9a7a8feb3c50254a21db2d9908fd Author: Dag-Erling Smørgrav <des@FreeBSD.org> AuthorDate: 2023-04-26 09:46:41 +0000 Commit: Dag-Erling Smørgrav <des@FreeBSD.org> CommitDate: 2023-04-26 09:46:41 +0000 tzcode: Clean up the ctime(3) manual page. MFC after: 3 weeks Sponsored by: Klara, Inc. Reviewed by: pauamma_gundo.com Differential Revision: https://reviews.freebsd.org/D39714 --- lib/libc/stdtime/ctime.3 | 191 ++++++++++++++++++++++------------------------- 1 file changed, 89 insertions(+), 102 deletions(-) diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 index b347e5362948..2aaf94f2b12a 100644 --- 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 @@ Thu Nov 24 18:22:48 1986\en\e0 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 @@ A negative value for .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 @@ represented, it returns \-1; .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 @@ long tm_gmtoff; /* offset from UTC in seconds */ .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 @@ and .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 @@ Subsequent calls to these 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202304261111.33QBBNcH086356>