From nobody Tue Mar 29 08:12:15 2022 X-Original-To: dev-commits-src-main@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 2862A1A4126E; Tue, 29 Mar 2022 09:12:22 +0000 (UTC) (envelope-from mpp302@gmail.com) Received: from mail-ed1-f49.google.com (mail-ed1-f49.google.com [209.85.208.49]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1D4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4KSP391Sfwz3kp8; Tue, 29 Mar 2022 09:12:21 +0000 (UTC) (envelope-from mpp302@gmail.com) Received: by mail-ed1-f49.google.com with SMTP id c62so19914967edf.5; Tue, 29 Mar 2022 02:12:21 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:date:mime-version:user-agent :content-language:to:references:from:subject:in-reply-to :content-transfer-encoding; bh=izpelxN3vNFGSGSqesIkTwEix54OrljhBMnLZbQ9F4A=; b=G0fiH6RKLo6B+kenpAiGjF1jmblGIact6D+Ur8BSfi8QTOF1JdDStA9tDr6FI4UZL0 s3aXyo2Y48vJsgjEob5DTcGulyuEFqi1BchpnXlyfzX4/1+zn4crMhdNih1wM1CmVTrX Xsxzj36nyMXhwOliMxBjDR33X19k9eVHyOntbnAVMHz4ig9+Dl1QAtuuKjHz6y9hgjAy Si+tcIs98dQpTwhmFBiVEKRxwTTQ4ATMlDjZHnbqq7lD8at80I5ZRXZNj4Q9cQSGNO3Y U06O+aasWOIOYIWINi/fSUvCkgN0XhfzNZ4Nkp+rRiJpZWGJVCsjpqMBSy14+Eo5Iwkn t3qw== X-Gm-Message-State: AOAM532sBZLBW39a3kw0vatRtZxdfdyQ5IAlTs5EuHX5AhNcRuYNFJau iJvY/ocv6ypUTp/Cy51HDd8khlqBv9mjtg== X-Google-Smtp-Source: ABdhPJxo21GLzCRAPbn8IuYNq5BrDxG37xhSqvd6KDAb538SAkX5CrVK0/zyJ46C7fGwx5152THs7A== X-Received: by 2002:a50:e696:0:b0:419:998d:5feb with SMTP id z22-20020a50e696000000b00419998d5febmr3385822edm.122.1648545133919; Tue, 29 Mar 2022 02:12:13 -0700 (PDT) Received: from ?IPV6:2001:16b8:5cfa:6600:5e5f:67ff:fef4:ffd8? ([2001:16b8:5cfa:6600:5e5f:67ff:fef4:ffd8]) by smtp.gmail.com with ESMTPSA id w2-20020a50d982000000b00410dc0889b9sm8326063edj.63.2022.03.29.02.12.13 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 29 Mar 2022 02:12:13 -0700 (PDT) Message-ID: <8974509d-ff11-a9b6-c91a-fa44c0cb10ce@FreeBSD.org> Date: Tue, 29 Mar 2022 10:12:15 +0200 List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; FreeBSD amd64; rv:91.0) Gecko/20100101 Thunderbird/91.7.0 Content-Language: en-US To: Greg Lehey , src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org References: <202203280359.22S3xKut056353@gitrepo.freebsd.org> From: Mateusz Piotrowski <0mp@FreeBSD.org> Subject: Re: git: 3c9f304b383b - main - Describe modern time zone handling. In-Reply-To: <202203280359.22S3xKut056353@gitrepo.freebsd.org> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Rspamd-Queue-Id: 4KSP391Sfwz3kp8 X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=pass (mx1.freebsd.org: domain of mpp302@gmail.com designates 209.85.208.49 as permitted sender) smtp.mailfrom=mpp302@gmail.com X-Spamd-Result: default: False [-2.95 / 15.00]; ARC_NA(0.00)[]; RCVD_VIA_SMTP_AUTH(0.00)[]; RCVD_TLS_ALL(0.00)[]; FROM_HAS_DN(0.00)[]; RCPT_COUNT_THREE(0.00)[4]; R_SPF_ALLOW(-0.20)[+ip4:209.85.128.0/17:c]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MIME_GOOD(-0.10)[text/plain]; DMARC_NA(0.00)[FreeBSD.org]; NEURAL_HAM_LONG(-1.00)[-1.000]; TO_DN_SOME(0.00)[]; MID_RHS_MATCH_FROM(0.00)[]; RCVD_COUNT_THREE(0.00)[3]; NEURAL_HAM_MEDIUM(-0.95)[-0.950]; NEURAL_HAM_SHORT(-1.00)[-0.999]; RCVD_IN_DNSWL_NONE(0.00)[209.85.208.49:from]; MLMMJ_DEST(0.00)[dev-commits-src-all,dev-commits-src-main]; FORGED_SENDER(0.30)[0mp@FreeBSD.org,mpp302@gmail.com]; RWL_MAILSPIKE_POSSIBLE(0.00)[209.85.208.49:from]; R_DKIM_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:15169, ipnet:209.85.128.0/17, country:US]; FROM_NEQ_ENVFROM(0.00)[0mp@FreeBSD.org,mpp302@gmail.com]; FREEMAIL_ENVFROM(0.00)[gmail.com] X-ThisMailContainsUnwantedMimeParts: N Hey Greg, I've noticed a couple of minor issues in the patch. On 28/03/2022 05:59, Greg Lehey wrote: > The branch main has been updated by grog: > > URL: https://cgit.FreeBSD.org/src/commit/?id=3c9f304b383bd378757ac33393b02f457947bc50 > > commit 3c9f304b383bd378757ac33393b02f457947bc50 > Author: Greg Lehey > AuthorDate: 2022-03-28 03:57:37 +0000 > Commit: Greg Lehey > CommitDate: 2022-03-28 03:57:37 +0000 > > Describe modern time zone handling. > Reviewed by: peterj@ > MFC after: 2 weeks That's probably a typo, but it is a good idea to leave an empty line after the first line. Otherwise Git tooling thinks all the lines belong to the title of the commit message and it makes for a really long email subject. ;) > --- > bin/date/date.1 | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++------- > 1 file changed, 83 insertions(+), 11 deletions(-) > > diff --git a/bin/date/date.1 b/bin/date/date.1 > index 0aaae1614327..e4aad28c7d81 100644 > --- a/bin/date/date.1 > +++ b/bin/date/date.1 > @@ -195,6 +195,13 @@ Print the date and time of the last modification of > Display or set the date in > .Tn UTC > (Coordinated Universal) time. > +By default > +.Nm > +displays the time in the time zone described by > +.Pa /etc/localtime > +or the > +.Ev TZ > +environment variable. > .It Xo > .Fl v > .Sm off > @@ -337,10 +344,61 @@ Seconds, a number from 0 to 60 > .Pp > Everything but the minutes is optional. > .Pp > -Time changes for Daylight Saving Time, standard time, leap seconds, > +.Nm > +understands the time zone definitions in the > +.Nm tzdata > +package located in > +.Pa /usr/share/zoneinfo . > +This requires the kernel clock to be set to UTC. > +Time changes for Daylight Saving Time, standard time, leap seconds > and leap years are handled automatically. > +.Pp > +There are two ways to specify the time zone: > +.Pp > +If the file or symlink > +.Pa /etc/localtime > +exists, it is interpreted as a time zone definition file, usually in > +the directory hierarchy > +.Pa /usr/share/zoneinfo , > +which contains the time zone definitions from the > +.Nm tzdata > +package. > +.Pp > +If the environment variable > +.Ev TZ > +is set, its value is interpreted as the name of a time zone definition > +file, either an absolute path or a relative path to a time zone > +definition in > +.Pa /usr/share/zoneinfo . > +The > +.Ev TZ > +variable overrides > +.Pa /etc/localtime . > +.Pp > +If the time zone definition file is invalid, > +.Nm > +silently reverts to UTC. > +.Pp > +Previous versions of > +.Nm > +included the > +.Fl d > +(set daylight saving time flag) and > +.Fl t > +(set negative time zone offset) options, but these details are now > +handled automatically by > +.Nm tzdata . This should be Sy instead of Nm. From what I understand, Nm should be used only when referring to the subject of the manual page (in this case, "date"). > +Modern offsets are positive for time zones ahead of UTC and negative > +for time zones behind UTC, but like the obsolete > +.Nm t Nm should be Fl. > +option, the > +.Nm tzdata I'd change Nm to Sy. > +files in the subdirectory > +.Pa /usr/share/zoneinfo/Etc > +still use an older convention where times ahead of UTC are considered > +negative. > .Sh ENVIRONMENT > -The following environment variables affect the execution of > +The following environment variable affects the execution of > .Nm : > .Bl -tag -width Ds > .It Ev TZ > @@ -350,16 +408,22 @@ The normal format is a pathname relative to > For example, the command > .Dq TZ=America/Los_Angeles date > displays the current time in California. > +The variable can also specify an absolute path. > See > .Xr environ 7 > for more information. > .El > .Sh FILES > .Bl -tag -width /var/log/messages -compact > -.It Pa /var/log/utx.log > -record of date resets and time changes > +.It Pa /etc/localtime > +Time zone information file for default system time zone. > +May be omitted, in which case the default time zone is UTC. > +.It Pa /usr/share/zoneinfo > +Directory containing time zone information files. > .It Pa /var/log/messages > record of the user setting the time > +.It Pa /var/log/utx.log > +record of date resets and time changes Perhaps unrelated to this change, but it would be nice to make all descriptions consistent (start with a capital letter, finish with a period). > .El > .Sh EXIT STATUS > The > @@ -463,13 +527,14 @@ If this occurs, > .Nm > prints: > .Ql multiple output formats specified > -and exits with an error status. > +and exits with status 1. I'm not sure if we want to limit ourselves to 1. Perhaps it's better to just say it is non-zero so that we can have the flexibility in the future to return different exit codes for different errors. > .Sh SEE ALSO > .Xr locale 1 , > .Xr gettimeofday 2 , > .Xr getutxent 3 , > .Xr strftime 3 , > -.Xr strptime 3 > +.Xr strptime 3 , > +.Xr ntpd 8 > .Rs > .%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD" > .%A R. Gusella > @@ -480,11 +545,9 @@ The > .Nm > utility is expected to be compatible with > .St -p1003.2 . > -The > -.Fl f , I , j , r , > -and > -.Fl v > -options are all extensions to the standard. > +With the exception of the > +.Fl u > +option, all options are extensions to the standard. > .Pp > The format selected by the > .Fl I > @@ -496,6 +559,15 @@ A > command appeared in > .At v1 . > .Pp > +A number of options were added and then removed again, including the > +.Fl d > +(set DST flag) and > +.Fl t > +(set negative time zone offset). > +Time zones are now handled by the > +.Nm tzdata Nm should be Sy. Ideally, we should create a manual page for tzdata and just use Xr here. > +package. > +.Pp > The > .Fl I > flag was added in >