HardenedBSD/sbin/adjkerntz/adjkerntz.8

.\" Copyright (C) 1993-1996 by Andrey A. Chernov, Moscow, Russia.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd April 4, 1996
.Dt ADJKERNTZ 8
.Os FreeBSD
.Sh NAME
.Nm adjkerntz
.Nd "adjust local time CMOS clock to reflect time zone changes and keep current timezone offset for the kernel"
.Sh SYNOPSIS
.Nm adjkerntz
.Fl i
.Nm adjkerntz
.Fl a Op Fl s
.Sh DESCRIPTION
.Nm Adjkerntz
maintains the proper relationship between the kernel clock, which
is always set to UTC, and the CMOS clock, which may be set to local
time.
.Nm Adjkerntz
also informs the kernel about machine timezone shift to
maintain proper timestamps for local time file systems like MS-DOS one.
If the file
.Pa /etc/wall_cmos_clock
exists, it means that CMOS clock keep local time (MS-DOS and MS-Windows
compatible mode),
if that file does not exist it means that CMOS clock keep UTC time.
.Nm Adjkerntz
passes this state to
.Pa machdep.wall_cmos_clock
kernel variable.
.Pp
Adjustments may be needed at system startup and shutdown, and
whenever a time zone change occurs.
To handle these different situations,
.Nm adjkerntz
is invoked in two ways:
.Bl -tag -width 4n
.It Cm Fl i
This form handles system startups and shutdowns.
.Nm Adjkerntz
is invoked with this option from
.Pa /etc/rc
on entry to multi-user mode, before any other daemons have been started.
.Nm Adjkerntz
puts itself into the background.
Then for wall CMOS clock
.Nm adjkerntz
reads the local time from it
and sets the kernel clock to the corresponding UTC time.
.Nm Adjkerntz
also stores the local time zone offset into the
.Pa machdep.adjkerntz
kernel variable, for use by subsequent invocations of
.Nm "'adjkerntz -a'"
and by local time file systems.
.Pp
For wall CMOS clock
.Nm "'adjkerntz -i'"
pauses, and remains inactive as a background daemon until it
receives a SIGTERM.
The SIGTERM will normally be sent by
.Xr init 8
when the system leaves multi-user mode (usually, because the system
is being shut down).
After receiving the SIGTERM,
.Nm adjkerntz
reads the UTC kernel clock and updates the CMOS clock, if necessary,
to ensure that it reflects the current local time zone.
Then
.Nm adjkerntz
exits.
.It Cm Fl a Op Fl s
This form is used to update the wall CMOS clock and kernel
.Pa machdep.adjkerntz
variable when time zone changes occur,
e.g., when entering or leaving daylight savings time.
.Nm Adjkerntz
uses the kernel clock's UTC time,
the previously stored
time zone offset, and the changed time zone rule to
calculate a new time zone offset.
It stores the new offset into the
.Pa machdep.adjkerntz
kernel variable, and updates the wall CMOS clock to the new local time.
If
.Nm "'adjkerntz -a'"
was started at nonexisten time (inside timezone change), it exits
with warning diagnostic unless
.Fl s
option is used, in this case
.Nm adjkerntz
sleep 30 minutes and tries again.
.Pp
This form should be invoked from root's
.Xr crontab 5
every half hour between midnight and 4am, when most modern time
zone changes occur.
Warning: don't use
.Fl s
option in
.Xr crontab 5
command line or multiply
.Nm "'adjkerntz -a'"
copies can conflict with each other.
.El
.Pp
.Nm Adjkerntz
clears the kernel timezone structure and makes the kernel clock run
in the UTC time zone.
Super-user privileges are required for all operations.
.Sh ENVIRONMENT
.Bl -tag -width Fl
.It Ev TZ
Time zone change rule, see
.Xr tzset 3 ;
not needed when
.Xr tzsetup 8
or
.Xr zic 8
is used.
.Sh FILES
.Bl -tag -width /etc/wall_cmos_clock -compact
.It Pa /etc/localtime
Current zoneinfo file, see
.Xr tzsetup 8
and
.Xr zic 8 .
.It Pa /etc/wall_cmos_clock
Empty file.
Its presence indicates that the machine's CMOS clock is set to local
time, while its absence indicates a UTC CMOS clock.
.Sh SEE ALSO
.Xr tzset 3 ,
.Xr crontab 5 ,
.Xr rc 8 ,
.Xr sysctl 8 ,
.Xr tzsetup 8 ,
.Xr zic 8 .
.Sh DIAGNOSTICS
No diagnostics.
If an error occurs,
.Nm adjkerntz
logs an error message via
.Xr syslog 3
and exits with a nonzero return code.
.Sh AUTHOR
Andrey A. Chernov <ache@astral.msk.su>
.Sh HISTORY
The
.Nm adjkerntz
command appeared in FreeBSD 1.0.1.