1.\"- 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 1993-1998 by Andrey A. Chernov, Moscow, Russia. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd July 29, 2024 29.Dt ADJKERNTZ 8 30.Os 31.Sh NAME 32.Nm adjkerntz 33.Nd adjust real-time clock (rtc) and kernel timezone offset 34.Sh SYNOPSIS 35.Nm 36.Fl i 37.Nm 38.Fl a Op Fl s 39.Sh DESCRIPTION 40The 41.Nm 42utility maintains the proper relationship between the kernel clock, which 43is always set to UTC and the real-time clock, which may be set to local time. 44The 45.Nm 46utility also informs the kernel about machine timezone shifts in order to 47maintain proper timestamps for local time file systems such as the MS-DOS 48file system. 49The main purpose of maintaining these timestamps properly is to keep the 50timestamps of a 51.Fx 52MS-DOS file system and an MS-DOS operating system synchronized when they are 53installed on the same system rather than fixing broken MS-DOS file 54timestamps. 55If the file 56.Pa /etc/wall_cmos_clock 57exists, it means that the real-time clock keeps local time 58.Pq MS-DOS and MS-Windows compatible mode . 59If that file does not exist, it means that the real-time clock keeps UTC time. 60The 61.Nm 62utility passes this state to the 63.Va machdep.wall_cmos_clock 64kernel variable. 65.Pp 66Adjustments may be needed at system startup and shutdown, and 67whenever a time zone change occurs. 68To handle these different situations, 69.Nm 70is invoked in two ways: 71.Bl -tag -width "-a [-s]" 72.It Fl i 73This form handles system startups and shutdowns. 74The 75.Nm 76utility is invoked with this option from 77.Pa /etc/rc 78on entry to multi-user mode, before any other daemons have been started. 79The 80.Nm 81utility puts itself into the background. 82Then, for a local time real-time clock, 83.Nm 84reads the local time from it 85and sets the kernel clock to the corresponding UTC time. 86The 87.Nm 88utility also stores the local time zone offset in the 89.Va machdep.adjkerntz 90kernel variable, for use by subsequent invocations of 91.Ql adjkerntz -a 92and by local time file systems. 93.Pp 94For a local time real-time clock 95.Ql adjkerntz -i 96pauses and remains inactive as a background daemon until it 97receives a SIGTERM. 98The SIGTERM will normally be sent by 99.Xr init 8 100when the system leaves multi-user mode 101.Pq usually, because the system is being shut down . 102After receiving the SIGTERM, 103.Nm 104reads the UTC kernel clock and updates the real-time clock, if necessary, 105to ensure that it reflects the current local time zone. 106Then 107.Nm 108exits. 109.It Fl a Op Fl s 110This form is used to update the local time real-time clock and 111.Va machdep.adjkerntz 112kernel variable when time zone changes occur, 113e.g., when entering or leaving daylight savings time. 114The 115.Nm 116utility uses the kernel clock's UTC time, 117the previously stored time zone offset, 118and the changed time zone rule to calculate a new time zone offset. 119It stores the new offset into the 120.Va machdep.adjkerntz 121kernel variable and updates the wall real-time clock to the new local time. 122If 123.Ql adjkerntz -a 124was started at a nonexistent time 125.Pq during a timezone change , 126it exits with a warning diagnostic unless the 127.Fl s 128option was used, in which case 129.Nm 130sleeps 30 minutes and tries again. 131.Pp 132This form should be invoked from root's 133.Xr crontab 5 134every half hour between midnight and 5am, 135when most modern time zone changes occur. 136Warning: do not use the 137.Fl s 138option in a 139.Xr crontab 5 140command line, or multiple 141.Ql adjkerntz -a 142instances could conflict with each other. 143.El 144.Pp 145The 146.Nm 147utility clears the kernel timezone structure and makes the kernel clock run 148in the UTC time zone. 149Super-user privileges are required for all operations. 150.Sh ENVIRONMENT 151.Bl -tag -width /etc/wall_cmos_clock 152.It Ev TZ 153Time zone change rule, see 154.Xr tzset 3 ; 155not needed when 156.Xr tzsetup 8 157or 158.Xr zic 8 159is used. 160.El 161.Sh FILES 162.Bl -tag -width /etc/wall_cmos_clock -compact 163.It Pa /etc/localtime 164Current zoneinfo file, see 165.Xr tzsetup 8 166and 167.Xr zic 8 . 168.It Pa /etc/wall_cmos_clock 169Empty file. 170Its presence indicates that the machine's real-time clock is set to local 171time, while its absence indicates a UTC real-time clock. 172.El 173.Sh DIAGNOSTICS 174No diagnostics. 175If an error occurs, 176.Nm 177logs an error message via 178.Xr syslog 3 179and exits with a nonzero return code. 180.Sh SEE ALSO 181.Xr tzset 3 , 182.Xr crontab 5 , 183.Xr mount_msdosfs 8 , 184.Xr ntpd 8 , 185.Xr rc 8 , 186.Xr sysctl 8 , 187.Xr tzsetup 8 , 188.Xr zic 8 189.Sh HISTORY 190The 191.Nm 192utility appeared in 193.Fx 1.0 . 194.Sh AUTHORS 195.An Andrey A. Chernov Aq Mt ache@astral.msk.su 196