From nobody Mon Mar 28 03:59:20 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 F3A1E1A3CDDE; Mon, 28 Mar 2022 03:59:20 +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 4KRf8S6bPCz3HmW; Mon, 28 Mar 2022 03:59:20 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1648439960; 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=Gc1hObcCT/a5P0+KoFiygn2J4i7NV/F6s/B/ANwJNUs=; b=MsyBmM07hESQVdCXtYHT5eRtxKg20l35UijFO9EpWiZiByxv+RuGcqzxDKSPeeVRY1h1Y0 0K7J8cDulKX453JXwsQi/hIroEZaCqDnn+l9HVgLD4wWk2lMefa0+3of5bTYiDIUML9t4y p5MSc7421pe6V26XkVr9wE6H1txGVUM4nt/BvN5XW0Hs9MqVSyYr3hf9BS/D7uBuvxwH6w HPppEoFAAyZVPZ6Px9KLgrPNQdHqMCN/z/+lesaOxb5Vq0mqmG9/R7P1VgpvKbmiCAeYWZ mRHTOU1CWRynvz9zZ4J067OSjfJJ3ApHIFgxJe6GmQmizhMBOs/3h8zAJyd4Ew== 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 C258622955; Mon, 28 Mar 2022 03:59:20 +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 22S3xKT9056354; Mon, 28 Mar 2022 03:59:20 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 22S3xKut056353; Mon, 28 Mar 2022 03:59:20 GMT (envelope-from git) Date: Mon, 28 Mar 2022 03:59:20 GMT Message-Id: <202203280359.22S3xKut056353@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Greg Lehey Subject: git: 3c9f304b383b - main - Describe modern time zone handling. Reviewed by: peterj@ MFC after: 2 weeks 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 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: grog X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 3c9f304b383bd378757ac33393b02f457947bc50 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1648439960; 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=Gc1hObcCT/a5P0+KoFiygn2J4i7NV/F6s/B/ANwJNUs=; b=vroz/9FX0vEFrRy68m01gsZRuslRh05asR3xkHOugvg57pf0Bzzu6PtWrCgDMsTWLq2ew6 aUQO5ITQbrXPKiUCpcaDUbfHFPoqzV/M3lONyM9G16lO87XM9FPFREcFxmqtEH/xB3uep+ 8zQ/1Cixq1y+53UiaCnCJosC580Lu2bMkUpFxxVCP2ltknGLT/Yd/qhwrr0Urb0KA16/QE vkB7LbNitHj8apZpSYzdyF33TIZ7OVkZVKsMQrdowas0y+MOmTkmjjgGMNSF4osMYSrbW7 a2MyWRSA2M7fzgt71wnCde3Htq+6MYSJFLWJLXAgIiHJ9p+8NfeP4dDYEPQrUA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1648439960; a=rsa-sha256; cv=none; b=f3DhnvKmrCBj7YT/DMW65yarH03BWVIIPgOxbYXLKzNana+M4gELodTeQA60pYP+VRZfCd ss/LV7X0gZkARBqjWWItO4CEtRfZhWqEsbYvPB1pEnQb9NnI0xGHhr4Iy/egBFNzu0dG9x 2e6+Pq7a5PfpI8wT1COVBPuCFvL9RVKRfJZxaWK7chyNZ7VkZbuB+8aGdxfUaw5Jq5CQm9 FN2Naq1Agy6E4W9qtt62InxdSkD5+TPpKPVen+GsAv14qkSowjL0Fps4Qru6JkaP5ffyQR sGrx5KiKeBe8ln7EI141G1waY7Qd1Hya3+Ly/nWJZPSRmqgYVzwOUWwbBcDSlA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N 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 --- 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 . +Modern offsets are positive for time zones ahead of UTC and negative +for time zones behind UTC, but like the obsolete +.Nm t +option, the +.Nm tzdata +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 .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. .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 +package. +.Pp The .Fl I flag was added in