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