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