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