diff options
Diffstat (limited to 'doc/clock.n')
| -rw-r--r-- | doc/clock.n | 346 |
1 files changed, 213 insertions, 133 deletions
diff --git a/doc/clock.n b/doc/clock.n index 3f19644..42dca80 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -2,25 +2,25 @@ '\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. '\" -.so man.macros .TH "clock" n 8.5 Tcl "Tcl Built-In Commands" +.so man.macros .BS -.SH "NAME" +.SH NAME clock \- Obtain and manipulate dates and times .SH "SYNOPSIS" package require \fBTcl 8.5\fR .sp -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR? +\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? .sp -\fBclock clicks\fR ?\fI-option\fR? +\fBclock clicks\fR ?\fI\-option\fR? .sp -\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...? +\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? .sp \fBclock microseconds\fR .sp \fBclock milliseconds\fR .sp -\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...? +\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? .sp \fBclock seconds\fR .sp @@ -31,27 +31,29 @@ The \fBclock\fR command performs several operations that obtain and manipulate values that represent times. The command supports several subcommands that determine what action is carried out by the command. .TP -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR? +\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? Adds a (possibly negative) offset to a time that is expressed as an integer number of seconds. See \fBCLOCK ARITHMETIC\fR for a full description. .TP -\fBclock clicks\fR ?\fI-option\fR? -If no \fI-option\fR argument is supplied, returns a high-resolution +\fBclock clicks\fR ?\fI\-option\fR? +If no \fI\-option\fR argument is supplied, returns a high-resolution time value as a system-dependent integer value. The unit of the value is system-dependent but should be the highest resolution clock available on the system such as a CPU cycle counter. See \fBHIGH RESOLUTION TIMERS\fR for a full description. -.sp -If the \fI-option\fR argument is \fI-milliseconds\fR, then the command +.RS +.PP +If the \fI\-option\fR argument is \fB\-milliseconds\fR, then the command is synonymous with \fBclock milliseconds\fR (see below). This usage is obsolete, and \fBclock milliseconds\fR is to be considered the preferred way of obtaining a count of milliseconds. -.sp -If the \fI-option\fR argument is \fI-microseconds\fR, then the command +.PP +If the \fI\-option\fR argument is \fB\-microseconds\fR, then the command is synonymous with \fBclock microseconds\fR (see below). This usage is obsolete, and \fBclock microseconds\fR is to be considered the preferred way of obtaining a count of microseconds. +.RE .TP -\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...? +\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? Formats a time that is expressed as an integer number of seconds into a format intended for consumption by users or external programs. See \fBFORMATTING TIMES\fR for a full description. @@ -62,14 +64,14 @@ Returns the current time as an integer number of microseconds. See \fBHIGH RESO \fBclock milliseconds\fR Returns the current time as an integer number of milliseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. .TP -\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...? +\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? Scans a time that is expressed as a character string and produces an integer number of seconds. See \fBSCANNING TIMES\fR for a full description. .TP \fBclock seconds\fR Returns the current time as an integer number of seconds. -.SH "PARAMETERS" +.SS "PARAMETERS" .TP \fIcount\fR An integer representing a count of some unit of time. See @@ -88,62 +90,67 @@ have 59 or 61 seconds. \fIunit\fR One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR, \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or -any unique prefix of such a word. Used in conjuction with \fIcount\fR +any unique prefix of such a word. Used in conjunction with \fIcount\fR to identify an interval of time, for example, \fI3 seconds\fR or \fI1 year\fR. -.SH "OPTIONS" +.SS "OPTIONS" .TP -\fB-base\fR time +\fB\-base\fR time Specifies that any relative times present in a \fBclock scan\fR command are to be given relative to \fItime\fR. \fItime\fR must be expressed as a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC. .TP -\fB-format\fR format +\fB\-format\fR format Specifies the desired output format for \fBclock format\fR or the expected input format for \fBclock scan\fR. The \fIformat\fR string consists -of any number of characters other than the per-cent sign ('\fI%\fR') +of any number of characters other than the per-cent sign +.PQ \fB%\fR interspersed with any number of \fIformat groups\fR, which are two-character sequences beginning with the per-cent sign. The permissible format groups, and their interpretation, are described under \fBFORMAT GROUPS\fR. .RS .PP On \fBclock format\fR, the default format is +.PP .CS %a %b %d %H:%M:%S %z %Y .CE .PP -On \fBclock scan\fR, the lack of a \fI-format\fR option indicates that -a "free format scan" is requested; see \fBFREE FORM SCAN\fR for a -description of what happens. +On \fBclock scan\fR, the lack of a \fB\-format\fR option indicates that a +.QW "free format scan" +is requested; see \fBFREE FORM SCAN\fR for a description of what happens. .RE .TP -\fB-gmt\fR boolean +\fB\-gmt\fR boolean If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR, \fBclock format\fR or \fBclock scan\fR should be processed in UTC. If \fIboolean\fR is false, the processing defaults to the local time zone. This usage is obsolete; the correct current usage is to -specify the UTC time zone with '\fB-timezone\fR \fI:UTC\fR' or any of -the equivalent ways to specify it. +specify the UTC time zone with +.QW "\fB\-timezone\fR \fI:UTC\fR" +or any of the equivalent ways to specify it. .TP -\fB-locale\fR localeName +\fB\-locale\fR localeName Specifies that locale-dependent scanning and formatting (and date arithmetic for dates preceding the adoption of the Gregorian calendar) is to be done in the locale identified by \fIlocaleName\fR. The locale name may be any of the locales acceptable to the \fBmsgcat\fR package, or it may be the special name \fIsystem\fR, which represents the current locale of the process, or the null string, which represents Tcl's default locale. -.sp +.RS +.PP The effect of locale on scanning and formatting is discussed in the descriptions of the individual format groups under \fBFORMAT GROUPS\fR. The effect of locale on clock arithmetic is discussed under \fBCLOCK ARITHMETIC\fR. +.RE .TP -\fB-timezone\fR zoneName +\fB\-timezone\fR zoneName Specifies that clock arithmetic, formatting, and scanning are to be done according to the rules for the time zone specified by \fIzoneName\fR. The permissible values, and their interpretation, are discussed under \fBTIME ZONES\fR. -On subcommands that expect a \fB-timezone\fR argument, the default +On subcommands that expect a \fB\-timezone\fR argument, the default is to use the \fIcurrent time zone\fR. The current time zone is determined, in order of preference, by: .RS @@ -154,16 +161,18 @@ the environment variable \fBTZ\fR. .IP [3] on Windows systems, the time zone settings from the Control Panel. .RE +.PP If none of these is present, the C \fBlocaltime\fR and \fBmktime\fR functions are used to attempt to convert times between local and Greenwich. On 32-bit systems, this approach is likely to have bugs, particularly for times that lie outside the window (approximately the years 1902 to 2037) that can be represented in a 32-bit integer. .SH "CLOCK ARITHMETIC" +.PP The \fBclock add\fR command performs clock arithmetic on a value (expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC) given as its first argument. The remaining arguments (other than the -possible \fB-timezone\fR, \fB-locale\fR and \fB-gmt\fR options) +possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options) are integers and keywords in alternation, where the keywords are chosen from \fBseconds\fR, \fBminutes\fR, \fBhours\fR, \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or @@ -189,11 +198,13 @@ absolute time means that it will add fixed amounts of time in time zones that observe summer time (Daylight Saving Time). For example, the following code sets the value of \fBx\fR to \fB04:00:00\fR because the clock has changed in the interval in question. +.PP .CS -set s [\fBclock scan\fR {2004-10-30 05:00:00} \\ - -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] +set s [\fBclock scan\fR {2004-10-30 05:00:00} \e + -format {%Y-%m-%d %H:%M:%S} \e + -timezone :America/New_York] set a [\fBclock add\fR $s 24 hours -timezone :America/New_York] -set x [\fBclock format\fR $a \\ +set x [\fBclock format\fR $a \e -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -208,11 +219,13 @@ Adding and subtracting a given number of days across the point that the time changes at the start or end of summer time (Daylight Saving Time) results in the \fIsame local time\fR on the day in question. For instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR. +.PP .CS -set s [\fBclock scan\fR {2004-10-30 05:00:00} \\ - -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] +set s [\fBclock scan\fR {2004-10-30 05:00:00} \e + -format {%Y-%m-%d %H:%M:%S} \e + -timezone :America/New_York] set a [\fBclock add\fR $s 1 day -timezone :America/New_York] -set x [\fBclock format\fR $a \\ +set x [\fBclock format\fR $a \e -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -222,17 +235,20 @@ yields an impossible time (for instance, 02:30 during the Spring Daylight Saving Time change using US rules), the time is converted as if the clock had not changed. Thus, the following code will set the value of \fBx\fR to \fB03:30:00\fR. +.PP .CS -set s [\fBclock scan\fR {2004-04-03 02:30:00} \\ - -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] +set s [\fBclock scan\fR {2004-04-03 02:30:00} \e + -format {%Y-%m-%d %H:%M:%S} \e + -timezone :America/New_York] set a [\fBclock add\fR $s 1 day -timezone :America/New_York] -set x [\fBclock format\fR $a \\ +set x [\fBclock format\fR $a \e -format {%H:%M:%S} -timezone :America/New_York] .CE .PP Adding a given number of days or weeks works correctly across the conversion between the Julian and Gregorian calendars; the omitted days are skipped. The following code sets \fBz\fR to \fB1752-09-14\fR. +.PP .CS set x [\fBclock scan\fR 1752-09-02 -format %Y-%m-%d -locale en_US] set y [\fBclock add\fR $x 1 day -locale en_US] @@ -261,13 +277,14 @@ years as they are when adding/subtracting days and weeks. If multiple \fIcount unit\fR pairs are present on the command, they are evaluated consecutively, from left to right. .SH "HIGH RESOLUTION TIMERS" +.PP Most of the subcommands supported by the \fBclock\fR command deal with times represented as a count of seconds from the epoch time, and this is the representation that \fBclock seconds\fR returns. There are three exceptions, which are all intended for use where higher-resolution times are required. \fBclock milliseconds\fR returns the count of milliseconds from the epoch time, and \fBclock microseconds\fR returns the count of microseconds -from the epoch time. In addition, there js a \fBclock clicks\fR command +from the epoch time. In addition, there is a \fBclock clicks\fR command that returns a platform-dependent high-resolution timer. Unlike \fBclock seconds\fR and \fBclock milliseconds\fR, the value of \fBclock clicks\fR is not guaranteed to be tied to any fixed @@ -275,76 +292,83 @@ epoch; it is simply intended to be the most precise interval timer available, and is intended only for relative timing studies such as benchmarks. .SH "FORMATTING TIMES" +.PP The \fBclock format\fR command produces times for display to a user or writing to an external medium. The command accepts times that are expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC, as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR, \fBfile atime\fR or \fBfile mtime\fR. .PP -If a \fB-format\fR option is present, the following argument is +If a \fB\-format\fR option is present, the following argument is a string that specifies how the date and time are to be formatted. The string consists -of any number of characters other than the per-cent sign ('\fI%\fR') +of any number of characters other than the per-cent sign +.PQ \fB%\fR interspersed with any number of \fIformat groups\fR, which are two-character sequences beginning with the per-cent sign. The permissible format groups, and their interpretation, are described under \fBFORMAT GROUPS\fR. .PP -If a \fB-timezone\fR option is present, the following +If a \fB\-timezone\fR option is present, the following argument is a string that specifies the time zone in which the date and time -are to be formatted. As an alternative to \fB-timezone\fR \fI:UTC\fR, -the obsolete usage \fB-gmt\fR \fItrue\fR may be used. See +are to be formatted. As an alternative to +.QW "\fB\-timezone\fR \fI:UTC\fR" , +the obsolete usage +.QW "\fB\-gmt\fR \fItrue\fR" +may be used. See \fBTIME ZONES\fR for the permissible variants for the time zone. .PP -If a \fB-locale\fR option is present, the following argument is +If a \fB\-locale\fR option is present, the following argument is a string that specifies the locale in which the time is to be formatted, in the same format that is used for the \fBmsgcat\fR package. Note -that the default, if \fB-locale\fR is not specified, is the root locale +that the default, if \fB\-locale\fR is not specified, is the root locale \fB{}\fR rather than the current locale. The current locale may -be obtained by using \fB-locale\fR \fBcurrent\fR. +be obtained by using \fB\-locale\fR \fBcurrent\fR. In addition, some platforms support a \fBsystem\fR locale that reflects the user's current choices. For instance, on Windows, the format that the user has selected from dates and times in the Control Panel can be obtained by using the \fBsystem\fR locale. On platforms that do not define a user selection of date and time formats -separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is -synonymous with \fB-locale\fR \fBcurrent\fR. +separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is +synonymous with \fB\-locale\fR \fBcurrent\fR. .SH "SCANNING TIMES" +.PP The \fBclock scan\fR command accepts times that are formatted as strings and converts them to counts of seconds from the epoch time -of 1 January 1970, 00:00 UTC. It normally takes a \fB-format\fR +of 1 January 1970, 00:00 UTC. It normally takes a \fB\-format\fR option that is followed by a string describing the expected format of the input. (See \fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR without such an argument.) The string consists of any number of -characters other than the per-cent sign ('\fI%\fR'), +characters other than the per-cent sign +.PQ \fB%\fR "" , interspersed with any number of \fIformat groups\fR, which are two-character sequences beginning with the per-cent sign. The permissible format groups, and their interpretation, are described under \fBFORMAT GROUPS\fR. .PP -If a \fB-timezone\fR option is present, the following +If a \fB\-timezone\fR option is present, the following argument is a string that specifies the time zone in which the date and time -are to be interpreted. As an alternative to \fB-timezone\fR \fI:UTC\fR, -the obsolete usage \fB-gmt\fR \fItrue\fR may be used. See +are to be interpreted. As an alternative to \fB\-timezone\fR \fI:UTC\fR, +the obsolete usage \fB\-gmt\fR \fItrue\fR may be used. See \fBTIME ZONES\fR for the permissible variants for the time zone. .PP -If a \fB-locale\fR option is present, the following argument is +If a \fB\-locale\fR option is present, the following argument is a string that specifies the locale in which the time is to be interpreted, in the same format that is used for the \fBmsgcat\fR package. Note -that the default, if \fB-locale\fR is not specified, is the root locale +that the default, if \fB\-locale\fR is not specified, is the root locale \fB{}\fR rather than the current locale. The current locale may -be obtained by using \fB-locale\fR \fBcurrent\fR. +be obtained by using \fB\-locale\fR \fBcurrent\fR. In addition, some platforms support a \fBsystem\fR locale that reflects the user's current choices. For instance, on Windows, the format that the user has selected from dates and times in the Control Panel can be obtained by using the \fBsystem\fR locale. On platforms that do not define a user selection of date and time formats -separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is -synonymous with \fB-locale\fR \fBcurrent\fR. +separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is +synonymous with \fB\-locale\fR \fBcurrent\fR. .PP -If a \fB-base\fR option is present, the following argument is +If a \fB\-base\fR option is present, the following argument is a time (expressed in seconds from the epoch time) that is used as a \fIbase time\fR for interpreting relative times. If no -\fB-base\fR option is present, the base time is the current time. +\fB\-base\fR option is present, the base time is the current time. .PP Scanning of times in fixed format works by determining three things: the date, the time of day, and the time zone. These three are then @@ -383,8 +407,9 @@ combined and used to determine the date. If more than one complete set is present, the one at the rightmost position in the string is used. The year is presumed to lie in the range 1938 to 2037 inclusive. .IP [5] -If the string entirely lacks any specification for the year, -but contains a set of format groups specifying month and day of month, +If the string entirely lacks any specification for the year +(or contains the year only on the locale's alternative calendar) +and contains a set of format groups specifying month and day of month, day of year, or week of year and day of week, those groups are combined and used to determine the date. If more than one complete set is present, the one at the rightmost position in the string is @@ -418,7 +443,7 @@ combines with the hour and minute. If the string contains neither a \fB%s\fR format group nor a group specifying the hour of the day, then midnight (\fB00:00\fR, the start of the given date) is used. -The time zone is determined by either the \fB-timezone\fR or \fB-gmt\fR +The time zone is determined by either the \fB\-timezone\fR or \fB\-gmt\fR options, or by using the current time zone. .PP If a format string lacks a \fB%z\fR or \fB%Z\fR format group, @@ -429,6 +454,7 @@ If this situation occurs, the first occurrence of the time is chosen. time zone when converting local times. This caveat does not apply to UTC times.) .SH "FORMAT GROUPS" +.PP The following format groups are recognized by the \fBclock scan\fR and \fBclock format\fR commands. .TP @@ -459,7 +485,7 @@ any unique prefix of either form). \fB%c\fR On output, receives a localized representation of date and time of day; the localized representation is expected to use the Gregorian calendar. -On input, matches whatever %c produces. +On input, matches whatever \fB%c\fR produces. .TP \fB%C\fR On output, receives the number of the century in Indo-Arabic numerals. @@ -485,7 +511,7 @@ whitespace, that are expected to be the number of the day of the month. \fB%Ec\fR On output, produces a locale-dependent representation of the date and time of day in the locale's alternative calendar. On input, matches -whatever %Ec produces. The locale's alternative calendar need not +whatever \fB%Ec\fR produces. The locale's alternative calendar need not be the Gregorian calendar. .TP \fB%EC\fR @@ -493,16 +519,25 @@ On output, produces a locale-dependent name of an era in the locale's alternative calendar. On input, matches the name of the era or any unique prefix. .TP +\fB%EE\fR +On output, produces the string \fBB.C.E.\fR or \fBC.E.\fR, or a +string of the same meaning in the locale, to indicate whether \fB%Y\fR refers +to years before or after Year 1 of the Common Era. On input, accepts +the string \fBB.C.E.\fR, \fBB.C.\fR, \fBC.E.\fR, \fBA.D.\fR, or the +abbreviation appropriate to the current locale, and uses it to fix +whether \fB%Y\fR refers to years before or after Year 1 of the +Common Era. +.TP \fB%Ex\fR On output, produces a locale-dependent representation of the date in the locale's alternative calendar. On input, matches -whatever %Ex produces. The locale's alternative calendar need not +whatever \fB%Ex\fR produces. The locale's alternative calendar need not be the Gregorian calendar. .TP \fB%EX\fR On output, produces a locale-dependent representation of the time of day in the locale's alternative numerals. On input, matches -whatever %EX produces. +whatever \fB%EX\fR produces. .TP \fB%Ey\fR On output, produces a locale-dependent number of the year of the era @@ -568,27 +603,30 @@ with exactly two digits. On input, accepts two digits and interprets them as the number of the minute of the hour. .TP \fB%N\fR -On output, produces the number of the month (1-12) with one or two digits. -digits. On input, accepts one or two digits, possibly with leading whitespace, +On output, produces the number of the month (1-12) with one or two digits, +and a leading blank for one-digit dates. +On input, accepts one or two digits, possibly with leading whitespace, and interprets them as the number of the month. .TP \fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR All of these format groups are synonymous with their counterparts -without the '\fBO\fR', except that the string is produced and parsed in the +without the +.QW \fBO\fR , +except that the string is produced and parsed in the locale-dependent alternative numerals. .TP \fB%p\fR -On output, produces an indicator for the part of the day, \fBA.M.\fR -or \fBP.M.\fR, appropriate to the given locale. If the script of the -given locale supports multiple letterforms, uppercase is preferred. -On input, matches the representation \fBA.M.\fR or \fBP.M.\fR in +On output, produces an indicator for the part of the day, \fBAM\fR +or \fBPM\fR, appropriate to the given locale. If the script of the +given locale supports multiple letterforms, lowercase is preferred. +On input, matches the representation \fBAM\fR or \fBPM\fR in the given locale, in either case. .TP \fB%P\fR -On output, produces an indicator for the part of the day, \fBA.M.\fR -or \fBP.M.\fR, appropriate to the given locale. If the script of the -given locale supports multiple letterforms, lowercase is preferred. -On input, matches the representation \fBA.M.\fR or \fBP.M.\fR in +On output, produces an indicator for the part of the day, \fBam\fR +or \fBpm\fR, appropriate to the given locale. If the script of the +given locale supports multiple letterforms, uppercase is preferred. +On input, matches the representation \fBAM\fR or \fBPM\fR in the given locale, in either case. .TP \fB%Q\fR @@ -622,7 +660,7 @@ Synonymous with \fB%H:%M:%S\fR. .TP \fB%u\fR On output, produces the number of the day of the week -(\fB1\fR-Monday, \fB7\fR-Sunday). On input, accepts a single digit and +(\fB1\fR\(->Monday, \fB7\fR\(->Sunday). On input, accepts a single digit and interprets it as the day of the week. Sunday may be either \fB0\fR or \fB7\fR. .TP @@ -643,6 +681,13 @@ equivalent). Each week begins on a Monday. On input, accepts the ISO8601 week number. .TP \fB%w\fR +On output, produces the ordinal number of the day of the week +(Sunday==0; Saturday==6). On input, accepts a single digit and +interprets it as the day of the week; Sunday may be represented as +either 0 or 7. Note that \fB%w\fR is not the ISO8601 weekday number, +which is produced and accepted by \fB%u\fR. +.TP +\fB%W\fR On output, produces a week number (00-53) within the year; week 01 begins on the first Monday of the year. On input, accepts two digits, which are otherwise ignored. This format group is never used in @@ -674,7 +719,7 @@ week number \fB%V\fR; programs should use \fB%G\fR for that purpose. .TP \fB%z\fR On output, produces the current time zone, expressed in hours and -minutes east (+hhmm) or west (-hhmm) of Greenwich. On input, accepts a +minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a time zone specifier (see \fBTIME ZONES\fR below) that will be used to determine the time zone. .TP @@ -689,12 +734,17 @@ Brazilian Standard Time. It is recommended that date/time strings for use by computers use numeric time zones instead. .TP \fB%%\fR -On output, produces a literal '\fB%\fR' charater. On input, matches -a literal '\fB%\fR' character. +On output, produces a literal +.QW \fB%\fR +character. On input, matches a literal +.QW \fB%\fR +character. .TP \fB%+\fR -Synonymous with '\fB%a %b %e %H:%M:%S %Z %Y\fR'. +Synonymous with +.QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" . .SH "TIME ZONES" +.PP When the \fBclock\fR command is processing a local time, it has several possible sources for the time zone to use. In order of preference, they are: @@ -702,8 +752,8 @@ are: A time zone specified inside a string being parsed and matched by a \fB%z\fR or \fB%Z\fR format group. .IP [2] -A time zone specified with the \fB-timezone\fR option to the \fBclock\fR -command (or, equivalently, by \fB-gmt\fR \fB1\fR). +A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR +command (or, equivalently, by \fB\-gmt\fR \fB1\fR). .IP [3] A time zone specified in an environment variable \fBTCL_TZ\fR. .IP [4] @@ -714,10 +764,9 @@ The local time zone from the Control Panel on Windows systems. The C library's idea of the local time zone, as defined by the \fBmktime\fR and \fBlocaltime\fR functions. .PP -Whatever the source of the time zone string, the same set of rules -is used to parse it. First, if it was obtained from a \fB%z\fR -or \fB%Z\fR format group, it is checked to see if it is one of -the strings, +In case [1] \fIonly,\fR the string is tested to see if it is one +of the strings: +.PP .CS gmt ut utc bst wet wat at nft nst ndt ast adt est edt @@ -729,52 +778,78 @@ the strings, cadt east eadt gst nzt nzst nzdt idle .CE +.PP If it is a string in the above list, it designates a known time zone, and is interpreted as such. .PP -The next check is for a string beginning with a colon. +For time zones in case [1] that do not match any of the above strings, +and always for cases [2]-[6], the following rules apply. +.PP If the time zone begins with a colon, it is one of a standardized list of names like \fB:America/New_York\fR that give the rules for various locales. A complete list of the location names is too lengthy to be listed here. On most Tcl installations, the definitions of the locations are to be found in named files in the directory - "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR". On some Unix systems, these -files are omitted, and the definitions are instead -obtained from system files in "\fI/usr/share/zoneinfo\fR", - "\fI/usr/share/lib/zoneinfo\fR" or "\fI/usr/local/etc/zoneinfo\fR". +.QW "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR" . +On some Unix systems, these files are omitted, and the definitions are +instead obtained from system files in +.QW "\fI/usr/share/zoneinfo\fR" , +.QW "\fI/usr/share/lib/zoneinfo\fR" +or +.QW "\fI/usr/local/etc/zoneinfo\fR" . As a special case, the name \fB:localtime\fR refers to the local time zone as defined by the C library. .PP -A string consisting of a plus or minus sign followed by +A time zone string consisting of a plus or minus sign followed by four or six decimal digits is interpreted as an offset in hours, minutes, and seconds (if six digits are present) from UTC. The plus sign denotes a sign east of Greenwich; the minus sign one west of Greenwich. .PP -A string conforming to the Posix specification of the \fBTZ\fR +A time zone string conforming to the Posix specification of the \fBTZ\fR environment variable will be recognized. The specification may be found at \fIhttp://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR. .PP -Any other string is processed by prefixing a colon and attempting +If the Posix time zone string contains a DST (Daylight Savings Time) +part, but doesn't contain a rule stating when DST starts or ends, +then default rules are used. For Timezones with an offset between 0 +and +12, the current European/Russian rules are used, otherwise the +current US rules are used. In Europe (offset +0 to +2) the switch +to summertime is done each last Sunday in March at 1:00 GMT, and +the switch back is each last Sunday in October at 2:00 GMT. In +Russia (offset +3 to +12), the switch dates are the same, only +the switch to summertime is at 2:00 local time, and the switch +back is at 3:00 local time in all time zones. The US switch to +summertime takes place each second Sunday in March at 2:00 local +time, and the switch back is each first Sunday in November at +3:00 local time. These default rules mean that in all European, +Russian and US (or compatible) time zones, DST calculations will +be correct for dates in 2007 and later, unless in the future the +rules change again. +.PP +Any other time zone string is processed by prefixing a colon and attempting to use it as a location name, as above. .SH "LOCALIZATION" +.PP Developers wishing to localize the date and time formatting and parsing are referred to \fIhttp://tip.tcl.tk/173\fR for a specification. .SH "FREE FORM SCAN" -If the \fBclock scan\fR command is invoked without a \fB-format\fR +.PP +If the \fBclock scan\fR command is invoked without a \fB\-format\fR option, then it requests a \fIfree-form scan.\fR \fI This form of scan is deprecated.\fR The reason for the deprecation -is that there are too many ambiguities. (Does the string '2000' +is that there are too many ambiguities. (Does the string +.QW 2000 represent a year, a time of day, or a quantity?) No set of rules for interpreting free-form dates and times has been found to give unsurprising results in all cases. .PP -If free-form scan is used, only the \fB-base\fR and \fB-gmt\fR -options are accepted. The \fB-timezone\fR and \fB-locale\fR -options will result in an error if \fB-format\fR is not supplied. +If free-form scan is used, only the \fB\-base\fR and \fB\-gmt\fR +options are accepted. The \fB\-timezone\fR and \fB\-locale\fR +options will result in an error if \fB\-format\fR is not supplied. .PP For the benefit of users who need to understand legacy code that uses free-form scan, the documentation for how free-form scan @@ -783,13 +858,13 @@ interprets a string is included here: If only a time is specified, the current date is assumed. If the \fIinputString\fR does not contain a -time zone mnemonic, the local time zone is assumed, unless the \fB-gmt\fR +time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR argument is true, in which case the clock value is calculated assuming that the specified time is relative to Greenwich Mean Time. -\fB-gmt\fR, if specified, affects only the computed time value; it does not -impact the interpretation of \fB-base\fR. +\fB\-gmt\fR, if specified, affects only the computed time value; it does not +impact the interpretation of \fB\-base\fR. .PP -If the \fB-base\fR flag is specified, the next argument should contain +If the \fB\-base\fR flag is specified, the next argument should contain an integer clock value. Only the date in this value is used, not the time. This is useful for determining the time on a specific day or doing other date-relative conversions. @@ -805,30 +880,42 @@ a 24-hour clock. .TP \fIdate\fR A specific month and day with optional year. The -acceptable formats are "\fBmm/dd\fR?\fB/yy\fR?", - "\fBmonthname dd\fR?\fB, yy\fR?", - "\fBday, dd monthname \fR?\fByy\fR?", - "\fBdd monthname yy\fR", - "?\fBCC\fR?\fByymmdd\fR", and - "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR". +acceptable formats are +.QW "\fBmm/dd\fR?\fB/yy\fR?" , +.QW "\fBmonthname dd\fR?\fB, yy\fR?" , +.QW "\fBday, dd monthname \fR?\fByy\fR?" , +.QW "\fBdd monthname yy\fR" , +.QW "?\fBCC\fR?\fByymmdd\fR" , +and +.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" . The default year is the current year. If the year is less than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 as 1969-1999. Not all platforms can represent the years 38-70, so an error may result if these years are used. .TP \fIISO 8601 point-in-time\fR -An ISO 8601 point-in-time specification, such as \fBCCyymmddThhmmss\fR, -where \fBT\fR is the literal T, "\fBCCyymmdd hhmmss\fR", or -\fBCCyymmddThh:mm:ss\fR. +An ISO 8601 point-in-time specification, such as +.QW \fICCyymmdd\fBT\fIhhmmss\fR, +where \fBT\fR is the literal +.QW T , +.QW "\fICCyymmdd hhmmss\fR" , +or +.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR . +Note that only these three formats are accepted. +The command does \fInot\fR accept the full range of point-in-time +specifications specified in ISO8601. Other formats can be recognized by +giving an explicit \fB\-format\fR option to the \fBclock scan\fR command. .TP \fIrelative time\fR A specification relative to the current time. The format is \fBnumber -unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR, \fBmonth\fR, \fBweek\fR, \fBday\fR, +unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR, +\fBmonth\fR, \fBweek\fR, \fBday\fR, \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR). The unit can be specified as a singular or plural, as in \fB3 weeks\fR. These modifiers may also be specified: \fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR, \fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR. +.PP The actual date is calculated according to the following steps. .PP First, any absolute date and/or time is processed and converted. @@ -839,19 +926,12 @@ used. Finally, a correction is applied so that the correct hour of the day is produced after allowing for daylight savings time differences and the correct date is given when going from the end of a long month to a short month. -.PP -Daylight savings time correction is applied only when the relative time -is specified in units of days or more, i.e.\ days, weeks, fortnights, months or -years. This means that when crossing the daylight savings time boundary, -different results will be given for \fBclock scan "1 day"\fR and -\fBclock scan "24 hours"\fR: -.CS -% \fBclock scan\fR "1 day" -base [\fBclock scan\fR 1999-10-31] -941443200 -% \fBclock scan\fR "24 hours" -base [\fBclock scan\fR 1999-10-31] -941439600 -.CE .SH "SEE ALSO" -msgcat +msgcat(n) +.SH KEYWORDS +clock, date, time .SH "COPYRIGHT" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. +'\" Local Variables: +'\" mode: nroff +'\" End: |