From c554a39725c852498bc7a6a22b242e69b68d9602 Mon Sep 17 00:00:00 2001 From: Erik van der Kouwe Date: Wed, 6 Jan 2010 08:00:39 +0000 Subject: [PATCH] Move man-pages for zoneinfo, replace with links --- commands/zoneinfo/newctime.3 | 238 +---------------- commands/zoneinfo/newstrftime.3 | 231 +---------------- commands/zoneinfo/newtzset.3 | 238 +---------------- commands/zoneinfo/time2posix.3 | 122 +-------- commands/zoneinfo/tzfile.5 | 139 +--------- commands/zoneinfo/tzselect.8 | 42 +-- commands/zoneinfo/zdump.8 | 58 +---- commands/zoneinfo/zic.8 | 437 +------------------------------- man/man3/newctime.3 | 237 +++++++++++++++++ man/man3/newstrftime.3 | 230 +++++++++++++++++ man/man3/newtzset.3 | 237 +++++++++++++++++ man/man3/time2posix.3 | 121 +++++++++ man/man5/tzfile.5 | 138 ++++++++++ man/man8/tzselect.8 | 41 +++ man/man8/zdump.8 | 57 +++++ man/man8/zic.8 | 436 +++++++++++++++++++++++++++++++ 16 files changed, 1505 insertions(+), 1497 deletions(-) mode change 100644 => 120000 commands/zoneinfo/newctime.3 mode change 100644 => 120000 commands/zoneinfo/newstrftime.3 mode change 100644 => 120000 commands/zoneinfo/newtzset.3 mode change 100644 => 120000 commands/zoneinfo/time2posix.3 mode change 100644 => 120000 commands/zoneinfo/tzfile.5 mode change 100644 => 120000 commands/zoneinfo/tzselect.8 mode change 100644 => 120000 commands/zoneinfo/zdump.8 mode change 100644 => 120000 commands/zoneinfo/zic.8 create mode 100644 man/man3/newctime.3 create mode 100644 man/man3/newstrftime.3 create mode 100644 man/man3/newtzset.3 create mode 100644 man/man3/time2posix.3 create mode 100644 man/man5/tzfile.5 create mode 100644 man/man8/tzselect.8 create mode 100644 man/man8/zdump.8 create mode 100644 man/man8/zic.8 diff --git a/commands/zoneinfo/newctime.3 b/commands/zoneinfo/newctime.3 deleted file mode 100644 index fcb554c9c..000000000 --- a/commands/zoneinfo/newctime.3 +++ /dev/null @@ -1,237 +0,0 @@ -.TH NEWCTIME 3 -.SH NAME -asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time to ASCII -.SH SYNOPSIS -.nf -.B extern char *tzname[2]; -.PP -.B void tzset() -.PP -.B #include -.PP -.B char *ctime(clock) -.B const time_t *clock; -.PP -.B double difftime(time1, time0) -.B time_t time1; -.B time_t time0; -.PP -.B #include -.PP -.B char *asctime(tm) -.B const struct tm *tm; -.PP -.B struct tm *localtime(clock) -.B const time_t *clock; -.PP -.B struct tm *gmtime(clock) -.B const time_t *clock; -.PP -.B time_t mktime(tm) -.B struct tm *tm; -.PP -.B cc ... -ltz -.fi -.SH DESCRIPTION -.I Ctime\^ -converts a long integer, pointed to by -.IR clock , -representing the time in seconds since -00:00:00 UTC, 1970-01-01, -and returns a pointer to a -string of the form -.br -.ce -.eo -Thu Nov 24 18:22:48 1986\n\0 -.br -.ec -Years requiring fewer than four characters are padded with leading zeroes. -For years longer than four characters, the string is of the form -.br -.ce -.eo -Thu Nov 24 18:22:48 81986\n\0 -.ec -.br -with five spaces before the year. -These unusual formats are designed to make it less likely that older -software that expects exactly 26 bytes of output will mistakenly output -misleading values for out-of-range years. -.PP -.I Localtime\^ -and -.I gmtime\^ -return pointers to ``tm'' structures, described below. -.I Localtime\^ -corrects for the time zone and any time zone adjustments -(such as Daylight Saving Time in the United States). -After filling in the ``tm'' structure, -.I localtime -sets the -.BR tm_isdst 'th -element of -.B tzname -to a pointer to an -ASCII string that's the time zone abbreviation to be used with -.IR localtime 's -return value. -.PP -.I Gmtime\^ -converts to Coordinated Universal Time. -.PP -.I Asctime\^ -converts a time value contained in a -``tm'' structure to a string, -as shown in the above example, -and returns a pointer to the string. -.PP -.I Mktime\^ -converts the broken-down time, -expressed as local time, -in the structure pointed to by -.I tm -into a calendar time value with the same encoding as that of the values -returned by the -.I time -function. -The original values of the -.B tm_wday -and -.B tm_yday -components of the structure are ignored, -and the original values of the other components are not restricted -to their normal ranges. -(A positive or zero value for -.B tm_isdst -causes -.I mktime -to presume initially that summer time (for example, Daylight Saving Time -in the U.S.A.) -respectively, -is or is not in effect for the specified time. -A negative value for -.B tm_isdst -causes the -.I mktime -function to attempt to divine whether summer time is in effect -for the specified time.) -On successful completion, the values of the -.B tm_wday -and -.B tm_yday -components of the structure are set appropriately, -and the other components are set to represent the specified calendar time, -but with their values forced to their normal ranges; the final value of -.B tm_mday -is not set until -.B tm_mon -and -.B tm_year -are determined. -.I Mktime\^ -returns the specified calendar time; -If the calendar time cannot be represented, -it returns -.BR -1 . -.PP -.I Difftime\^ -returns the difference between two calendar times, -.RI ( time1 -- -.IR time0 ), -expressed in seconds. -.PP -Declarations of all the functions and externals, and the ``tm'' structure, -are in the -.B \^ -header file. -The structure (of type) -.B struct tm -includes the following fields: -.RS -.PP -.nf -.ta .5i +\w'long tm_gmtoff;\0\0'u - int tm_sec; /\(** seconds (0 - 60) \(**/ - int tm_min; /\(** minutes (0 - 59) \(**/ - int tm_hour; /\(** hours (0 - 23) \(**/ - int tm_mday; /\(** day of month (1 - 31) \(**/ - int tm_mon; /\(** month of year (0 - 11) \(**/ - int tm_year; /\(** year \- 1900 \(**/ - int tm_wday; /\(** day of week (Sunday = 0) \(**/ - int tm_yday; /\(** day of year (0 - 365) \(**/ - int tm_isdst; /\(** is summer time in effect? \(**/ - char \(**tm_zone; /\(** abbreviation of timezone name \(**/ - long tm_gmtoff; /\(** offset from UTC in seconds \(**/ -.fi -.RE -.PP -The -.I tm_zone -and -.I tm_gmtoff -fields exist, and are filled in, only if arrangements to do -so were made when the library containing these functions was -created. -There is no guarantee that these fields will continue to exist -in this form in future releases of this code. -.PP -.I Tm_isdst\^ -is non-zero if summer time is in effect. -.PP -.I Tm_gmtoff -is the offset (in seconds) of the time represented -from UTC, with positive values indicating east -of the Prime Meridian. -.SH FILES -.ta \w'/usr/share/zoneinfo/posixrules\0\0'u -/usr/share/zoneinfo time zone information directory -.br -/usr/share/zoneinfo/localtime local time zone file -.br -/usr/share/zoneinfo/posixrules used with POSIX-style TZ's -.br -/usr/share/zoneinfo/GMT for UTC leap seconds -.sp -If -.B /usr/share/zoneinfo/GMT -is absent, -UTC leap seconds are loaded from -.BR /usr/share/zoneinfo/posixrules . -.SH SEE ALSO -getenv(3), -newstrftime(3), -newtzset(3), -time(2), -tzfile(5) -.SH NOTES -The return values point to static data; -the data is overwritten by each call. -The -.B tm_zone -field of a returned -.B "struct tm" -points to a static array of characters, which -will also be overwritten at the next call -(and by calls to -.IR tzset ). -.PP -.I Asctime\^ -and -.I ctime\^ -behave strangely for years before 1000 or after 9999. -The 1989 and 1999 editions of the C Standard say -that years from \-99 through 999 are converted without -extra spaces, but this conflicts with longstanding -tradition and with this implementation. -Traditional implementations of these two functions are -restricted to years in the range 1900 through 2099. -To avoid this portability mess, new programs should use -.I strftime\^ -instead. -.PP -Avoid using out-of-range values with -.I mktime -when setting up lunch with promptness sticklers in Riyadh. -.\" @(#)newctime.3 7.17 diff --git a/commands/zoneinfo/newctime.3 b/commands/zoneinfo/newctime.3 new file mode 120000 index 000000000..5203f2f5e --- /dev/null +++ b/commands/zoneinfo/newctime.3 @@ -0,0 +1 @@ +../../man/man3/newctime.3 \ No newline at end of file diff --git a/commands/zoneinfo/newstrftime.3 b/commands/zoneinfo/newstrftime.3 deleted file mode 100644 index 19db8ea14..000000000 --- a/commands/zoneinfo/newstrftime.3 +++ /dev/null @@ -1,230 +0,0 @@ -.\" Based on the UCB file whose copyright information appears below. -.\" Copyright (c) 1989, 1991 The Regents of the University of California. -.\" All rights reserved. -.\" -.\" This code is derived from software contributed to Berkeley by -.\" the American National Standards Committee X3, on Information -.\" Processing Systems. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" from: @(#)strftime.3 5.12 (Berkeley) 6/29/91 -.\" $Id: strftime.3,v 1.4 1993/12/15 20:33:00 jtc Exp $ -.\" -.TH NEWSTRFTIME 3 -.SH NAME -strftime \- format date and time -.SH SYNOPSIS -.nf -.B #include -.B #include -.PP -.B size_t strftime(buf, maxsize, format, timeptr) -.B char *buf; -.B size_t maxsize; -.B const char *format; -.B const struct tm *timeptr -.PP -.B cc ... -ltz -.fi -.SH DESCRIPTION -The -.I strftime\^ -function formats the information from -.I timeptr\^ -into the buffer -.I buf\^ -according to the string pointed to by -.IR format\^ . -.PP -The -.I format\^ -string consists of zero or more conversion specifications and -ordinary characters. -All ordinary characters are copied directly into the buffer. -A conversion specification consists of a percent sign -.Ql % -and one other character. -.PP -No more than -.I maxsize\^ -characters are be placed into the array. -If the total number of resulting characters, including the terminating -null character, is not more than -.IR maxsize\^ , -.I strftime\^ -returns the number of characters in the array, not counting the -terminating null. -Otherwise, zero is returned. -.PP -Each conversion specification is replaced by the characters as -follows which are then copied into the buffer. -.TP -%A -is replaced by the locale's full weekday name. -.TP -%a -is replaced by the locale's abbreviated weekday name. -.TP -%B -is replaced by the locale's full month name. -.TP -%b or %h -is replaced by the locale's abbreviated month name. -.TP -%C -is replaced by the century (a year divided by 100 and truncated to an integer) -as a decimal number (00-99). -.TP -%c -is replaced by the locale's appropriate date and time representation. -.TP -%D -is replaced by the date in the format %m/%d/%y. -.TP -%d -is replaced by the day of the month as a decimal number (01-31). -.TP -%e -is replaced by the day of month as a decimal number (1-31); -single digits are preceded by a blank. -.TP -%F -is replaced by the date in the format %Y-%m-%d. -.TP -%G -is replaced by the ISO 8601 year with century as a decimal number. -.TP -%g -is replaced by the ISO 8601 year without century as a decimal number (00-99). -.TP -%H -is replaced by the hour (24-hour clock) as a decimal number (00-23). -.TP -%I -is replaced by the hour (12-hour clock) as a decimal number (01-12). -.TP -%j -is replaced by the day of the year as a decimal number (001-366). -.TP -%k -is replaced by the hour (24-hour clock) as a decimal number (0-23); -single digits are preceded by a blank. -.TP -%l -is replaced by the hour (12-hour clock) as a decimal number (1-12); -single digits are preceded by a blank. -.TP -%M -is replaced by the minute as a decimal number (00-59). -.TP -%m -is replaced by the month as a decimal number (01-12). -.TP -%n -is replaced by a newline. -.TP -%p -is replaced by the locale's equivalent of either AM or PM. -.TP -%R -is replaced by the time in the format %H:%M. -.TP -%r -is replaced by the locale's representation of 12-hour clock time -using AM/PM notation. -.TP -%S -is replaced by the second as a decimal number (00-60). -.TP -%s -is replaced by the number of seconds since the Epoch, UTC (see mktime(3)). -.TP -%T -is replaced by the time in the format %H:%M:%S. -.TP -%t -is replaced by a tab. -.TP -%U -is replaced by the week number of the year (Sunday as the first day of -the week) as a decimal number (00-53). -.TP -%u -is replaced by the weekday (Monday as the first day of the week) -as a decimal number (1-7). -.TP -%V -is replaced by the week number of the year (Monday as the first day of -the week) as a decimal number (01-53). If the week containing January -1 has four or more days in the new year, then it is week 1; otherwise -it is week 53 of the previous year, and the next week is week 1. -.TP -%W -is replaced by the week number of the year (Monday as the first day of -the week) as a decimal number (00-53). -.TP -%w -is replaced by the weekday (Sunday as the first day of the week) -as a decimal number (0-6). -.TP -%X -is replaced by the locale's appropriate time representation. -.TP -%x -is replaced by the locale's appropriate date representation. -.TP -%Y -is replaced by the year with century as a decimal number. -.TP -%y -is replaced by the year without century as a decimal number (00-99). -.TP -%Z -is replaced by the time zone name, -or by the empty string if this is not determinable. -.TP -%z -is replaced by the offset from UTC in the format +HHMM or -HHMM as appropriate, -with positive values representing locations east of Greenwich, -or by the empty string if this is not determinable. -.TP -%% -is replaced by a single %. -.TP -%+ -is replaced by the date and time in date(1) format. -.SH SEE ALSO -date(1), -getenv(3), -newctime(3), -newtzset(3), -time(2), -tzfile(5) -.\" @(#)newstrftime.3 7.15 diff --git a/commands/zoneinfo/newstrftime.3 b/commands/zoneinfo/newstrftime.3 new file mode 120000 index 000000000..bebdb79eb --- /dev/null +++ b/commands/zoneinfo/newstrftime.3 @@ -0,0 +1 @@ +../../man/man3/newstrftime.3 \ No newline at end of file diff --git a/commands/zoneinfo/newtzset.3 b/commands/zoneinfo/newtzset.3 deleted file mode 100644 index ea512447a..000000000 --- a/commands/zoneinfo/newtzset.3 +++ /dev/null @@ -1,237 +0,0 @@ -.TH NEWTZSET 3 -.SH NAME -tzset \- initialize time conversion information -.SH SYNOPSIS -.nf -.B void tzset() -.PP -.B cc ... -ltz -.fi -.SH DESCRIPTION -.I Tzset -uses the value of the environment variable -.B TZ -to set time conversion information used by -.IR localtime . -If -.B TZ -does not appear in the environment, -the best available approximation to local wall clock time, as specified -by the -.IR tzfile (5)-format -file -.B localtime -in the system time conversion information directory, is used by -.IR localtime . -If -.B TZ -appears in the environment but its value is a null string, -Coordinated Universal Time (UTC) is used (without leap second -correction). If -.B TZ -appears in the environment and its value is not a null string: -.IP -if the value begins with a colon, it is used as a pathname of a file -from which to read the time conversion information; -.IP -if the value does not begin with a colon, it is first used as the -pathname of a file from which to read the time conversion information, -and, if that file cannot be read, is used directly as a specification of -the time conversion information. -.PP -When -.B TZ -is used as a pathname, if it begins with a slash, -it is used as an absolute pathname; otherwise, -it is used as a pathname relative to a system time conversion information -directory. -The file must be in the format specified in -.IR tzfile (5). -.PP -When -.B TZ -is used directly as a specification of the time conversion information, -it must have the following syntax (spaces inserted for clarity): -.IP -\fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]] -.PP -Where: -.RS -.TP 15 -.IR std " and " dst -Three or more bytes that are the designation for the standard -.RI ( std ) -or summer -.RI ( dst ) -time zone. Only -.I std -is required; if -.I dst -is missing, then summer time does not apply in this locale. -Upper- and lowercase letters are explicitly allowed. Any characters -except a leading colon -.RB ( : ), -digits, comma -.RB ( , ), -minus -.RB ( \(mi ), -plus -.RB ( \(pl ), -and ASCII NUL are allowed. -.TP -.I offset -Indicates the value one must add to the local time to arrive at -Coordinated Universal Time. The -.I offset -has the form: -.RS -.IP -\fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]] -.RE -.IP -The minutes -.RI ( mm ) -and seconds -.RI ( ss ) -are optional. The hour -.RI ( hh ) -is required and may be a single digit. The -.I offset -following -.I std -is required. If no -.I offset -follows -.IR dst , -summer time is assumed to be one hour ahead of standard time. One or -more digits may be used; the value is always interpreted as a decimal -number. The hour must be between zero and 24, and the minutes (and -seconds) \(em if present \(em between zero and 59. If preceded by a -.RB `` \(mi '', -the time zone shall be east of the Prime Meridian; otherwise it shall be -west (which may be indicated by an optional preceding -.RB `` \(pl ''). -.TP -.I rule -Indicates when to change to and back from summer time. The -.I rule -has the form: -.RS -.IP -\fIdate\fB/\fItime\fB,\fIdate\fB/\fItime\fR -.RE -.IP -where the first -.I date -describes when the change from standard to summer time occurs and the -second -.I date -describes when the change back happens. Each -.I time -field describes when, in current local time, the change to the other -time is made. -.IP -The format of -.I date -is one of the following: -.RS -.TP 10 -.BI J n -The Julian day -.I n -.RI "(1\ \(<=" "\ n\ " "\(<=\ 365). -Leap days are not counted; that is, in all years \(em including leap -years \(em February 28 is day 59 and March 1 is day 60. It is -impossible to explicitly refer to the occasional February 29. -.TP -.I n -The zero-based Julian day -.RI "(0\ \(<=" "\ n\ " "\(<=\ 365). -Leap days are counted, and it is possible to refer to February 29. -.TP -.BI M m . n . d -The -.IR d' th -day -.RI "(0\ \(<=" "\ d\ " "\(<=\ 6) -of week -.I n -of month -.I m -of the year -.RI "(1\ \(<=" "\ n\ " "\(<=\ 5, -.RI "1\ \(<=" "\ m\ " "\(<=\ 12, -where week 5 means ``the last -.I d -day in month -.IR m '' -which may occur in either the fourth or the fifth week). Week 1 is the -first week in which the -.IR d' th -day occurs. Day zero is Sunday. -.RE -.IP "" 15 -The -.I time -has the same format as -.I offset -except that no leading sign -.RB (`` \(mi '' -or -.RB `` \(pl '') -is allowed. The default, if -.I time -is not given, is -.BR 02:00:00 . -.RE -.LP -If no -.I rule -is present in -.BR TZ , -the rules specified -by the -.IR tzfile (5)-format -file -.B posixrules -in the system time conversion information directory are used, with the -standard and summer time offsets from UTC replaced by those specified by -the -.I offset -values in -.BR TZ . -.PP -For compatibility with System V Release 3.1, a semicolon -.RB ( ; ) -may be used to separate the -.I rule -from the rest of the specification. -.PP -If the -.B TZ -environment variable does not specify a -.IR tzfile (5)-format -and cannot be interpreted as a direct specification, -UTC is used. -.SH FILES -.ta \w'/usr/share/zoneinfo/posixrules\0\0'u -/usr/share/zoneinfo time zone information directory -.br -/usr/share/zoneinfo/localtime local time zone file -.br -/usr/share/zoneinfo/posixrules used with POSIX-style TZ's -.br -/usr/share/zoneinfo/GMT for UTC leap seconds -.sp -If -.B /usr/share/zoneinfo/GMT -is absent, -UTC leap seconds are loaded from -.BR /usr/share/zoneinfo/posixrules . -.SH SEE ALSO -getenv(3), -newctime(3), -newstrftime(3), -time(2), -tzfile(5) -.\" @(#)newtzset.3 7.5 diff --git a/commands/zoneinfo/newtzset.3 b/commands/zoneinfo/newtzset.3 new file mode 120000 index 000000000..53481c4be --- /dev/null +++ b/commands/zoneinfo/newtzset.3 @@ -0,0 +1 @@ +../../man/man3/newtzset.3 \ No newline at end of file diff --git a/commands/zoneinfo/time2posix.3 b/commands/zoneinfo/time2posix.3 deleted file mode 100644 index 3ce2e0ee7..000000000 --- a/commands/zoneinfo/time2posix.3 +++ /dev/null @@ -1,121 +0,0 @@ -.TH TIME2POSIX 3 -.SH NAME -time2posix, posix2time \- convert seconds since the Epoch -.SH SYNOPSIS -.nf -.B #include -.B #include -.PP -.B time_t time2posix(t) -.B time_t t -.PP -.B time_t posix2time(t) -.B time_t t -.PP -.B cc ... -ltz -.fi -.SH DESCRIPTION -IEEE Standard 1003.1 -(POSIX) -legislates that a time_t value of -536457599 shall correspond to "Wed Dec 31 23:59:59 UTC 1986." -This effectively implies that POSIX time_t's cannot include leap -seconds and, -therefore, -that the system time must be adjusted as each leap occurs. -.PP -If the time package is configured with leap-second support -enabled, -however, -no such adjustment is needed and -time_t values continue to increase over leap events -(as a true `seconds since...' value). -This means that these values will differ from those required by POSIX -by the net number of leap seconds inserted since the Epoch. -.PP -Typically this is not a problem as the type time_t is intended -to be -(mostly) -opaque\(emtime_t values should only be obtained-from and -passed-to functions such as -.IR time(2) , -.IR localtime(3) , -.IR mktime(3) , -and -.IR difftime(3) . -However, -POSIX gives an arithmetic -expression for directly computing a time_t value from a given date/time, -and the same relationship is assumed by some -(usually older) -applications. -Any programs creating/dissecting time_t's -using such a relationship will typically not handle intervals -over leap seconds correctly. -.PP -The -.I time2posix -and -.I posix2time -functions are provided to address this time_t mismatch by converting -between local time_t values and their POSIX equivalents. -This is done by accounting for the number of time-base changes that -would have taken place on a POSIX system as leap seconds were inserted -or deleted. -These converted values can then be used in lieu of correcting the older -applications, -or when communicating with POSIX-compliant systems. -.PP -.I Time2posix -is single-valued. -That is, -every local time_t -corresponds to a single POSIX time_t. -.I Posix2time -is less well-behaved: -for a positive leap second hit the result is not unique, -and for a negative leap second hit the corresponding -POSIX time_t doesn't exist so an adjacent value is returned. -Both of these are good indicators of the inferiority of the -POSIX representation. -.PP -The following table summarizes the relationship between a time -T and it's conversion to, -and back from, -the POSIX representation over the leap second inserted at the end of June, -1993. -.nf -.ta \w'93/06/30 'u +\w'23:59:59 'u +\w'A+0 'u +\w'X=time2posix(T) 'u -DATE TIME T X=time2posix(T) posix2time(X) -93/06/30 23:59:59 A+0 B+0 A+0 -93/06/30 23:59:60 A+1 B+1 A+1 or A+2 -93/07/01 00:00:00 A+2 B+1 A+1 or A+2 -93/07/01 00:00:01 A+3 B+2 A+3 - -A leap second deletion would look like... - -DATE TIME T X=time2posix(T) posix2time(X) -??/06/30 23:59:58 A+0 B+0 A+0 -??/07/01 00:00:00 A+1 B+2 A+1 -??/07/01 00:00:01 A+2 B+3 A+2 -.sp -.ce - [Note: posix2time(B+1) => A+0 or A+1] -.fi -.PP -If leap-second support is not enabled, -local time_t's and -POSIX time_t's are equivalent, -and both -.I time2posix -and -.I posix2time -degenerate to the identity function. -.SH SEE ALSO -difftime(3), -localtime(3), -mktime(3), -time(2) -.\" @(#)time2posix.3 7.8 -.\" This file is in the public domain, so clarified as of -.\" 1996-06-05 by Arthur David Olson. diff --git a/commands/zoneinfo/time2posix.3 b/commands/zoneinfo/time2posix.3 new file mode 120000 index 000000000..51d9e9c00 --- /dev/null +++ b/commands/zoneinfo/time2posix.3 @@ -0,0 +1 @@ +../../man/man3/time2posix.3 \ No newline at end of file diff --git a/commands/zoneinfo/tzfile.5 b/commands/zoneinfo/tzfile.5 deleted file mode 100644 index ceb6a77b3..000000000 --- a/commands/zoneinfo/tzfile.5 +++ /dev/null @@ -1,138 +0,0 @@ -.TH TZFILE 5 -.SH NAME -tzfile \- time zone information -.SH SYNOPSIS -.B -#include -.SH DESCRIPTION -The time zone information files used by -.IR tzset (3) -begin with the magic characters "TZif" to identify then as -time zone information files, -followed by sixteen bytes reserved for future use, -followed by six four-byte values of type -.BR long , -written in a ``standard'' byte order -(the high-order byte of the value is written first). -These values are, -in order: -.TP -.I tzh_ttisgmtcnt -The number of UTC/local indicators stored in the file. -.TP -.I tzh_ttisstdcnt -The number of standard/wall indicators stored in the file. -.TP -.I tzh_leapcnt -The number of leap seconds for which data is stored in the file. -.TP -.I tzh_timecnt -The number of "transition times" for which data is stored -in the file. -.TP -.I tzh_typecnt -The number of "local time types" for which data is stored -in the file (must not be zero). -.TP -.I tzh_charcnt -The number of characters of "time zone abbreviation strings" -stored in the file. -.PP -The above header is followed by -.I tzh_timecnt -four-byte values of type -.BR long , -sorted in ascending order. -These values are written in ``standard'' byte order. -Each is used as a transition time (as returned by -.IR time (2)) -at which the rules for computing local time change. -Next come -.I tzh_timecnt -one-byte values of type -.BR "unsigned char" ; -each one tells which of the different types of ``local time'' types -described in the file is associated with the same-indexed transition time. -These values serve as indices into an array of -.I ttinfo -structures that appears next in the file; -these structures are defined as follows: -.in +.5i -.sp -.nf -.ta .5i +\w'unsigned int\0\0'u -struct ttinfo { - long tt_gmtoff; - int tt_isdst; - unsigned int tt_abbrind; -}; -.in -.5i -.fi -.sp -Each structure is written as a four-byte value for -.I tt_gmtoff -of type -.BR long , -in a standard byte order, followed by a one-byte value for -.I tt_isdst -and a one-byte value for -.IR tt_abbrind . -In each structure, -.I tt_gmtoff -gives the number of seconds to be added to UTC, -.I tt_isdst -tells whether -.I tm_isdst -should be set by -.I localtime (3) -and -.I tt_abbrind -serves as an index into the array of time zone abbreviation characters -that follow the -.I ttinfo -structure(s) in the file. -.PP -Then there are -.I tzh_leapcnt -pairs of four-byte values, written in standard byte order; -the first value of each pair gives the time -(as returned by -.IR time(2)) -at which a leap second occurs; -the second gives the -.I total -number of leap seconds to be applied after the given time. -The pairs of values are sorted in ascending order by time. -.PP -Then there are -.I tzh_ttisstdcnt -standard/wall indicators, each stored as a one-byte value; -they tell whether the transition times associated with local time types -were specified as standard time or wall clock time, -and are used when a time zone file is used in handling POSIX-style -time zone environment variables. -.PP -Finally there are -.I tzh_ttisgmtcnt -UTC/local indicators, each stored as a one-byte value; -they tell whether the transition times associated with local time types -were specified as UTC or local time, -and are used when a time zone file is used in handling POSIX-style -time zone environment variables. -.PP -.I Localtime -uses the first standard-time -.I ttinfo -structure in the file -(or simply the first -.I ttinfo -structure in the absence of a standard-time structure) -if either -.I tzh_timecnt -is zero or the time argument is less than the first transition time recorded -in the file. -.SH SEE ALSO -newctime(3) -.\" @(#)tzfile.5 7.12 -.\" This file is in the public domain, so clarified as of -.\" 1996-06-05 by Arthur David Olson. diff --git a/commands/zoneinfo/tzfile.5 b/commands/zoneinfo/tzfile.5 new file mode 120000 index 000000000..eb8856461 --- /dev/null +++ b/commands/zoneinfo/tzfile.5 @@ -0,0 +1 @@ +../../man/man5/tzfile.5 \ No newline at end of file diff --git a/commands/zoneinfo/tzselect.8 b/commands/zoneinfo/tzselect.8 deleted file mode 100644 index f839ed828..000000000 --- a/commands/zoneinfo/tzselect.8 +++ /dev/null @@ -1,41 +0,0 @@ -.TH TZSELECT 8 -.SH NAME -tzselect \- select a time zone -.SH SYNOPSIS -.B tzselect -.SH DESCRIPTION -The -.B tzselect -program asks the user for information about the current location, -and outputs the resulting time zone description to standard output. -The output is suitable as a value for the TZ environment variable. -.PP -All interaction with the user is done via standard input and standard error. -.SH "ENVIRONMENT VARIABLES" -.TP -\f3AWK\fP -Name of a Posix-compliant -.I awk -program (default: -.BR awk ). -.TP -\f3TZDIR\fP -Name of the directory containing time zone data files (default: -.BR /usr/share/zoneinfo ). -.SH FILES -.TP -\f2TZDIR\fP\f3/iso3166.tab\fP -Table of ISO 3166 2-letter country codes and country names. -.TP -\f2TZDIR\fP\f3/zone.tab\fP -Table of country codes, latitude and longitude, TZ values, and -descriptive comments. -.TP -\f2TZDIR\fP\f3/\fP\f2TZ\fP -Time zone data file for time zone \f2TZ\fP. -.SH "EXIT STATUS" -The exit status is zero if a time zone was successfully obtained from the user, -nonzero otherwise. -.SH "SEE ALSO" -newctime(3), tzfile(5), zdump(8), zic(8) -.\" @(#)tzselect.8 1.3 diff --git a/commands/zoneinfo/tzselect.8 b/commands/zoneinfo/tzselect.8 new file mode 120000 index 000000000..1e7cb9d56 --- /dev/null +++ b/commands/zoneinfo/tzselect.8 @@ -0,0 +1 @@ +../../man/man8/tzselect.8 \ No newline at end of file diff --git a/commands/zoneinfo/zdump.8 b/commands/zoneinfo/zdump.8 deleted file mode 100644 index b22a12955..000000000 --- a/commands/zoneinfo/zdump.8 +++ /dev/null @@ -1,57 +0,0 @@ -.TH ZDUMP 8 -.SH NAME -zdump \- time zone dumper -.SH SYNOPSIS -.B zdump -[ -.B \-\-version -] -[ -.B \-v -] [ -.B \-c -[loyear,]hiyear ] [ zonename ... ] -.SH DESCRIPTION -.I Zdump -prints the current time in each -.I zonename -named on the command line. -.PP -These options are available: -.TP -.BI "\-\-version" -Output version information and exit. -.TP -.B \-v -For each -.I zonename -on the command line, -print the time at the lowest possible time value, -the time one day after the lowest possible time value, -the times both one second before and exactly at -each detected time discontinuity, -the time at one day less than the highest possible time value, -and the time at the highest possible time value, -Each line ends with -.B isdst=1 -if the given time is Daylight Saving Time or -.B isdst=0 -otherwise. -.TP -.BI "\-c " [loyear,]hiyear -Cut off verbose output near the start of the given year(s). -By default, -the program cuts off verbose output near the starts of the years -500 and 2500. -.SH LIMITATIONS -The -.B \-v -option may not be used on systems with floating-point time_t values -that are neither float nor double. -.PP -Time discontinuities are found by sampling the results returned by localtime -at twelve-hour intervals. -This works in all real-world cases; -one can construct artificial time zones for which this fails. -.SH "SEE ALSO" -newctime(3), tzfile(5), zic(8) -.\" @(#)zdump.8 7.7 diff --git a/commands/zoneinfo/zdump.8 b/commands/zoneinfo/zdump.8 new file mode 120000 index 000000000..5b9dbabaa --- /dev/null +++ b/commands/zoneinfo/zdump.8 @@ -0,0 +1 @@ +../../man/man8/zdump.8 \ No newline at end of file diff --git a/commands/zoneinfo/zic.8 b/commands/zoneinfo/zic.8 deleted file mode 100644 index 8bbdce839..000000000 --- a/commands/zoneinfo/zic.8 +++ /dev/null @@ -1,436 +0,0 @@ -.TH ZIC 8 -.SH NAME -zic \- time zone compiler -.SH SYNOPSIS -.B zic -[ -.B \-\-version -] -[ -.B \-v -] [ -.B \-d -.I directory -] [ -.B \-l -.I localtime -] [ -.B \-p -.I posixrules -] [ -.B \-L -.I leapsecondfilename -] [ -.B \-s -] [ -.B \-y -.I command -] [ -.I filename -\&... ] -.SH DESCRIPTION -.if t .ds lq `` -.if t .ds rq '' -.if n .ds lq \&"\" -.if n .ds rq \&"\" -.de q -\\$3\*(lq\\$1\*(rq\\$2 -.. -.I Zic -reads text from the file(s) named on the command line -and creates the time conversion information files specified in this input. -If a -.I filename -is -.BR \- , -the standard input is read. -.PP -These options are available: -.TP -.BI "\-\-version" -Output version information and exit. -.TP -.BI "\-d " directory -Create time conversion information files in the named directory rather than -in the standard directory named below. -.TP -.BI "\-l " timezone -Use the given time zone as local time. -.I Zic -will act as if the input contained a link line of the form -.sp -.ti +.5i -Link \fItimezone\fP localtime -.TP -.BI "\-p " timezone -Use the given time zone's rules when handling POSIX-format -time zone environment variables. -.I Zic -will act as if the input contained a link line of the form -.sp -.ti +.5i -Link \fItimezone\fP posixrules -.TP -.BI "\-L " leapsecondfilename -Read leap second information from the file with the given name. -If this option is not used, -no leap second information appears in output files. -.TP -.B \-v -Complain if a year that appears in a data file is outside the range -of years representable by -.IR time (2) -values. -Also complain if a time of 24:00 -(which cannot be handled by pre-1998 versions of -.IR zic ) -appears in the input. -.TP -.B \-s -Limit time values stored in output files to values that are the same -whether they're taken to be signed or unsigned. -You can use this option to generate SVVS-compatible files. -.TP -.BI "\-y " command -Use the given -.I command -rather than -.B yearistype -when checking year types (see below). -.PP -Input lines are made up of fields. -Fields are separated from one another by any number of white space characters. -Leading and trailing white space on input lines is ignored. -An unquoted sharp character (#) in the input introduces a comment which extends -to the end of the line the sharp character appears on. -White space characters and sharp characters may be enclosed in double quotes -(") if they're to be used as part of a field. -Any line that is blank (after comment stripping) is ignored. -Non-blank lines are expected to be of one of three types: -rule lines, zone lines, and link lines. -.PP -A rule line has the form -.nf -.ti +.5i -.ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'TYPE\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u -.sp -Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S -.sp -For example: -.ti +.5i -.sp -Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D -.sp -.fi -The fields that make up a rule line are: -.TP "\w'LETTER/S'u" -.B NAME -Gives the (arbitrary) name of the set of rules this rule is part of. -.TP -.B FROM -Gives the first year in which the rule applies. -Any integer year can be supplied; the Gregorian calendar is assumed. -The word -.B minimum -(or an abbreviation) means the minimum year representable as an integer. -The word -.B maximum -(or an abbreviation) means the maximum year representable as an integer. -Rules can describe times that are not representable as time values, -with the unrepresentable times ignored; this allows rules to be portable -among hosts with differing time value types. -.TP -.B TO -Gives the final year in which the rule applies. -In addition to -.B minimum -and -.B maximum -(as above), -the word -.B only -(or an abbreviation) -may be used to repeat the value of the -.B FROM -field. -.TP -.B TYPE -Gives the type of year in which the rule applies. -If -.B TYPE -is -.B \- -then the rule applies in all years between -.B FROM -and -.B TO -inclusive. -If -.B TYPE -is something else, then -.I zic -executes the command -.ti +.5i -\fByearistype\fP \fIyear\fP \fItype\fP -.br -to check the type of a year: -an exit status of zero is taken to mean that the year is of the given type; -an exit status of one is taken to mean that the year is not of the given type. -.TP -.B IN -Names the month in which the rule takes effect. -Month names may be abbreviated. -.TP -.B ON -Gives the day on which the rule takes effect. -Recognized forms include: -.nf -.in +.5i -.sp -.ta \w'Sun<=25\0\0'u -5 the fifth of the month -lastSun the last Sunday in the month -lastMon the last Monday in the month -Sun>=8 first Sunday on or after the eighth -Sun<=25 last Sunday on or before the 25th -.fi -.in -.5i -.sp -Names of days of the week may be abbreviated or spelled out in full. -Note that there must be no spaces within the -.B ON -field. -.TP -.B AT -Gives the time of day at which the rule takes effect. -Recognized forms include: -.nf -.in +.5i -.sp -.ta \w'1:28:13\0\0'u -2 time in hours -2:00 time in hours and minutes -15:00 24-hour format time (for times after noon) -1:28:14 time in hours, minutes, and seconds -\- equivalent to 0 -.fi -.in -.5i -.sp -where hour 0 is midnight at the start of the day, -and hour 24 is midnight at the end of the day. -Any of these forms may be followed by the letter -.B w -if the given time is local -.q "wall clock" -time, -.B s -if the given time is local -.q standard -time, or -.B u -(or -.B g -or -.BR z ) -if the given time is universal time; -in the absence of an indicator, -wall clock time is assumed. -.TP -.B SAVE -Gives 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 -.B AT -field -(although, of course, the -.B w -and -.B s -suffixes are not used). -.TP -.B LETTER/S -Gives the -.q "variable part" -(for example, the -.q S -or -.q D -in -.q EST -or -.q EDT ) -of time zone abbreviations to be used when this rule is in effect. -If this field is -.BR \- , -the variable part is null. -.PP -A zone line has the form -.sp -.nf -.ti +.5i -.ta \w'Zone\0\0'u +\w'Australia/Adelaide\0\0'u +\w'GMTOFF\0\0'u +\w'RULES/SAVE\0\0'u +\w'FORMAT\0\0'u -Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL] -.sp -For example: -.sp -.ti +.5i -Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 -.sp -.fi -The fields that make up a zone line are: -.TP "\w'GMTOFF'u" -.B NAME -The name of the time zone. -This is the name used in creating the time conversion information file for the -zone. -.TP -.B GMTOFF -The amount of time to add to UTC to get standard time in this zone. -This field has the same format as the -.B AT -and -.B SAVE -fields of rule lines; -begin the field with a minus sign if time must be subtracted from UTC. -.TP -.B RULES/SAVE -The name of the rule(s) that apply in the time zone or, -alternately, an amount of time to add to local standard time. -If this field is -.B \- -then standard time always applies in the time zone. -.TP -.B FORMAT -The format for time zone abbreviations in this time zone. -The pair of characters -.B %s -is used to show where the -.q "variable part" -of the time zone abbreviation goes. -Alternately, -a slash (/) -separates standard and daylight abbreviations. -.TP -.B UNTIL -The time at which the UTC offset or the rule(s) change for a location. -It is specified as a year, a month, a day, and a time of day. -If this is specified, -the time zone information is generated from the given UTC offset -and rule change until the time specified. -The month, day, and time of day have the same format as the IN, ON, and AT -columns of a rule; trailing columns can be omitted, and default to the -earliest possible value for the missing columns. -.IP -The next line must be a -.q continuation -line; this has the same form as a zone line except that the -string -.q Zone -and the name are omitted, as the continuation line will -place information starting at the time specified as the -.B UNTIL -field in the previous line in the file used by the previous line. -Continuation lines may contain an -.B UNTIL -field, just as zone lines do, indicating that the next line is a further -continuation. -.PP -A link line has the form -.sp -.nf -.ti +.5i -.ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u -Link LINK-FROM LINK-TO -.sp -For example: -.sp -.ti +.5i -Link Europe/Istanbul Asia/Istanbul -.sp -.fi -The -.B LINK-FROM -field should appear as the -.B NAME -field in some zone line; -the -.B LINK-TO -field is used as an alternate name for that zone. -.PP -Except for continuation lines, -lines may appear in any order in the input. -.PP -Lines in the file that describes leap seconds have the following form: -.nf -.ti +.5i -.ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u -.sp -Leap YEAR MONTH DAY HH:MM:SS CORR R/S -.sp -For example: -.ti +.5i -.sp -Leap 1974 Dec 31 23:59:60 + S -.sp -.fi -The -.BR YEAR , -.BR MONTH , -.BR DAY , -and -.B HH:MM:SS -fields tell when the leap second happened. -The -.B CORR -field -should be -.q + -if a second was added -or -.q - -if a second was skipped. -.\" There's no need to document the following, since it's impossible for more -.\" than one leap second to be inserted or deleted at a time. -.\" The C Standard is in error in suggesting the possibility. -.\" See Terry J Quinn, The BIPM and the accurate measure of time, -.\" Proc IEEE 79, 7 (July 1991), 894-905. -.\" or -.\" .q ++ -.\" if two seconds were added -.\" or -.\" .q -- -.\" if two seconds were skipped. -The -.B R/S -field -should be (an abbreviation of) -.q Stationary -if the leap second time given by the other fields should be interpreted as UTC -or -(an abbreviation of) -.q Rolling -if the leap second time given by the other fields should be interpreted as -local wall clock time. -.SH NOTES -For areas with more than two types of local time, -you may need to use local standard time in the -.B AT -field of the earliest transition time's rule to ensure that -the earliest transition time recorded in the compiled file is correct. -.PP -If, -for a particular zone, -a clock advance caused by the start of daylight saving -coincides with and is equal to -a clock retreat caused by a change in UTC offset, -.IR zic -produces a single transition to daylight saving at the new UTC offset -(without any change in wall clock time). -To get separate transitions -use multiple zone continuation lines -specifying transition instants using universal time. -.SH FILE -/usr/share/zoneinfo standard directory used for created files -.SH "SEE ALSO" -newctime(3), tzfile(5), zdump(8) -.\" @(#)zic.8 7.24 diff --git a/commands/zoneinfo/zic.8 b/commands/zoneinfo/zic.8 new file mode 120000 index 000000000..16448e698 --- /dev/null +++ b/commands/zoneinfo/zic.8 @@ -0,0 +1 @@ +../../man/man8/zic.8 \ No newline at end of file diff --git a/man/man3/newctime.3 b/man/man3/newctime.3 new file mode 100644 index 000000000..fcb554c9c --- /dev/null +++ b/man/man3/newctime.3 @@ -0,0 +1,237 @@ +.TH NEWCTIME 3 +.SH NAME +asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time to ASCII +.SH SYNOPSIS +.nf +.B extern char *tzname[2]; +.PP +.B void tzset() +.PP +.B #include +.PP +.B char *ctime(clock) +.B const time_t *clock; +.PP +.B double difftime(time1, time0) +.B time_t time1; +.B time_t time0; +.PP +.B #include +.PP +.B char *asctime(tm) +.B const struct tm *tm; +.PP +.B struct tm *localtime(clock) +.B const time_t *clock; +.PP +.B struct tm *gmtime(clock) +.B const time_t *clock; +.PP +.B time_t mktime(tm) +.B struct tm *tm; +.PP +.B cc ... -ltz +.fi +.SH DESCRIPTION +.I Ctime\^ +converts a long integer, pointed to by +.IR clock , +representing the time in seconds since +00:00:00 UTC, 1970-01-01, +and returns a pointer to a +string of the form +.br +.ce +.eo +Thu Nov 24 18:22:48 1986\n\0 +.br +.ec +Years requiring fewer than four characters are padded with leading zeroes. +For years longer than four characters, the string is of the form +.br +.ce +.eo +Thu Nov 24 18:22:48 81986\n\0 +.ec +.br +with five spaces before the year. +These unusual formats are designed to make it less likely that older +software that expects exactly 26 bytes of output will mistakenly output +misleading values for out-of-range years. +.PP +.I Localtime\^ +and +.I gmtime\^ +return pointers to ``tm'' structures, described below. +.I Localtime\^ +corrects for the time zone and any time zone adjustments +(such as Daylight Saving Time in the United States). +After filling in the ``tm'' structure, +.I localtime +sets the +.BR tm_isdst 'th +element of +.B tzname +to a pointer to an +ASCII string that's the time zone abbreviation to be used with +.IR localtime 's +return value. +.PP +.I Gmtime\^ +converts to Coordinated Universal Time. +.PP +.I Asctime\^ +converts a time value contained in a +``tm'' structure to a string, +as shown in the above example, +and returns a pointer to the string. +.PP +.I Mktime\^ +converts the broken-down time, +expressed as local time, +in the structure pointed to by +.I tm +into a calendar time value with the same encoding as that of the values +returned by the +.I time +function. +The original values of the +.B tm_wday +and +.B tm_yday +components of the structure are ignored, +and the original values of the other components are not restricted +to their normal ranges. +(A positive or zero value for +.B tm_isdst +causes +.I mktime +to presume initially that summer time (for example, Daylight Saving Time +in the U.S.A.) +respectively, +is or is not in effect for the specified time. +A negative value for +.B tm_isdst +causes the +.I mktime +function to attempt to divine whether summer time is in effect +for the specified time.) +On successful completion, the values of the +.B tm_wday +and +.B tm_yday +components of the structure are set appropriately, +and the other components are set to represent the specified calendar time, +but with their values forced to their normal ranges; the final value of +.B tm_mday +is not set until +.B tm_mon +and +.B tm_year +are determined. +.I Mktime\^ +returns the specified calendar time; +If the calendar time cannot be represented, +it returns +.BR -1 . +.PP +.I Difftime\^ +returns the difference between two calendar times, +.RI ( time1 +- +.IR time0 ), +expressed in seconds. +.PP +Declarations of all the functions and externals, and the ``tm'' structure, +are in the +.B \^ +header file. +The structure (of type) +.B struct tm +includes the following fields: +.RS +.PP +.nf +.ta .5i +\w'long tm_gmtoff;\0\0'u + int tm_sec; /\(** seconds (0 - 60) \(**/ + int tm_min; /\(** minutes (0 - 59) \(**/ + int tm_hour; /\(** hours (0 - 23) \(**/ + int tm_mday; /\(** day of month (1 - 31) \(**/ + int tm_mon; /\(** month of year (0 - 11) \(**/ + int tm_year; /\(** year \- 1900 \(**/ + int tm_wday; /\(** day of week (Sunday = 0) \(**/ + int tm_yday; /\(** day of year (0 - 365) \(**/ + int tm_isdst; /\(** is summer time in effect? \(**/ + char \(**tm_zone; /\(** abbreviation of timezone name \(**/ + long tm_gmtoff; /\(** offset from UTC in seconds \(**/ +.fi +.RE +.PP +The +.I tm_zone +and +.I tm_gmtoff +fields exist, and are filled in, only if arrangements to do +so were made when the library containing these functions was +created. +There is no guarantee that these fields will continue to exist +in this form in future releases of this code. +.PP +.I Tm_isdst\^ +is non-zero if summer time is in effect. +.PP +.I Tm_gmtoff +is the offset (in seconds) of the time represented +from UTC, with positive values indicating east +of the Prime Meridian. +.SH FILES +.ta \w'/usr/share/zoneinfo/posixrules\0\0'u +/usr/share/zoneinfo time zone information directory +.br +/usr/share/zoneinfo/localtime local time zone file +.br +/usr/share/zoneinfo/posixrules used with POSIX-style TZ's +.br +/usr/share/zoneinfo/GMT for UTC leap seconds +.sp +If +.B /usr/share/zoneinfo/GMT +is absent, +UTC leap seconds are loaded from +.BR /usr/share/zoneinfo/posixrules . +.SH SEE ALSO +getenv(3), +newstrftime(3), +newtzset(3), +time(2), +tzfile(5) +.SH NOTES +The return values point to static data; +the data is overwritten by each call. +The +.B tm_zone +field of a returned +.B "struct tm" +points to a static array of characters, which +will also be overwritten at the next call +(and by calls to +.IR tzset ). +.PP +.I Asctime\^ +and +.I ctime\^ +behave strangely for years before 1000 or after 9999. +The 1989 and 1999 editions of the C Standard say +that years from \-99 through 999 are converted without +extra spaces, but this conflicts with longstanding +tradition and with this implementation. +Traditional implementations of these two functions are +restricted to years in the range 1900 through 2099. +To avoid this portability mess, new programs should use +.I strftime\^ +instead. +.PP +Avoid using out-of-range values with +.I mktime +when setting up lunch with promptness sticklers in Riyadh. +.\" @(#)newctime.3 7.17 diff --git a/man/man3/newstrftime.3 b/man/man3/newstrftime.3 new file mode 100644 index 000000000..19db8ea14 --- /dev/null +++ b/man/man3/newstrftime.3 @@ -0,0 +1,230 @@ +.\" Based on the UCB file whose copyright information appears below. +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strftime.3 5.12 (Berkeley) 6/29/91 +.\" $Id: strftime.3,v 1.4 1993/12/15 20:33:00 jtc Exp $ +.\" +.TH NEWSTRFTIME 3 +.SH NAME +strftime \- format date and time +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.B size_t strftime(buf, maxsize, format, timeptr) +.B char *buf; +.B size_t maxsize; +.B const char *format; +.B const struct tm *timeptr +.PP +.B cc ... -ltz +.fi +.SH DESCRIPTION +The +.I strftime\^ +function formats the information from +.I timeptr\^ +into the buffer +.I buf\^ +according to the string pointed to by +.IR format\^ . +.PP +The +.I format\^ +string consists of zero or more conversion specifications and +ordinary characters. +All ordinary characters are copied directly into the buffer. +A conversion specification consists of a percent sign +.Ql % +and one other character. +.PP +No more than +.I maxsize\^ +characters are be placed into the array. +If the total number of resulting characters, including the terminating +null character, is not more than +.IR maxsize\^ , +.I strftime\^ +returns the number of characters in the array, not counting the +terminating null. +Otherwise, zero is returned. +.PP +Each conversion specification is replaced by the characters as +follows which are then copied into the buffer. +.TP +%A +is replaced by the locale's full weekday name. +.TP +%a +is replaced by the locale's abbreviated weekday name. +.TP +%B +is replaced by the locale's full month name. +.TP +%b or %h +is replaced by the locale's abbreviated month name. +.TP +%C +is replaced by the century (a year divided by 100 and truncated to an integer) +as a decimal number (00-99). +.TP +%c +is replaced by the locale's appropriate date and time representation. +.TP +%D +is replaced by the date in the format %m/%d/%y. +.TP +%d +is replaced by the day of the month as a decimal number (01-31). +.TP +%e +is replaced by the day of month as a decimal number (1-31); +single digits are preceded by a blank. +.TP +%F +is replaced by the date in the format %Y-%m-%d. +.TP +%G +is replaced by the ISO 8601 year with century as a decimal number. +.TP +%g +is replaced by the ISO 8601 year without century as a decimal number (00-99). +.TP +%H +is replaced by the hour (24-hour clock) as a decimal number (00-23). +.TP +%I +is replaced by the hour (12-hour clock) as a decimal number (01-12). +.TP +%j +is replaced by the day of the year as a decimal number (001-366). +.TP +%k +is replaced by the hour (24-hour clock) as a decimal number (0-23); +single digits are preceded by a blank. +.TP +%l +is replaced by the hour (12-hour clock) as a decimal number (1-12); +single digits are preceded by a blank. +.TP +%M +is replaced by the minute as a decimal number (00-59). +.TP +%m +is replaced by the month as a decimal number (01-12). +.TP +%n +is replaced by a newline. +.TP +%p +is replaced by the locale's equivalent of either AM or PM. +.TP +%R +is replaced by the time in the format %H:%M. +.TP +%r +is replaced by the locale's representation of 12-hour clock time +using AM/PM notation. +.TP +%S +is replaced by the second as a decimal number (00-60). +.TP +%s +is replaced by the number of seconds since the Epoch, UTC (see mktime(3)). +.TP +%T +is replaced by the time in the format %H:%M:%S. +.TP +%t +is replaced by a tab. +.TP +%U +is replaced by the week number of the year (Sunday as the first day of +the week) as a decimal number (00-53). +.TP +%u +is replaced by the weekday (Monday as the first day of the week) +as a decimal number (1-7). +.TP +%V +is replaced by the week number of the year (Monday as the first day of +the week) as a decimal number (01-53). If the week containing January +1 has four or more days in the new year, then it is week 1; otherwise +it is week 53 of the previous year, and the next week is week 1. +.TP +%W +is replaced by the week number of the year (Monday as the first day of +the week) as a decimal number (00-53). +.TP +%w +is replaced by the weekday (Sunday as the first day of the week) +as a decimal number (0-6). +.TP +%X +is replaced by the locale's appropriate time representation. +.TP +%x +is replaced by the locale's appropriate date representation. +.TP +%Y +is replaced by the year with century as a decimal number. +.TP +%y +is replaced by the year without century as a decimal number (00-99). +.TP +%Z +is replaced by the time zone name, +or by the empty string if this is not determinable. +.TP +%z +is replaced by the offset from UTC in the format +HHMM or -HHMM as appropriate, +with positive values representing locations east of Greenwich, +or by the empty string if this is not determinable. +.TP +%% +is replaced by a single %. +.TP +%+ +is replaced by the date and time in date(1) format. +.SH SEE ALSO +date(1), +getenv(3), +newctime(3), +newtzset(3), +time(2), +tzfile(5) +.\" @(#)newstrftime.3 7.15 diff --git a/man/man3/newtzset.3 b/man/man3/newtzset.3 new file mode 100644 index 000000000..ea512447a --- /dev/null +++ b/man/man3/newtzset.3 @@ -0,0 +1,237 @@ +.TH NEWTZSET 3 +.SH NAME +tzset \- initialize time conversion information +.SH SYNOPSIS +.nf +.B void tzset() +.PP +.B cc ... -ltz +.fi +.SH DESCRIPTION +.I Tzset +uses the value of the environment variable +.B TZ +to set time conversion information used by +.IR localtime . +If +.B TZ +does not appear in the environment, +the best available approximation to local wall clock time, as specified +by the +.IR tzfile (5)-format +file +.B localtime +in the system time conversion information directory, is used by +.IR localtime . +If +.B TZ +appears in the environment but its value is a null string, +Coordinated Universal Time (UTC) is used (without leap second +correction). If +.B TZ +appears in the environment and its value is not a null string: +.IP +if the value begins with a colon, it is used as a pathname of a file +from which to read the time conversion information; +.IP +if the value does not begin with a colon, it is first used as the +pathname of a file from which to read the time conversion information, +and, if that file cannot be read, is used directly as a specification of +the time conversion information. +.PP +When +.B TZ +is used as a pathname, if it begins with a slash, +it is used as an absolute pathname; otherwise, +it is used as a pathname relative to a system time conversion information +directory. +The file must be in the format specified in +.IR tzfile (5). +.PP +When +.B TZ +is used directly as a specification of the time conversion information, +it must have the following syntax (spaces inserted for clarity): +.IP +\fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]] +.PP +Where: +.RS +.TP 15 +.IR std " and " dst +Three or more bytes that are the designation for the standard +.RI ( std ) +or summer +.RI ( dst ) +time zone. Only +.I std +is required; if +.I dst +is missing, then summer time does not apply in this locale. +Upper- and lowercase letters are explicitly allowed. Any characters +except a leading colon +.RB ( : ), +digits, comma +.RB ( , ), +minus +.RB ( \(mi ), +plus +.RB ( \(pl ), +and ASCII NUL are allowed. +.TP +.I offset +Indicates the value one must add to the local time to arrive at +Coordinated Universal Time. The +.I offset +has the form: +.RS +.IP +\fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]] +.RE +.IP +The minutes +.RI ( mm ) +and seconds +.RI ( ss ) +are optional. The hour +.RI ( hh ) +is required and may be a single digit. The +.I offset +following +.I std +is required. If no +.I offset +follows +.IR dst , +summer time is assumed to be one hour ahead of standard time. One or +more digits may be used; the value is always interpreted as a decimal +number. The hour must be between zero and 24, and the minutes (and +seconds) \(em if present \(em between zero and 59. If preceded by a +.RB `` \(mi '', +the time zone shall be east of the Prime Meridian; otherwise it shall be +west (which may be indicated by an optional preceding +.RB `` \(pl ''). +.TP +.I rule +Indicates when to change to and back from summer time. The +.I rule +has the form: +.RS +.IP +\fIdate\fB/\fItime\fB,\fIdate\fB/\fItime\fR +.RE +.IP +where the first +.I date +describes when the change from standard to summer time occurs and the +second +.I date +describes when the change back happens. Each +.I time +field describes when, in current local time, the change to the other +time is made. +.IP +The format of +.I date +is one of the following: +.RS +.TP 10 +.BI J n +The Julian day +.I n +.RI "(1\ \(<=" "\ n\ " "\(<=\ 365). +Leap days are not counted; that is, in all years \(em including leap +years \(em February 28 is day 59 and March 1 is day 60. It is +impossible to explicitly refer to the occasional February 29. +.TP +.I n +The zero-based Julian day +.RI "(0\ \(<=" "\ n\ " "\(<=\ 365). +Leap days are counted, and it is possible to refer to February 29. +.TP +.BI M m . n . d +The +.IR d' th +day +.RI "(0\ \(<=" "\ d\ " "\(<=\ 6) +of week +.I n +of month +.I m +of the year +.RI "(1\ \(<=" "\ n\ " "\(<=\ 5, +.RI "1\ \(<=" "\ m\ " "\(<=\ 12, +where week 5 means ``the last +.I d +day in month +.IR m '' +which may occur in either the fourth or the fifth week). Week 1 is the +first week in which the +.IR d' th +day occurs. Day zero is Sunday. +.RE +.IP "" 15 +The +.I time +has the same format as +.I offset +except that no leading sign +.RB (`` \(mi '' +or +.RB `` \(pl '') +is allowed. The default, if +.I time +is not given, is +.BR 02:00:00 . +.RE +.LP +If no +.I rule +is present in +.BR TZ , +the rules specified +by the +.IR tzfile (5)-format +file +.B posixrules +in the system time conversion information directory are used, with the +standard and summer time offsets from UTC replaced by those specified by +the +.I offset +values in +.BR TZ . +.PP +For compatibility with System V Release 3.1, a semicolon +.RB ( ; ) +may be used to separate the +.I rule +from the rest of the specification. +.PP +If the +.B TZ +environment variable does not specify a +.IR tzfile (5)-format +and cannot be interpreted as a direct specification, +UTC is used. +.SH FILES +.ta \w'/usr/share/zoneinfo/posixrules\0\0'u +/usr/share/zoneinfo time zone information directory +.br +/usr/share/zoneinfo/localtime local time zone file +.br +/usr/share/zoneinfo/posixrules used with POSIX-style TZ's +.br +/usr/share/zoneinfo/GMT for UTC leap seconds +.sp +If +.B /usr/share/zoneinfo/GMT +is absent, +UTC leap seconds are loaded from +.BR /usr/share/zoneinfo/posixrules . +.SH SEE ALSO +getenv(3), +newctime(3), +newstrftime(3), +time(2), +tzfile(5) +.\" @(#)newtzset.3 7.5 diff --git a/man/man3/time2posix.3 b/man/man3/time2posix.3 new file mode 100644 index 000000000..3ce2e0ee7 --- /dev/null +++ b/man/man3/time2posix.3 @@ -0,0 +1,121 @@ +.TH TIME2POSIX 3 +.SH NAME +time2posix, posix2time \- convert seconds since the Epoch +.SH SYNOPSIS +.nf +.B #include +.B #include +.PP +.B time_t time2posix(t) +.B time_t t +.PP +.B time_t posix2time(t) +.B time_t t +.PP +.B cc ... -ltz +.fi +.SH DESCRIPTION +IEEE Standard 1003.1 +(POSIX) +legislates that a time_t value of +536457599 shall correspond to "Wed Dec 31 23:59:59 UTC 1986." +This effectively implies that POSIX time_t's cannot include leap +seconds and, +therefore, +that the system time must be adjusted as each leap occurs. +.PP +If the time package is configured with leap-second support +enabled, +however, +no such adjustment is needed and +time_t values continue to increase over leap events +(as a true `seconds since...' value). +This means that these values will differ from those required by POSIX +by the net number of leap seconds inserted since the Epoch. +.PP +Typically this is not a problem as the type time_t is intended +to be +(mostly) +opaque\(emtime_t values should only be obtained-from and +passed-to functions such as +.IR time(2) , +.IR localtime(3) , +.IR mktime(3) , +and +.IR difftime(3) . +However, +POSIX gives an arithmetic +expression for directly computing a time_t value from a given date/time, +and the same relationship is assumed by some +(usually older) +applications. +Any programs creating/dissecting time_t's +using such a relationship will typically not handle intervals +over leap seconds correctly. +.PP +The +.I time2posix +and +.I posix2time +functions are provided to address this time_t mismatch by converting +between local time_t values and their POSIX equivalents. +This is done by accounting for the number of time-base changes that +would have taken place on a POSIX system as leap seconds were inserted +or deleted. +These converted values can then be used in lieu of correcting the older +applications, +or when communicating with POSIX-compliant systems. +.PP +.I Time2posix +is single-valued. +That is, +every local time_t +corresponds to a single POSIX time_t. +.I Posix2time +is less well-behaved: +for a positive leap second hit the result is not unique, +and for a negative leap second hit the corresponding +POSIX time_t doesn't exist so an adjacent value is returned. +Both of these are good indicators of the inferiority of the +POSIX representation. +.PP +The following table summarizes the relationship between a time +T and it's conversion to, +and back from, +the POSIX representation over the leap second inserted at the end of June, +1993. +.nf +.ta \w'93/06/30 'u +\w'23:59:59 'u +\w'A+0 'u +\w'X=time2posix(T) 'u +DATE TIME T X=time2posix(T) posix2time(X) +93/06/30 23:59:59 A+0 B+0 A+0 +93/06/30 23:59:60 A+1 B+1 A+1 or A+2 +93/07/01 00:00:00 A+2 B+1 A+1 or A+2 +93/07/01 00:00:01 A+3 B+2 A+3 + +A leap second deletion would look like... + +DATE TIME T X=time2posix(T) posix2time(X) +??/06/30 23:59:58 A+0 B+0 A+0 +??/07/01 00:00:00 A+1 B+2 A+1 +??/07/01 00:00:01 A+2 B+3 A+2 +.sp +.ce + [Note: posix2time(B+1) => A+0 or A+1] +.fi +.PP +If leap-second support is not enabled, +local time_t's and +POSIX time_t's are equivalent, +and both +.I time2posix +and +.I posix2time +degenerate to the identity function. +.SH SEE ALSO +difftime(3), +localtime(3), +mktime(3), +time(2) +.\" @(#)time2posix.3 7.8 +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson. diff --git a/man/man5/tzfile.5 b/man/man5/tzfile.5 new file mode 100644 index 000000000..ceb6a77b3 --- /dev/null +++ b/man/man5/tzfile.5 @@ -0,0 +1,138 @@ +.TH TZFILE 5 +.SH NAME +tzfile \- time zone information +.SH SYNOPSIS +.B +#include +.SH DESCRIPTION +The time zone information files used by +.IR tzset (3) +begin with the magic characters "TZif" to identify then as +time zone information files, +followed by sixteen bytes reserved for future use, +followed by six four-byte values of type +.BR long , +written in a ``standard'' byte order +(the high-order byte of the value is written first). +These values are, +in order: +.TP +.I tzh_ttisgmtcnt +The number of UTC/local indicators stored in the file. +.TP +.I tzh_ttisstdcnt +The number of standard/wall indicators stored in the file. +.TP +.I tzh_leapcnt +The number of leap seconds for which data is stored in the file. +.TP +.I tzh_timecnt +The number of "transition times" for which data is stored +in the file. +.TP +.I tzh_typecnt +The number of "local time types" for which data is stored +in the file (must not be zero). +.TP +.I tzh_charcnt +The number of characters of "time zone abbreviation strings" +stored in the file. +.PP +The above header is followed by +.I tzh_timecnt +four-byte values of type +.BR long , +sorted in ascending order. +These values are written in ``standard'' byte order. +Each is used as a transition time (as returned by +.IR time (2)) +at which the rules for computing local time change. +Next come +.I tzh_timecnt +one-byte values of type +.BR "unsigned char" ; +each one tells which of the different types of ``local time'' types +described in the file is associated with the same-indexed transition time. +These values serve as indices into an array of +.I ttinfo +structures that appears next in the file; +these structures are defined as follows: +.in +.5i +.sp +.nf +.ta .5i +\w'unsigned int\0\0'u +struct ttinfo { + long tt_gmtoff; + int tt_isdst; + unsigned int tt_abbrind; +}; +.in -.5i +.fi +.sp +Each structure is written as a four-byte value for +.I tt_gmtoff +of type +.BR long , +in a standard byte order, followed by a one-byte value for +.I tt_isdst +and a one-byte value for +.IR tt_abbrind . +In each structure, +.I tt_gmtoff +gives the number of seconds to be added to UTC, +.I tt_isdst +tells whether +.I tm_isdst +should be set by +.I localtime (3) +and +.I tt_abbrind +serves as an index into the array of time zone abbreviation characters +that follow the +.I ttinfo +structure(s) in the file. +.PP +Then there are +.I tzh_leapcnt +pairs of four-byte values, written in standard byte order; +the first value of each pair gives the time +(as returned by +.IR time(2)) +at which a leap second occurs; +the second gives the +.I total +number of leap seconds to be applied after the given time. +The pairs of values are sorted in ascending order by time. +.PP +Then there are +.I tzh_ttisstdcnt +standard/wall indicators, each stored as a one-byte value; +they tell whether the transition times associated with local time types +were specified as standard time or wall clock time, +and are used when a time zone file is used in handling POSIX-style +time zone environment variables. +.PP +Finally there are +.I tzh_ttisgmtcnt +UTC/local indicators, each stored as a one-byte value; +they tell whether the transition times associated with local time types +were specified as UTC or local time, +and are used when a time zone file is used in handling POSIX-style +time zone environment variables. +.PP +.I Localtime +uses the first standard-time +.I ttinfo +structure in the file +(or simply the first +.I ttinfo +structure in the absence of a standard-time structure) +if either +.I tzh_timecnt +is zero or the time argument is less than the first transition time recorded +in the file. +.SH SEE ALSO +newctime(3) +.\" @(#)tzfile.5 7.12 +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson. diff --git a/man/man8/tzselect.8 b/man/man8/tzselect.8 new file mode 100644 index 000000000..f839ed828 --- /dev/null +++ b/man/man8/tzselect.8 @@ -0,0 +1,41 @@ +.TH TZSELECT 8 +.SH NAME +tzselect \- select a time zone +.SH SYNOPSIS +.B tzselect +.SH DESCRIPTION +The +.B tzselect +program asks the user for information about the current location, +and outputs the resulting time zone description to standard output. +The output is suitable as a value for the TZ environment variable. +.PP +All interaction with the user is done via standard input and standard error. +.SH "ENVIRONMENT VARIABLES" +.TP +\f3AWK\fP +Name of a Posix-compliant +.I awk +program (default: +.BR awk ). +.TP +\f3TZDIR\fP +Name of the directory containing time zone data files (default: +.BR /usr/share/zoneinfo ). +.SH FILES +.TP +\f2TZDIR\fP\f3/iso3166.tab\fP +Table of ISO 3166 2-letter country codes and country names. +.TP +\f2TZDIR\fP\f3/zone.tab\fP +Table of country codes, latitude and longitude, TZ values, and +descriptive comments. +.TP +\f2TZDIR\fP\f3/\fP\f2TZ\fP +Time zone data file for time zone \f2TZ\fP. +.SH "EXIT STATUS" +The exit status is zero if a time zone was successfully obtained from the user, +nonzero otherwise. +.SH "SEE ALSO" +newctime(3), tzfile(5), zdump(8), zic(8) +.\" @(#)tzselect.8 1.3 diff --git a/man/man8/zdump.8 b/man/man8/zdump.8 new file mode 100644 index 000000000..b22a12955 --- /dev/null +++ b/man/man8/zdump.8 @@ -0,0 +1,57 @@ +.TH ZDUMP 8 +.SH NAME +zdump \- time zone dumper +.SH SYNOPSIS +.B zdump +[ +.B \-\-version +] +[ +.B \-v +] [ +.B \-c +[loyear,]hiyear ] [ zonename ... ] +.SH DESCRIPTION +.I Zdump +prints the current time in each +.I zonename +named on the command line. +.PP +These options are available: +.TP +.BI "\-\-version" +Output version information and exit. +.TP +.B \-v +For each +.I zonename +on the command line, +print the time at the lowest possible time value, +the time one day after the lowest possible time value, +the times both one second before and exactly at +each detected time discontinuity, +the time at one day less than the highest possible time value, +and the time at the highest possible time value, +Each line ends with +.B isdst=1 +if the given time is Daylight Saving Time or +.B isdst=0 +otherwise. +.TP +.BI "\-c " [loyear,]hiyear +Cut off verbose output near the start of the given year(s). +By default, +the program cuts off verbose output near the starts of the years -500 and 2500. +.SH LIMITATIONS +The +.B \-v +option may not be used on systems with floating-point time_t values +that are neither float nor double. +.PP +Time discontinuities are found by sampling the results returned by localtime +at twelve-hour intervals. +This works in all real-world cases; +one can construct artificial time zones for which this fails. +.SH "SEE ALSO" +newctime(3), tzfile(5), zic(8) +.\" @(#)zdump.8 7.7 diff --git a/man/man8/zic.8 b/man/man8/zic.8 new file mode 100644 index 000000000..8bbdce839 --- /dev/null +++ b/man/man8/zic.8 @@ -0,0 +1,436 @@ +.TH ZIC 8 +.SH NAME +zic \- time zone compiler +.SH SYNOPSIS +.B zic +[ +.B \-\-version +] +[ +.B \-v +] [ +.B \-d +.I directory +] [ +.B \-l +.I localtime +] [ +.B \-p +.I posixrules +] [ +.B \-L +.I leapsecondfilename +] [ +.B \-s +] [ +.B \-y +.I command +] [ +.I filename +\&... ] +.SH DESCRIPTION +.if t .ds lq `` +.if t .ds rq '' +.if n .ds lq \&"\" +.if n .ds rq \&"\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +.I Zic +reads text from the file(s) named on the command line +and creates the time conversion information files specified in this input. +If a +.I filename +is +.BR \- , +the standard input is read. +.PP +These options are available: +.TP +.BI "\-\-version" +Output version information and exit. +.TP +.BI "\-d " directory +Create time conversion information files in the named directory rather than +in the standard directory named below. +.TP +.BI "\-l " timezone +Use the given time zone as local time. +.I Zic +will act as if the input contained a link line of the form +.sp +.ti +.5i +Link \fItimezone\fP localtime +.TP +.BI "\-p " timezone +Use the given time zone's rules when handling POSIX-format +time zone environment variables. +.I Zic +will act as if the input contained a link line of the form +.sp +.ti +.5i +Link \fItimezone\fP posixrules +.TP +.BI "\-L " leapsecondfilename +Read leap second information from the file with the given name. +If this option is not used, +no leap second information appears in output files. +.TP +.B \-v +Complain if a year that appears in a data file is outside the range +of years representable by +.IR time (2) +values. +Also complain if a time of 24:00 +(which cannot be handled by pre-1998 versions of +.IR zic ) +appears in the input. +.TP +.B \-s +Limit time values stored in output files to values that are the same +whether they're taken to be signed or unsigned. +You can use this option to generate SVVS-compatible files. +.TP +.BI "\-y " command +Use the given +.I command +rather than +.B yearistype +when checking year types (see below). +.PP +Input lines are made up of fields. +Fields are separated from one another by any number of white space characters. +Leading and trailing white space on input lines is ignored. +An unquoted sharp character (#) in the input introduces a comment which extends +to the end of the line the sharp character appears on. +White space characters and sharp characters may be enclosed in double quotes +(") if they're to be used as part of a field. +Any line that is blank (after comment stripping) is ignored. +Non-blank lines are expected to be of one of three types: +rule lines, zone lines, and link lines. +.PP +A rule line has the form +.nf +.ti +.5i +.ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'TYPE\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u +.sp +Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S +.sp +For example: +.ti +.5i +.sp +Rule US 1967 1973 \- Apr lastSun 2:00 1:00 D +.sp +.fi +The fields that make up a rule line are: +.TP "\w'LETTER/S'u" +.B NAME +Gives the (arbitrary) name of the set of rules this rule is part of. +.TP +.B FROM +Gives the first year in which the rule applies. +Any integer year can be supplied; the Gregorian calendar is assumed. +The word +.B minimum +(or an abbreviation) means the minimum year representable as an integer. +The word +.B maximum +(or an abbreviation) means the maximum year representable as an integer. +Rules can describe times that are not representable as time values, +with the unrepresentable times ignored; this allows rules to be portable +among hosts with differing time value types. +.TP +.B TO +Gives the final year in which the rule applies. +In addition to +.B minimum +and +.B maximum +(as above), +the word +.B only +(or an abbreviation) +may be used to repeat the value of the +.B FROM +field. +.TP +.B TYPE +Gives the type of year in which the rule applies. +If +.B TYPE +is +.B \- +then the rule applies in all years between +.B FROM +and +.B TO +inclusive. +If +.B TYPE +is something else, then +.I zic +executes the command +.ti +.5i +\fByearistype\fP \fIyear\fP \fItype\fP +.br +to check the type of a year: +an exit status of zero is taken to mean that the year is of the given type; +an exit status of one is taken to mean that the year is not of the given type. +.TP +.B IN +Names the month in which the rule takes effect. +Month names may be abbreviated. +.TP +.B ON +Gives the day on which the rule takes effect. +Recognized forms include: +.nf +.in +.5i +.sp +.ta \w'Sun<=25\0\0'u +5 the fifth of the month +lastSun the last Sunday in the month +lastMon the last Monday in the month +Sun>=8 first Sunday on or after the eighth +Sun<=25 last Sunday on or before the 25th +.fi +.in -.5i +.sp +Names of days of the week may be abbreviated or spelled out in full. +Note that there must be no spaces within the +.B ON +field. +.TP +.B AT +Gives the time of day at which the rule takes effect. +Recognized forms include: +.nf +.in +.5i +.sp +.ta \w'1:28:13\0\0'u +2 time in hours +2:00 time in hours and minutes +15:00 24-hour format time (for times after noon) +1:28:14 time in hours, minutes, and seconds +\- equivalent to 0 +.fi +.in -.5i +.sp +where hour 0 is midnight at the start of the day, +and hour 24 is midnight at the end of the day. +Any of these forms may be followed by the letter +.B w +if the given time is local +.q "wall clock" +time, +.B s +if the given time is local +.q standard +time, or +.B u +(or +.B g +or +.BR z ) +if the given time is universal time; +in the absence of an indicator, +wall clock time is assumed. +.TP +.B SAVE +Gives 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 +.B AT +field +(although, of course, the +.B w +and +.B s +suffixes are not used). +.TP +.B LETTER/S +Gives the +.q "variable part" +(for example, the +.q S +or +.q D +in +.q EST +or +.q EDT ) +of time zone abbreviations to be used when this rule is in effect. +If this field is +.BR \- , +the variable part is null. +.PP +A zone line has the form +.sp +.nf +.ti +.5i +.ta \w'Zone\0\0'u +\w'Australia/Adelaide\0\0'u +\w'GMTOFF\0\0'u +\w'RULES/SAVE\0\0'u +\w'FORMAT\0\0'u +Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL] +.sp +For example: +.sp +.ti +.5i +Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 +.sp +.fi +The fields that make up a zone line are: +.TP "\w'GMTOFF'u" +.B NAME +The name of the time zone. +This is the name used in creating the time conversion information file for the +zone. +.TP +.B GMTOFF +The amount of time to add to UTC to get standard time in this zone. +This field has the same format as the +.B AT +and +.B SAVE +fields of rule lines; +begin the field with a minus sign if time must be subtracted from UTC. +.TP +.B RULES/SAVE +The name of the rule(s) that apply in the time zone or, +alternately, an amount of time to add to local standard time. +If this field is +.B \- +then standard time always applies in the time zone. +.TP +.B FORMAT +The format for time zone abbreviations in this time zone. +The pair of characters +.B %s +is used to show where the +.q "variable part" +of the time zone abbreviation goes. +Alternately, +a slash (/) +separates standard and daylight abbreviations. +.TP +.B UNTIL +The time at which the UTC offset or the rule(s) change for a location. +It is specified as a year, a month, a day, and a time of day. +If this is specified, +the time zone information is generated from the given UTC offset +and rule change until the time specified. +The month, day, and time of day have the same format as the IN, ON, and AT +columns of a rule; trailing columns can be omitted, and default to the +earliest possible value for the missing columns. +.IP +The next line must be a +.q continuation +line; this has the same form as a zone line except that the +string +.q Zone +and the name are omitted, as the continuation line will +place information starting at the time specified as the +.B UNTIL +field in the previous line in the file used by the previous line. +Continuation lines may contain an +.B UNTIL +field, just as zone lines do, indicating that the next line is a further +continuation. +.PP +A link line has the form +.sp +.nf +.ti +.5i +.ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u +Link LINK-FROM LINK-TO +.sp +For example: +.sp +.ti +.5i +Link Europe/Istanbul Asia/Istanbul +.sp +.fi +The +.B LINK-FROM +field should appear as the +.B NAME +field in some zone line; +the +.B LINK-TO +field is used as an alternate name for that zone. +.PP +Except for continuation lines, +lines may appear in any order in the input. +.PP +Lines in the file that describes leap seconds have the following form: +.nf +.ti +.5i +.ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u +.sp +Leap YEAR MONTH DAY HH:MM:SS CORR R/S +.sp +For example: +.ti +.5i +.sp +Leap 1974 Dec 31 23:59:60 + S +.sp +.fi +The +.BR YEAR , +.BR MONTH , +.BR DAY , +and +.B HH:MM:SS +fields tell when the leap second happened. +The +.B CORR +field +should be +.q + +if a second was added +or +.q - +if a second was skipped. +.\" There's no need to document the following, since it's impossible for more +.\" than one leap second to be inserted or deleted at a time. +.\" The C Standard is in error in suggesting the possibility. +.\" See Terry J Quinn, The BIPM and the accurate measure of time, +.\" Proc IEEE 79, 7 (July 1991), 894-905. +.\" or +.\" .q ++ +.\" if two seconds were added +.\" or +.\" .q -- +.\" if two seconds were skipped. +The +.B R/S +field +should be (an abbreviation of) +.q Stationary +if the leap second time given by the other fields should be interpreted as UTC +or +(an abbreviation of) +.q Rolling +if the leap second time given by the other fields should be interpreted as +local wall clock time. +.SH NOTES +For areas with more than two types of local time, +you may need to use local standard time in the +.B AT +field of the earliest transition time's rule to ensure that +the earliest transition time recorded in the compiled file is correct. +.PP +If, +for a particular zone, +a clock advance caused by the start of daylight saving +coincides with and is equal to +a clock retreat caused by a change in UTC offset, +.IR zic +produces a single transition to daylight saving at the new UTC offset +(without any change in wall clock time). +To get separate transitions +use multiple zone continuation lines +specifying transition instants using universal time. +.SH FILE +/usr/share/zoneinfo standard directory used for created files +.SH "SEE ALSO" +newctime(3), tzfile(5), zdump(8) +.\" @(#)zic.8 7.24 -- 2.44.0