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