sbin/adjkerntz/adjkerntz.8

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