From nobody Wed Apr 26 11:11:23 2023 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4Q5x5815jKz47qW3; Wed, 26 Apr 2023 11:11:24 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Q5x576tsWz3mqK; Wed, 26 Apr 2023 11:11:23 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1682507484; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=fw9UdGkSlIN+olQH1jwR+hvJfFI3NHrZvkqxxJB9AJg=; b=tmw+0xRRs4/NFWynXKbYDKHrhFIDqO1kMCSiJJ4VrsHvAxPhiPbgHs8q6/SUasBNLVRG7D eWbIak0sjuyi9XRhUyThOlBX6DLz2TGfwShOh1qGL0iOxdzWRtSpZyXX6dK6KBAAKLA0kB TbXzyAXiotkWAqHgIpoSCwHj6BQTqeDhHVrJt8s05vGc515MtoSRXsM6wUs0+NWf4La6oT wWGfxRAvUhOmQI4QBXQ18Q6Mg3R8M7pK1bL4Nj4jDE9NEhgPcDa7XYm3nv1/C9LWyjNgX5 rMThZdjt2tmedKqsHiMo+BXP6mCF4Rk6Y6bqaH68TugHNOeOmpqkcM/1TrXU9A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1682507484; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=fw9UdGkSlIN+olQH1jwR+hvJfFI3NHrZvkqxxJB9AJg=; b=bGyTUiNjtem9joJ5JBu3SSmqx7i8FZOFN/ql7ablWPsYnP1qsmrxgn8jyEzL+EVFmf6NZD D4v0ynlDYlpE7HjEiyccgMG7EYSjBy4cS8Lr/IPnyv63sVQl22R73HSch5Twg95+xXD1/i qB+43biNysbp9BzY/i/iKsDI8sHn+32uiytp5AbZqq0R/PhshhWOHCFnnGstudbZSQWvyw dFKfWtvP0QO4An18HsWKKVKduoIplIjweEDKALZR+ViyWkN42L2LzKYXxMMdxAph8poBTD K2E50lDQJ0lEUK5Kgf2FRJy5wrio0Cz6OTtVc4M/JD5fA36Z06+s/kGhsfFYHA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1682507484; a=rsa-sha256; cv=none; b=IYQ3zgThF98yygGWdTFx2ws9qw7kUqIVJBSKmuMspLnFJxoyWIE49m5CMQGRXh4cOF6F4d EO5sRlLup99dvVHPZKmHC0MNQ0bhcKm+dPLK6943DGd531jHFKULW3F/k4a8yEnvw1ddWW Mg0pp8aKSsEr+UQX0Hm3ijkW/kDuGSiG7g5WWNUjcei/ueK96tkVvQIC+ca3j3VT9mzCRj yQZD6FxwfWTbXGYoJeHlA43eAbb0RVuJBZJ+fylkxCGuYzBDCIijehI/y/7H00KA3SBqws YzmHjvU4X4e1qRXv8UutClgYXwCpefhW8jkhxxqib7AaHITbTsVOl0mC/bONAA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4Q5x5751q3zXLY; Wed, 26 Apr 2023 11:11:23 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 33QBBNa7086357; Wed, 26 Apr 2023 11:11:23 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 33QBBNcH086356; Wed, 26 Apr 2023 11:11:23 GMT (envelope-from git) Date: Wed, 26 Apr 2023 11:11:23 GMT Message-Id: <202304261111.33QBBNcH086356@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: =?utf-8?Q?Dag-Erling=20Sm=C3=B8rgrav?= Subject: git: 6f3c2f41b18b - main - tzcode: Clean up the ctime(3) manual page. List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: des X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 6f3c2f41b18b9a7a8feb3c50254a21db2d9908fd Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by des: URL: https://cgit.FreeBSD.org/src/commit/?id=6f3c2f41b18b9a7a8feb3c50254a21db2d9908fd commit 6f3c2f41b18b9a7a8feb3c50254a21db2d9908fd Author: Dag-Erling Smørgrav AuthorDate: 2023-04-26 09:46:41 +0000 Commit: Dag-Erling Smørgrav 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