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 .Fx
  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 .Pa 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 .Pa 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 SIGTERM.
  99 The SIGTERM will normally be sent by
 100 .Xr init 8
 101 when the system leaves multi-user mode (usually, because the system
 102 is being shut down).
 103 After receiving the SIGTERM,
 104 .Nm
 105 reads the UTC kernel clock and updates the CMOS clock, if necessary,
 106 to ensure that it reflects the current local time zone.
 107 Then
 108 .Nm
 109 exits.
 110 .It Fl a Op Fl s
 111 This form is used to update the local time CMOS clock and kernel
 112 .Pa machdep.adjkerntz
 113 variable when time zone changes occur,
 114 e.g., when entering or leaving daylight savings time.
 115 The
 116 .Nm
 117 utility uses the kernel clock's UTC time,
 118 the previously stored
 119 time zone offset, and the changed time zone rule to
 120 calculate a new time zone offset.
 121 It stores the new offset into the
 122 .Pa machdep.adjkerntz
 123 kernel variable, and updates the wall CMOS clock to the new local time.
 124 If
 125 .Em "'adjkerntz -a'"
 126 was started at a nonexistent time (during a timezone change), it exits
 127 with a warning diagnostic unless the
 128 .Fl s
 129 option was used, in which case
 130 .Nm
 131 sleeps 30 minutes and tries again.
 132 .Pp
 133 This form should be invoked from root's
 134 .Xr crontab 5
 135 every half hour between midnight and 5am, when most modern time
 136 zone changes occur.
 137 Warning: don't use the
 138 .Fl s
 139 option in a
 140 .Xr crontab 5
 141 command line, or multiple
 142 .Em "'adjkerntz -a'"
 143 instances could conflict with each other.
 144 .El
 145 .Pp
 146 The
 147 .Nm
 148 utility clears the kernel timezone structure and makes the kernel clock run
 149 in the UTC time zone.
 150 Super-user privileges are required for all operations.
 151 .Sh ENVIRONMENT
 152 .Bl -tag -width Fl
 153 .It Ev TZ
 154 Time zone change rule, see
 155 .Xr tzset 3 ;
 156 not needed when
 157 .Xr tzsetup 8
 158 or
 159 .Xr zic 8
 160 is used.
 161 .El
 162 .Sh FILES
 163 .Bl -tag -width /etc/wall_cmos_clock -compact
 164 .It Pa /etc/localtime
 165 Current zoneinfo file, see
 166 .Xr tzsetup 8
 167 and
 168 .Xr zic 8 .
 169 .It Pa /etc/wall_cmos_clock
 170 Empty file.
 171 Its presence indicates that the machine's CMOS clock is set to local
 172 time, while its absence indicates a UTC CMOS clock.
 173 .El
 174 .Sh SEE ALSO
 175 .Xr tzset 3 ,
 176 .Xr crontab 5 ,
 177 .Xr mount_msdos 8 ,
 178 .Xr rc 8 ,
 179 .Xr sysctl 8 ,
 180 .Xr tzsetup 8 ,
 181 .Xr zic 8
 182 .Sh DIAGNOSTICS
 183 No diagnostics.
 184 If an error occurs,
 185 .Nm
 186 logs an error message via
 187 .Xr syslog 3
 188 and exits with a nonzero return code.
 189 .Sh AUTHORS
 190 .An Andrey A. Chernov Aq ache@astral.msk.su
 191 .Sh HISTORY
 192 The
 193 .Nm
 194 utility appeared in
 195 .Fx 1.0 .