git: 662dc74155ad - stable/13 - tzcode: Clean up the ctime(3) manual page.
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Thu, 04 Apr 2024 11:39:02 UTC
The branch stable/13 has been updated by des: URL: https://cgit.FreeBSD.org/src/commit/?id=662dc74155ada993513a08190032710cf224e47f commit 662dc74155ada993513a08190032710cf224e47f 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: 2024-04-04 09:51:02 +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 (cherry picked from commit 6f3c2f41b18b9a7a8feb3c50254a21db2d9908fd) libc: Improve description of mktime() / timegm(). * Mention that mktime() and timegm() set errno on failure. * Correctly determining whether mktime() / timegm() succeeded with arbitrary input (where -1 can be a valid result) is non-trivial. Document the recommended procedure. PR: 277863 MFC after: 1 week Reviewed by: pauamma_gundo.com, gbe Differential Revision: https://reviews.freebsd.org/D44503 (cherry picked from commit 7534109d13a6cdb22e78d9d4c0a0cd5efd323c45) --- lib/libc/stdtime/ctime.3 | 207 ++++++++++++++++++++++++----------------------- 1 file changed, 104 insertions(+), 103 deletions(-) diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 index 0f649e4d99ab..579b14ada552 100644 --- a/lib/libc/stdtime/ctime.3 +++ b/lib/libc/stdtime/ctime.3 @@ -29,7 +29,7 @@ .\" .\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93 .\" -.Dd September 16, 2022 +.Dd March 26, 2024 .Dt CTIME 3 .Os .Sh NAME @@ -51,81 +51,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 @@ -140,65 +137,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 @@ -227,7 +217,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 @@ -253,21 +243,37 @@ The .Fn mktime function returns the specified calendar time; if the calendar time cannot be -represented, it returns \-1; +represented, it returns \-1 and sets +.Xr errno 3 +to an appropriate value. +.Pp +Note that \-1 is a valid result (representing one second before +midnight UTC on the evening of 31 December 1969), so this cannot be +relied upon to indicate success or failure; instead, +.Fa tm_wday +and / or +.Fa tm_yday +should be set to an out-of-bounds value (e.g. \-1) prior to calling +.Fn mktime +or +.Fn timegm +and checked after the call. .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) */ @@ -283,16 +289,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 , @@ -358,13 +362,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 @@ -379,13 +383,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