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