From nobody Mon Jul 29 20:18:01 2024 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 4WXqRY54xLz5RvRX; Mon, 29 Jul 2024 20:18:01 +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 "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4WXqRY4FS2z4gQp; Mon, 29 Jul 2024 20:18:01 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1722284281; 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=o/FcwLmFM0SaOVx2/Wq3IlukrVh8ZVFgC5kvTaLvHE0=; b=bfxQWMcHWUj8l4S84t9oH6hrfvn0kXEiMdTFzjbCkcGxMe19P2na4QTdx5Nk1C9dqg4VfT YLpqlNlGLIAOrJDorFKZKv+oSbZGCkfrtsFm3oQ30ddsiipgN0a2pU+rd0bt/MznrK8HkS fnKfi/Apc61WhCBWWWzuAnV0e0MpUeDz7ODdIC1tG/QYBK1/6/9zyrYTkOMcua1bWMtIgC EUt2WHxkxIW4d7rzhR0IWCDeYLRZexpSx4uoAheGuzkS6giNwvtRpLI/qbYfOUrYHEzSex udz8hz2tsbap8Qx81pm7QgzRoBAghsGVO5eZ+QZiK8rhBXp9xSiT0DoYa64Lug== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1722284281; a=rsa-sha256; cv=none; b=XQvRRqTnVMRFiQfBLtcmQ/41hzulJlfB1JpO6HEUbWMJQlb6Qybiuj/hMomlynyKc5kHne yRswa4ULTRB6dv1CBrfvz09mNl+bPj8BJDsTXfhf0G2A2ArV7qqbLoScYhAd06b752wGav ABwr5EOsM7ykTETLNT39m6qmFy7sfLlwaD05A614eIx+SYD9hIZeBCwWs/ctHzPvJClyJp glZfJcydaiYDiYrvVgR2qHALFuFF7O8zqMj7sYxdM1+BfZ7CFuSOqDLPxXLRD7feYiQx6H 0ZHFH9LPipPbjzL5ibMXFPCEPdV4Dc1RKp35wQrqvSHO7JypnWW60QBfO44V0A== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1722284281; 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=o/FcwLmFM0SaOVx2/Wq3IlukrVh8ZVFgC5kvTaLvHE0=; b=s07hxzcmB9DWYFLwo+y/Yn1l9+YAqBuwZkzJ3ei0ZvB9PZA+/03dWZLTSgwkcTbC8kZLGf 9LWwOMC66mzxU7rakPiUG0Fl54ZCAd8qiTA2hbHQJcA3QPE0i2O517vFJzm8qoj2WME7Pt 5+Og2oZfrwuFzqzsFFBTZMoEQzkZKLX20w2t4XTsSBOS2hdjaA3Eu5drUbfiyGv1w/wq8+ cGcNi7qoymhMGr1R5lbaGQza2Ya0xR9nnbnIs1CO2HKL/Klqvz0M38x9hQZP38uCVyGwB8 r5z+iHKx3hcZe4hNPQFshb2mcb8Q6z8vOsy3+E0t+DRfaX88hZKwB0w2l/BU1Q== 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 4WXqRY3rl9zp7B; Mon, 29 Jul 2024 20:18:01 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 46TKI1Rd079051; Mon, 29 Jul 2024 20:18:01 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 46TKI1PR079048; Mon, 29 Jul 2024 20:18:01 GMT (envelope-from git) Date: Mon, 29 Jul 2024 20:18:01 GMT Message-Id: <202407292018.46TKI1PR079048@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Warner Losh Subject: git: ad57cea9e633 - main - adjkerntz.8: minor cleanup (markup, spdx, reflow) 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: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: ad57cea9e633cac5ef3f17ce0a82160bc32d7f63 Auto-Submitted: auto-generated The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=ad57cea9e633cac5ef3f17ce0a82160bc32d7f63 commit ad57cea9e633cac5ef3f17ce0a82160bc32d7f63 Author: Alexander Ziaee AuthorDate: 2024-07-24 19:39:13 +0000 Commit: Warner Losh CommitDate: 2024-07-29 20:06:06 +0000 adjkerntz.8: minor cleanup (markup, spdx, reflow) + real-time and rtc added to search keywords - local dropped from search keywords + ntpd added to see also + use machine independent language Reported by: emaste (MI language) MFC after: 3 days Reviewed by: imp Pull Request: https://github.com/freebsd/freebsd-src/pull/1326 --- sbin/adjkerntz/adjkerntz.8 | 72 ++++++++++++++++++++++++---------------------- 1 file changed, 38 insertions(+), 34 deletions(-) diff --git a/sbin/adjkerntz/adjkerntz.8 b/sbin/adjkerntz/adjkerntz.8 index 787282348a91..b87981fd19f4 100644 --- a/sbin/adjkerntz/adjkerntz.8 +++ b/sbin/adjkerntz/adjkerntz.8 @@ -1,4 +1,7 @@ -.\" Copyright (C) 1993-1998 by Andrey A. Chernov, Moscow, Russia. +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 1993-1998 by Andrey A. Chernov, Moscow, Russia. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -22,12 +25,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd March 8, 2012 +.Dd July 29, 2024 .Dt ADJKERNTZ 8 .Os .Sh NAME .Nm adjkerntz -.Nd adjust the local time CMOS clock to reflect time zone changes and keep the current timezone offset for the kernel +.Nd adjust real-time clock (rtc) and kernel timezone offset .Sh SYNOPSIS .Nm .Fl i @@ -37,7 +40,7 @@ The .Nm utility maintains the proper relationship between the kernel clock, which -is always set to UTC and the CMOS clock, which may be set to local time. +is always set to UTC and the real-time clock, which may be set to local time. The .Nm utility also informs the kernel about machine timezone shifts in order to @@ -51,13 +54,13 @@ installed on the same system rather than fixing broken MS-DOS file timestamps. If the file .Pa /etc/wall_cmos_clock -exists, it means that the CMOS clock keeps local time (MS-DOS and MS-Windows -compatible mode). -If that file does not exist, it means that the CMOS clock keeps UTC time. +exists, it means that the real-time clock keeps local time +.Pq MS-DOS and MS-Windows compatible mode . +If that file does not exist, it means that the real-time clock keeps UTC time. The .Nm utility passes this state to the -.Pa machdep.wall_cmos_clock +.Va machdep.wall_cmos_clock kernel variable. .Pp Adjustments may be needed at system startup and shutdown, and @@ -65,7 +68,7 @@ whenever a time zone change occurs. To handle these different situations, .Nm is invoked in two ways: -.Bl -tag -width 4n +.Bl -tag -width "-a [-s]" .It Fl i This form handles system startups and shutdowns. The @@ -76,51 +79,51 @@ on entry to multi-user mode, before any other daemons have been started. The .Nm utility puts itself into the background. -Then, for a local time CMOS clock, +Then, for a local time real-time clock, .Nm reads the local time from it and sets the kernel clock to the corresponding UTC time. The .Nm utility also stores the local time zone offset in the -.Pa machdep.adjkerntz +.Va machdep.adjkerntz kernel variable, for use by subsequent invocations of -.Em "'adjkerntz -a'" +.Ql adjkerntz -a and by local time file systems. .Pp -For a local time CMOS clock -.Em "'adjkerntz -i'" +For a local time real-time clock +.Ql adjkerntz -i pauses and remains inactive as a background daemon until it receives a SIGTERM. The SIGTERM will normally be sent by .Xr init 8 -when the system leaves multi-user mode (usually, because the system -is being shut down). +when the system leaves multi-user mode +.Pq usually, because the system is being shut down . After receiving the SIGTERM, .Nm -reads the UTC kernel clock and updates the CMOS clock, if necessary, +reads the UTC kernel clock and updates the real-time clock, if necessary, to ensure that it reflects the current local time zone. Then .Nm exits. .It Fl a Op Fl s -This form is used to update the local time CMOS clock and kernel -.Pa machdep.adjkerntz -variable when time zone changes occur, +This form is used to update the local time real-time clock and +.Va machdep.adjkerntz +kernel variable when time zone changes occur, e.g., when entering or leaving daylight savings time. The .Nm utility uses the kernel clock's UTC time, -the previously stored -time zone offset, and the changed time zone rule to -calculate a new time zone offset. +the previously stored time zone offset, +and the changed time zone rule to calculate a new time zone offset. It stores the new offset into the -.Pa machdep.adjkerntz -kernel variable and updates the wall CMOS clock to the new local time. +.Va machdep.adjkerntz +kernel variable and updates the wall real-time clock to the new local time. If -.Em "'adjkerntz -a'" -was started at a nonexistent time (during a timezone change), it exits -with a warning diagnostic unless the +.Ql adjkerntz -a +was started at a nonexistent time +.Pq during a timezone change , +it exits with a warning diagnostic unless the .Fl s option was used, in which case .Nm @@ -128,14 +131,14 @@ sleeps 30 minutes and tries again. .Pp This form should be invoked from root's .Xr crontab 5 -every half hour between midnight and 5am, when most modern time -zone changes occur. +every half hour between midnight and 5am, +when most modern time zone changes occur. Warning: do not use the .Fl s option in a .Xr crontab 5 command line, or multiple -.Em "'adjkerntz -a'" +.Ql adjkerntz -a instances could conflict with each other. .El .Pp @@ -145,7 +148,7 @@ utility clears the kernel timezone structure and makes the kernel clock run in the UTC time zone. Super-user privileges are required for all operations. .Sh ENVIRONMENT -.Bl -tag -width Fl +.Bl -tag -width /etc/wall_cmos_clock .It Ev TZ Time zone change rule, see .Xr tzset 3 ; @@ -164,8 +167,8 @@ and .Xr zic 8 . .It Pa /etc/wall_cmos_clock Empty file. -Its presence indicates that the machine's CMOS clock is set to local -time, while its absence indicates a UTC CMOS clock. +Its presence indicates that the machine's real-time clock is set to local +time, while its absence indicates a UTC real-time clock. .El .Sh DIAGNOSTICS No diagnostics. @@ -178,6 +181,7 @@ and exits with a nonzero return code. .Xr tzset 3 , .Xr crontab 5 , .Xr mount_msdosfs 8 , +.Xr ntpd 8 , .Xr rc 8 , .Xr sysctl 8 , .Xr tzsetup 8 ,