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.\" $FreeBSD$ 26.\" 27.Dd March 8, 2012 28.Dt ADJKERNTZ 8 29.Os 30.Sh NAME 31.Nm adjkerntz 32.Nd adjust the local time CMOS clock to reflect time zone changes and keep the current timezone offset for the kernel 33.Sh SYNOPSIS 34.Nm 35.Fl i 36.Nm 37.Fl a Op Fl s 38.Sh DESCRIPTION 39The 40.Nm 41utility maintains the proper relationship between the kernel clock, which 42is always set to UTC and the CMOS clock, which may be set to local time. 43The 44.Nm 45utility also informs the kernel about machine timezone shifts in order to 46maintain proper timestamps for local time file systems such as the MS-DOS 47file system. 48The main purpose of maintaining these timestamps properly is to keep the 49timestamps of a 50.Fx 51MS-DOS file system and an MS-DOS operating system synchronized when they are 52installed on the same system rather than fixing broken MS-DOS file 53timestamps. 54If the file 55.Pa /etc/wall_cmos_clock 56exists, it means that the CMOS clock keeps local time (MS-DOS and MS-Windows 57compatible mode). 58If that file does not exist, it means that the CMOS clock keeps UTC time. 59The 60.Nm 61utility passes this state to the 62.Pa machdep.wall_cmos_clock 63kernel variable. 64.Pp 65Adjustments may be needed at system startup and shutdown, and 66whenever a time zone change occurs. 67To handle these different situations, 68.Nm 69is invoked in two ways: 70.Bl -tag -width 4n 71.It Fl i 72This form handles system startups and shutdowns. 73The 74.Nm 75utility is invoked with this option from 76.Pa /etc/rc 77on entry to multi-user mode, before any other daemons have been started. 78The 79.Nm 80utility puts itself into the background. 81Then, for a local time CMOS clock, 82.Nm 83reads the local time from it 84and sets the kernel clock to the corresponding UTC time. 85The 86.Nm 87utility also stores the local time zone offset in the 88.Pa machdep.adjkerntz 89kernel variable, for use by subsequent invocations of 90.Em "'adjkerntz -a'" 91and by local time file systems. 92.Pp 93For a local time CMOS clock 94.Em "'adjkerntz -i'" 95pauses and remains inactive as a background daemon until it 96receives a SIGTERM. 97The SIGTERM will normally be sent by 98.Xr init 8 99when the system leaves multi-user mode (usually, because the system 100is being shut down). 101After receiving the SIGTERM, 102.Nm 103reads the UTC kernel clock and updates the CMOS clock, if necessary, 104to ensure that it reflects the current local time zone. 105Then 106.Nm 107exits. 108.It Fl a Op Fl s 109This form is used to update the local time CMOS clock and kernel 110.Pa machdep.adjkerntz 111variable when time zone changes occur, 112e.g., when entering or leaving daylight savings time. 113The 114.Nm 115utility uses the kernel clock's UTC time, 116the previously stored 117time zone offset, and the changed time zone rule to 118calculate a new time zone offset. 119It stores the new offset into the 120.Pa machdep.adjkerntz 121kernel variable and updates the wall CMOS clock to the new local time. 122If 123.Em "'adjkerntz -a'" 124was started at a nonexistent time (during a timezone change), it exits 125with a warning diagnostic unless the 126.Fl s 127option was used, in which case 128.Nm 129sleeps 30 minutes and tries again. 130.Pp 131This form should be invoked from root's 132.Xr crontab 5 133every half hour between midnight and 5am, when most modern time 134zone changes occur. 135Warning: do not use the 136.Fl s 137option in a 138.Xr crontab 5 139command line, or multiple 140.Em "'adjkerntz -a'" 141instances could conflict with each other. 142.El 143.Pp 144The 145.Nm 146utility clears the kernel timezone structure and makes the kernel clock run 147in the UTC time zone. 148Super-user privileges are required for all operations. 149.Sh ENVIRONMENT 150.Bl -tag -width Fl 151.It Ev TZ 152Time zone change rule, see 153.Xr tzset 3 ; 154not needed when 155.Xr tzsetup 8 156or 157.Xr zic 8 158is used. 159.El 160.Sh FILES 161.Bl -tag -width /etc/wall_cmos_clock -compact 162.It Pa /etc/localtime 163Current zoneinfo file, see 164.Xr tzsetup 8 165and 166.Xr zic 8 . 167.It Pa /etc/wall_cmos_clock 168Empty file. 169Its presence indicates that the machine's CMOS clock is set to local 170time, while its absence indicates a UTC CMOS clock. 171.El 172.Sh DIAGNOSTICS 173No diagnostics. 174If an error occurs, 175.Nm 176logs an error message via 177.Xr syslog 3 178and exits with a nonzero return code. 179.Sh SEE ALSO 180.Xr tzset 3 , 181.Xr crontab 5 , 182.Xr mount_msdosfs 8 , 183.Xr rc 8 , 184.Xr sysctl 8 , 185.Xr tzsetup 8 , 186.Xr zic 8 187.Sh HISTORY 188The 189.Nm 190utility appeared in 191.Fx 1.0 . 192.Sh AUTHORS 193.An Andrey A. Chernov Aq Mt ache@astral.msk.su 194