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