usr.sbin/tzsetup/tzsetup.8

   1 .\" Copyright (c) 1996 Wolfram Schneider <wosch@FreeBSD.org>. Berlin.
   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 AUTHOR AND CONTRIBUTORS ``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 AUTHOR 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$
  26 .\"
  27 .Dd April 18, 2023
  28 .Dt TZSETUP 8
  29 .Os
  30 .Sh NAME
  31 .Nm tzsetup
  32 .Nd set local timezone
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl nrs
  36 .Op Fl C Ar chroot_directory
  37 .Op Ar zoneinfo_file | zoneinfo_name
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 utility reads a database of timezone information and presents a menu
  42 allowing the user to select a specific zone without knowing the details
  43 of the database layout.
  44 The selected zone is installed as the system
  45 default zone.
  46 The
  47 .Nm
  48 utility also determines whether any adjustment is necessary for systems where
  49 the hardware clock does not keep UTC.
  50 .Pp
  51 The following options are available:
  52 .Bl -tag -offset indent -width Fl
  53 .It Fl C Ar chroot_directory
  54 Open all files and directories relative to
  55 .Ar chroot_directory .
  56 .It Fl n
  57 Do not create or copy files.
  58 .It Fl r
  59 Reinstall the zoneinfo file installed last time.
  60 The name is obtained from
  61 .Pa /var/db/zoneinfo .
  62 .It Fl s
  63 Skip the initial question about adjusting the clock if not set to UTC.
  64 .El
  65 .Pp
  66 It is possible to short-circuit the menu system by specifying the
  67 location of a
  68 .Ar zoneinfo_file
  69 or the name of the
  70 .Ar zoneinfo_name
  71 on the command line; this is intended mainly for pre-configured installation
  72 scripts or people who know which zoneinfo they want to install.
  73 .Sh TIMEZONE DATABASE
  74 The contents of the timezone database are indexed by
  75 .Pa /usr/share/zoneinfo/zone1970.tab .
  76 This file lists, for each timezone data file, the ISO 3166 territory code,
  77 approximate geographical coordinates (in ISO 6709 format),
  78 and location within the territory.
  79 .Pp
  80 The maintainers of the database maintain the following policies:
  81 .Bl -enum -offset indent
  82 .It
  83 At least one zone for every country or inhabited geographical territory.
  84 .It
  85 One zone for every distinct, documented timezone history since the
  86 beginning of the
  87 .Ux
  88 epoch (January 1, 1970, GMT).
  89 .It
  90 Each zone is named for the most populous city therein.
  91 (Where possible,
  92 the database includes pre-1970 history for its city.)
  93 .El
  94 .Pp
  95 The source code to the database
  96 .Pq Pa /usr/src/contrib/tzdata/[a-z]*
  97 contains many additional comments and documentation references for the
  98 historically minded.
  99 .Sh FILES
 100 .Bl -tag -width ".Pa /usr/share/zoneinfo/zone1970.tab" -compact
 101 .It Pa /etc/localtime
 102 current time zone file
 103 .It Pa /etc/wall_cmos_clock
 104 see
 105 .Xr adjkerntz 8
 106 .It Pa /usr/share/misc/iso3166
 107 mapping of ISO 3166 territory codes to names
 108 .It Pa /usr/share/zoneinfo
 109 directory for zoneinfo files
 110 .It Pa /usr/share/zoneinfo/zone1970.tab
 111 mapping of timezone file to country and location
 112 .It Pa /var/db/zoneinfo
 113 saved name of the timezone file installed last
 114 .El
 115 .Sh EXAMPLES
 116 Normal usage, to select the right zoneinfo file via the dialog-based
 117 user interface:
 118 .Pp
 119 .Dl # tzsetup
 120 .Pp
 121 Install the file
 122 .Pa /usr/share/zoneinfo/Australia/Sydney :
 123 .Pp
 124 .Dl "# tzsetup /usr/share/zoneinfo/Australia/Sydney"
 125 .Pp
 126 Install the zoneinfo file for Australia/Sydney, assumed to be located in
 127 .Pa /usr/share/zoneinfo :
 128 .Pp
 129 .Dl "# tzsetup Australia/Sydney"
 130 .Pp
 131 After a reinstall of the zoneinfo files, you can reinstall the
 132 latest installed zoneinfo file (as specified in
 133 .Pa /var/db/zoneinfo ) :
 134 .Pp
 135 .Dl "# tzsetup -r"
 136 .Sh SEE ALSO
 137 .Xr date 1 ,
 138 .Xr adjtime 2 ,
 139 .Xr ctime 3 ,
 140 .Xr timezone 3 ,
 141 .Xr tzfile 5 ,
 142 .Xr adjkerntz 8 ,
 143 .Xr zdump 8 ,
 144 .Xr zic 8
 145 .Sh DISCLAIMER
 146 The representation of certain localities as being associated with certain
 147 countries and/or territories is for the purposes of identification only,
 148 and does not imply any endorsement or rejection on the part of the
 149 .Fx
 150 Project of the territorial claims of any entity.
 151 .Sh BUGS
 152 Programs which are already running when
 153 .Nm
 154 creates or updates
 155 .Pa /etc/localtime
 156 will not reflect the updated timezone.
 157 When the system is first configured for a non-UTC
 158 hardware clock, it is necessary to run
 159 .Xr adjkerntz 8
 160 (which normally happens as a part of system startup) in order to update
 161 the kernel's idea of the correct timezone offset.