ADJKERNTZ(8)            FreeBSD System Manager's Manual           ADJKERNTZ(8)

NAME

     adjkerntz - adjust real-time clock (rtc) and kernel timezone offset

SYNOPSIS

     adjkerntz -i
     adjkerntz -a [-s]

DESCRIPTION

     The adjkerntz utility maintains the proper relationship between the
     kernel clock, which is always set to UTC and the real-time clock, which
     may be set to local time.  The adjkerntz utility also informs the kernel
     about machine timezone shifts in order to maintain proper timestamps for
     local time file systems such as the MS-DOS file system.  The main purpose
     of maintaining these timestamps properly is to keep the timestamps of a
     FreeBSD MS-DOS file system and an MS-DOS operating system synchronized
     when they are installed on the same system rather than fixing broken MS-
     DOS file timestamps.  If the file /etc/wall_cmos_clock exists, it means
     that the real-time clock keeps local time (MS-DOS and MS-Windows
     compatible mode).  If that file does not exist, it means that the real-
     time clock keeps UTC time.  The adjkerntz utility passes this state to
     the machdep.wall_cmos_clock kernel variable.

     Adjustments may be needed at system startup and shutdown, and whenever a
     time zone change occurs.  To handle these different situations, adjkerntz
     is invoked in two ways:

     -i       This form handles system startups and shutdowns.  The adjkerntz
              utility is invoked with this option from /etc/rc on entry to
              multi-user mode, before any other daemons have been started.
              The adjkerntz utility puts itself into the background.  Then,
              for a local time real-time clock, adjkerntz reads the local time
              from it and sets the kernel clock to the corresponding UTC time.
              The adjkerntz utility also stores the local time zone offset in
              the machdep.adjkerntz kernel variable, for use by subsequent
              invocations of `adjkerntz -a' and by local time file systems.

              For a local time real-time clock `adjkerntz -i' pauses and
              remains inactive as a background daemon until it receives a
              SIGTERM.  The SIGTERM will normally be sent by init(8) when the
              system leaves multi-user mode (usually, because the system is
              being shut down).  After receiving the SIGTERM, adjkerntz reads
              the UTC kernel clock and updates the real-time clock, if
              necessary, to ensure that it reflects the current local time
              zone.  Then adjkerntz exits.

     -a [-s]  This form is used to update the local time real-time clock and
              machdep.adjkerntz kernel variable when time zone changes occur,
              e.g., when entering or leaving daylight savings time.  The
              adjkerntz utility 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 machdep.adjkerntz kernel variable and updates
              the wall real-time clock to the new local time.  If `adjkerntz
              -a' was started at a nonexistent time (during a timezone
              change), it exits with a warning diagnostic unless the -s option
              was used, in which case adjkerntz sleeps 30 minutes and tries
              again.

              This form should be invoked from root's crontab(5) every half
              hour between midnight and 5am, when most modern time zone
              changes occur.  Warning: do not use the -s option in a
              crontab(5) command line, or multiple `adjkerntz -a' instances
              could conflict with each other.

     The adjkerntz utility clears the kernel timezone structure and makes the
     kernel clock run in the UTC time zone.  Super-user privileges are
     required for all operations.

ENVIRONMENT

     TZ                    Time zone change rule, see tzset(3); not needed
                           when tzsetup(8) or zic(8) is used.

FILES

     /etc/localtime        Current zoneinfo file, see tzsetup(8) and zic(8).
     /etc/wall_cmos_clock  Empty file.  Its presence indicates that the
                           machine's real-time clock is set to local time,
                           while its absence indicates a UTC real-time clock.

DIAGNOSTICS

     No diagnostics.  If an error occurs, adjkerntz logs an error message via
     syslog(3) and exits with a nonzero return code.

SEE ALSO

     tzset(3), crontab(5), mount_msdosfs(8), ntpd(8), rc(8), sysctl(8),
     tzsetup(8), zic(8)

HISTORY

     The adjkerntz utility appeared in FreeBSD 1.0.

AUTHORS

     Andrey A. Chernov <ache@astral.msk.su>

FreeBSD 15.1-STABLE-HBSD         July 29, 2024                    ADJKERNTZ(8)