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