zic Command

Purpose

The zic command provides a time zone compiler.

Syntax

zic [ -v ] [ -p Posixrules ] [ -d Directory ] [ -L Leapseconds ] [ -b bloat ] [ -r [@lo][/@hi] ] [ -R @hi] [ --version ] [ --help ] [ FileName ...]

Description

The zic command processes text from the files that are named on the command line and creates the time conversion binary files that are specified in this input. The time zone information is processed from the standard input if file name is specified as - (hyphen).

Input lines in the specified files are made up of fields. Field separators can be any number of white-space characters. A pound sign (#) in the input file indicates a comment that extends to the end of the line on which the pound sign appears. White-space characters and pound signs can be enclosed in double quotation marks (") if they are to be used as part of a field. Blank lines are ignored.

A rule line has the form:

Rule  NAME  FROM   TO   TYPE   IN   ON   AT   SAVE   LETTER/S

Following are the fields that make up the rule line:

NAME

This field provides a random name for the set of rules for which this Rule is applicable.

FROM

This field provides the first year in which the rule applies. Specifying minimum (min) indicates the minimum year with a representable time value. Specifying maximum (max) indicates the maximum year with a representable time value.

TO

This field provides the final year in which the rule applies. This option is indicated as a valid time value or by specifying a minimum and maximum. Specifying only is used to repeat the value of the FROM field.

TYPE

This field provides the type of year in which the rule applies.

The TYPE field has the following values:

'-': The rule applies in all years between FROM and TO, inclusively.
uspres: The rule applies in US Presidential election years.
nonpres: The rule applies in years other than US Presidential election years.

IN

This field represents the month in which the rule takes effect. Month names can be abbreviated.

ON

This field represents the day on which the rule takes effect. Following are the recognized forms:

lastFri represents the last Friday in the month.
lastMon represents the last Monday in the month.
A number that represents the day of the month. For example, 5 represents the fifth of the month.
lastSun represents the last Sunday in the month.
Sun>=8 represents the first Sunday on or after the eighth.
Sun<=25 represents the last Sunday on or before the 25th.

Names of days of the week can be abbreviated or spelled out in full. Spaces are not supported within the ON field.

AT

Represents the time of day at which the rule takes effect. Following are the recognized forms:

A number that represents time in hours. For example, 2 indicates two hours.
2:00 indicates two AM in hours and minutes.
15:00 represents three PM in the afternoon by using the 24-hour format time format.
1:28:14 indicates one hour, twenty-eight minutes, and fourteen seconds, by using the hours, minutes, seconds format.

Any of these forms can be followed by the letter w if the given time is local wall-clock time or s if the given time is local standard time. In the absence of w or s, wall-clock time is assumed.

Regions with more than two types of local time are required to use the local standard time in the AT field of the earliest transition time's rule to ensure the accuracy of the earliest transition time that is stored in the resulting time-zone binary.

SAVE

This field represents the amount of time to be added to local standard time when the rule is in effect. This field has the same format as the AT field. The w and s suffixes are not valid with this field.

LETTER/S

This field provides the variable part of the time-zone abbreviations that are used when this rule is in effect. When this field contains - (hyphen), the variable is null. The S character is used to indicate EST and the D character is used to indicate EDT.

A zone line has the form:

Zone   NAME   GMTOFF   RULES/SAVE   FORMAT   [UNTIL]

Following are the fields that make up a zone line:

NAME: Indicates the name of the time zone. The name that is specified by the NAME field is the name that is used to create a file that contains time conversion information for the zone.
GMTOFF: Indicated the amount of time to add to GMT to get standard time in this zone. This field has the same format as the AT and SAVE fields of rule lines. Begin the field with a minus sign if time must be subtracted from GMT.
RULES/SAVE: Indicated the name of the rules that apply in the time zone or alternately, an amount of time to add to local standard time. If value of this field is - (hyphen), then standard time always applies in the time zone.
FORMAT: Indicates the format for time zone abbreviations in this time zone. The %s characters are used to show where the variable part of the time zone abbreviation goes.
UNTIL: Indicates the time at which the GMT offset or the rules change for a location. It is specified as year, month, day, and time of day. If this field is specified, the time zone information is generated from the specified GMT offset and rule change until the time specified.

The next line must be a continuation line. The continuation line places information that starts at the time that is specified in the UNTIL field of the previous line into the file that is used by the previous line. This line has the same format as a zone line, except that the Zone string and the name are omitted. Continuation lines can contain a UNTIL field, just as zone lines do, indicating that the next line is a further continuation.

A link line has the form:

Link    LINK-FROM    LINK-TO

The LINK-FROM field must appear as the NAME field in a zone line; the LINK-TO field is used as an alternate name for that zone.

Except for continuation lines, lines can appear in any order in the input.

The zic command has a limitation of compiling input that contains a date before 14 December 1901 because dates before this time cannot be represented by a 32-bit time_t data type.

Flags

Table 1. Flags
Item	Description
-b `bloat`	Provides binary data as specified by the `bloat` variable that is compatible with the earlier versions of software. Following are the valid values for the `bloat` variable: fat The fat option generates additional data entries in the binary file. These entries address potential bugs or incompatibilities in an older version of software. For example, an older version of software that incorrectly handles the 64-bit generated data. slim The slim option generates a smaller binary file that helps to identify bugs or incompatibilities in an older version of software. This binary file does not work around the bugs or incompatibilities. The default value for the `bloat` variable is the slim option. Note: You can also change the size of the binary file by using the -r option.
-d `Directory`	Creates files that contain time conversion information in the `Directory` directory, instead of the /usr/share/lib/zoneinfo/ standard directory.
--help	Displays a short usage message and exits.
-l `TimeZone`	Uses the `TimeZone` time zone as local time. The zic command acts as if the file contained a link similar to the following link: `Link timezone localtime`
-L `Leapseconds`	Reads the leap second information from the `leapseconds` file. If this option is not used, leap second information does not appear in the output.
-p `Posixrules`	Use the `posixrules` rules when handling POSIX-format time zone environment variables. The zic command acts as if the file contains a link as in this example: `Link timezone posixrules`
-r [@`lo`][/@`hi`]	The -r flag limits the applicability of the output binary files to timestamps in the range that is specified by the `lo` and `hi` variables. The values of the `lo` and `hi` variables are signed decimal counts of seconds since the EPOCH (1970-01-01 00:00:00 Coordinated Universal Time). The range includes the value of the `lo` variable but excludes the value of the `hi` variable. If the `lo` and the `hi` variables are not specified, the range defaults to extreme values. The output binary files use UT offset 0 and the abbreviation -00 if the `lo` and the `hi` variables are not specified. For example, the `zic -r @0` command returns binary data for nonnegative timestamps (the time after EPOCH). The `zic -r @0/@2147483648` command returns binary data for nonnegative timestamps that fit into 31-bit signed integers. On platforms with GNU date, the `zic -r @$(date +%s)` command excludes binary data that is intended for timestamps before the specified date. Using the -r flag reduces the size of the output binary file. However, the size of the output binary file might increase due to the need to represent the timestamp range boundaries. If the value of the `hi` variable causes a time zone information format (`TZif`) file to contain explicit entries for pre-`hi` transitions instead of representing them with an extended `POSIX TZ` format string, the size of the output binary file might increase. Note: You can also reduce the size of the binary file by using the -b slim option.
-R @`hi`	The -R flag generates redundant trailing explicit transitions for timestamps that occur less than the specified value of the `hi` variable in seconds since the EPOCH. These transitions can be more concisely represented via the extended `POSIX TZ` string. The -R flag does not affect the represented timestamps. You can accommodate nonstandard `TZif` readers that ignore the extended POSIX TZ string by using the -R flag. However, this option increases the size of the output binary file.
-v	Provides a message if a year that appears in a data file is outside the range of years representable by system time values (0:00:00 AM GMT, 1 January 1970, to 3:14:07 AM GMT, 19 January 2038).
--version	Displays the version information of the file and exits.

Parameters

Table 2. Parameters
Item	Description
`FileName`	A file that contains input lines that specify to create files that contain the time conversion information. If `FileName` is - (hyphen), then standard input is read.

Examples

A rule line can have the following format:

Rule  USA  1970    max    -    Sep   Sun<=14 3:00   0     S

A zone line can have the following format:

Zone    Turkey          3:00    Turkey          EET%s

A link line can have the following format:
```
Link    MET     CET
```
To compile a timezone.infile file that contains input time zone information and place the binary values into the standard time zone /usr/share/lib/zoneinfo/ directory, type:
```
zic timezone.infile
```
To compile a timezone.infile file that contains input time zone information and place the binary values into a directory that is specified with -d option, type:
```
 zic -d tzdir timezone.infile 
```
To report warnings during compilation of the time zone input file when the range of years are incorrect, type:
```
zic -v timezone.infile 
```
To compile a format.zi file that contains input time zone information and to place the binary values into a directory that is specified with -d flag, enter the following command:
```
zic -d /usr/share/lib/zoneinfo /usr/share/lib/tz/format.zi
```
The format.zi file contains information about the input time zone in the DATAFORM format. The format has the following valid options:
- main.zi: This option is the default DATAFORM format for the .zi file.
- vanguard.zi: This option is the latest DATAFORM format that supports negative offset values.
- rearguard.zi: This DATAFORM format does not support negative offset values.
For more information about DATAFORM format, see the DATAFORM format section.

DATAFORM format

The new DATAFORM format macro in the makefile provides three source data formats to minimise the downstream disruption when data formats are improved.

The DATAFORM format macro offers the following source data formats:

main: This DATAFORM format installs the data format from files similar to the africa data format file or other similar data format files. This option is the default format. Elements of the main format must move to the rearguard format in the future.
vanguard: This DATAFORM format installs the data format from the bleeding-edge format, which is released but is not reliably tested. Elements of the vanguard format must move to the main format in the future.
rearguard: This DATAFORM format installs the data format from the trailing-edge format that had more time to mature through iterative improvement.

Currently, the main and rearguard formats are identical and match the 2018 calendar. The vanguard format has a special feature that supports negative offset values. This feature of the vanguard format improves support for Ireland, where they follow Irish Standard Time (IST, UTC+01) in summer and Greenwich Mean Time (UTC) in winter. The tzcode library has supported negative offset values for a long time and must move to the main format soon. However, the tzcode library might not move to the rearguard format soon because some downstream parsers do not support negative offset values.

The build procedure for the DATAFORM format macro creates three files that are named vanguard.zi, main.zi, and rearguard.zi. Although the vanguard.zi, main.zi, and rearguard.zi files represent the same data, they might have minor discrepancies. These files are intended for the downstream data users. The zoneinfo parsers that do not support negative offset values must start using the rearguard.zi data format file so that they are not affected when the negative offset feature is moved from the vanguard data format to the main data format. The bleeding-edge zoneinfo parsers that support the new negative offset values can use the vanguard.zi data format file.

Exit Status

0: The command was completed successfully.
>0: An error occurred.

Files

Table 3. Files
Item	Description
/usr/sbin/zic	Contains the SystemV zic command.
/usr/share/lib/zoneinfo	Standard directory used for files that are created by the zic command.
/usr/share/lib/tz/	Contains .zi files to support DATAFORM formats by the zic command.