contrib/tzcode/tzselect.8

   1 .\" This file is in the public domain, so clarified as of
   2 .\" 2009-05-17 by Arthur David Olson.
   3 .TH tzselect 8 "" "Time Zone Database"
   4 .SH NAME
   5 tzselect \- select a timezone
   6 .SH SYNOPSIS
   7 .ie \n(.g .ds - \f(CR-\fP
   8 .el .ds - \-
   9 .ds d " degrees
  10 .ds m " minutes
  11 .ds s " seconds
  12 .ds _ " \&
  13 .if t \{\
  14 . if \n(.g .if c \(de .if c \(fm .if c \(sd \{\
  15 .  ds d \(de
  16 .  ds m \(fm
  17 .  ds s \(sd
  18 .  ds _ \|
  19 . \}
  20 .\}
  21 .B tzselect
  22 [
  23 .B \*-c
  24 .I coord
  25 ] [
  26 .B \*-n
  27 .I limit
  28 ] [
  29 .B \*-\*-help
  30 ] [
  31 .B \*-\*-version
  32 ]
  33 .SH DESCRIPTION
  34 The
  35 .B tzselect
  36 program asks the user for information about the current location,
  37 and outputs the resulting timezone to standard output.
  38 The output is suitable as a value for the TZ environment variable.
  39 .PP
  40 All interaction with the user is done via standard input and standard error.
  41 .SH OPTIONS
  42 .TP
  43 .BI "\*-c " coord
  44 Instead of asking for continent and then country and then city,
  45 ask for selection from time zones whose largest cities
  46 are closest to the location with geographical coordinates
  47 .I coord.
  48 Use ISO 6709 notation for
  49 .I coord,
  50 that is, a latitude immediately followed by a longitude.  The latitude
  51 and longitude should be signed integers followed by an optional
  52 decimal point and fraction: positive numbers represent north and east,
  53 negative south and west.  Latitudes with two and longitudes with three
  54 integer digits are treated as degrees; latitudes with four or six and
  55 longitudes with five or seven integer digits are treated as
  56 .I "DDMM, DDDMM, DDMMSS,"
  57 or
  58 .I DDDMMSS
  59 representing
  60 .I DD
  61 or
  62 .I DDD
  63 degrees,
  64 .I MM
  65 minutes,
  66 and zero or
  67 .I SS
  68 seconds, with any trailing fractions represent fractional minutes or
  69 (if
  70 .I SS
  71 is present) seconds.  The decimal point is that of the current locale.
  72 For example, in the (default) C locale,
  73 .B "\*-c\ +40.689\*-074.045"
  74 specifies 40.689\*d\*_N, 74.045\*d\*_W,
  75 .B "\*-c\ +4041.4\*-07402.7"
  76 specifies 40\*d\*_41.4\*m\*_N, 74\*d\*_2.7\*m\*_W, and
  77 .B "\*-c\ +404121\*-0740240"
  78 specifies 40\*d\*_41\*m\*_21\*s\*_N, 74\*d\*_2\*m\*_40\*s\*_W.
  79 If
  80 .I coord
  81 is not one of the documented forms, the resulting behavior is unspecified.
  82 .TP
  83 .BI "\*-n " limit
  84 When
  85 .B \*-c
  86 is used, display the closest
  87 .I limit
  88 locations (default 10).
  89 .TP
  90 .B "\*-\*-help"
  91 Output help information and exit.
  92 .TP
  93 .B "\*-\*-version"
  94 Output version information and exit.
  95 .SH "ENVIRONMENT VARIABLES"
  96 .TP
  97 \f3AWK\fP
  98 Name of a Posix-compliant
  99 .B awk
 100 program (default:
 101 .BR awk ).
 102 .TP
 103 \f3TZDIR\fP
 104 Name of the directory containing timezone data files (default:
 105 .BR /usr/share/zoneinfo ).
 106 .SH FILES
 107 .TP
 108 \f2TZDIR\fP\f3/iso3166.tab\fP
 109 Table of ISO 3166 2-letter country codes and country names.
 110 .TP
 111 \f2TZDIR\fP\f3/zone1970.tab\fP
 112 Table of country codes, latitude and longitude, timezones, and
 113 descriptive comments.
 114 .TP
 115 \f2TZDIR\fP\f3/\fP\f2TZ\fP
 116 Timezone data file for timezone \f2TZ\fP.
 117 .SH "EXIT STATUS"
 118 The exit status is zero if a timezone was successfully obtained from the user,
 119 nonzero otherwise.
 120 .SH "SEE ALSO"
 121 newctime(3), tzfile(5), zdump(8), zic(8)
 122 .SH NOTES
 123 Applications should not assume that
 124 .BR tzselect 's
 125 output matches the user's political preferences.