diff options
Diffstat (limited to 'tcl8.6/doc/clock.n')
-rw-r--r-- | tcl8.6/doc/clock.n | 938 |
1 files changed, 0 insertions, 938 deletions
diff --git a/tcl8.6/doc/clock.n b/tcl8.6/doc/clock.n deleted file mode 100644 index 889a5da..0000000 --- a/tcl8.6/doc/clock.n +++ /dev/null @@ -1,938 +0,0 @@ -'\" -'\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. -'\" -.TH "clock" n 8.5 Tcl "Tcl Built-In Commands" -.so man.macros -.BS -.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? -.sp -\fBclock clicks\fR ?\fI\-option\fR? -.sp -\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...? -.sp -\fBclock seconds\fR -.sp -.BE -.SH "DESCRIPTION" -.PP -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? -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 -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. -.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. -.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...? -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. -.TP -\fBclock microseconds\fR -Returns the current time as an integer number of microseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. -.TP -\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...? -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. -.SS "PARAMETERS" -.TP -\fIcount\fR -An integer representing a count of some unit of time. See -\fBCLOCK ARITHMETIC\fR for the details. -.TP -\fItimeVal\fR -An integer value passed to the \fBclock\fR command that represents an -absolute time as a number of seconds from the \fIepoch time\fR of -1 January 1970, 00:00 UTC. Note that the count of seconds does not -include any leap seconds; seconds are counted as if each UTC day has -exactly 86400 seconds. Tcl responds to leap seconds by speeding or -slowing its clock by a tiny fraction for some minutes until it is -back in sync with UTC; its data model does not represent minutes that -have 59 or 61 seconds. -.TP -\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 conjunction with \fIcount\fR -to identify an interval of time, for example, \fI3 seconds\fR or -\fI1 year\fR. -.SS "OPTIONS" -.TP -\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 -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 -.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 \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 -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 -.QW "\fB\-timezone\fR \fI:UTC\fR" -or any of the equivalent ways to specify it. -.TP -\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. -.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 -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 -is to use the \fIcurrent time zone\fR. The current time zone is -determined, in order of preference, by: -.RS -.IP [1] -the environment variable \fBTCL_TZ\fR. -.IP [2] -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) -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 -any unique prefix of such a word. -.PP -Addition of seconds, minutes and hours is fairly straightforward; -the given time increment (times sixty for minutes, or 3600 for hours) -is simply added to the \fItimeVal\fR given -to the \fBclock add\fR command. The result is interpreted as -a nominal number of seconds from the Epoch. -.PP -Surprising results -may be obtained when crossing a point at which a leap second is -inserted or removed; the \fBclock add\fR command simply ignores -leap seconds and therefore assumes that times come in sequence, -23:59:58, 23:59:59, 00:00:00. (This assumption is handled by -the fact that Tcl's model of time reacts to leap seconds by speeding -or slowing the clock by a minuscule amount until Tcl's time -is back in step with the world. -.PP -The fact that adding and subtracting hours is defined in terms of -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} \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 \e - -format {%H:%M:%S} -timezone :America/New_York] -.CE -.PP -Adding and subtracting days and weeks is accomplished by converting -the given time to a calendar day and time of day in the appropriate -time zone and locale. The requisite number of days (weeks are converted -to days by multiplying by seven) is added to the calendar day, and -the date and time are then converted back to a count of seconds from -the epoch time. -.PP -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} \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 \e - -format {%H:%M:%S} -timezone :America/New_York] -.CE -.PP -In cases of ambiguity, where the same local time happens twice -on the same day, the earlier time is used. In cases where the conversion -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} \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 \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] -set z [\fBclock format\fR $y -format %Y-%m-%d -locale en_US] -.CE -.PP -In the bizarre case that adding the given number of days yields a date -that does not exist because it falls within the dropped days of the -Julian-to-Gregorian conversion, the date is converted as if it was -on the Julian calendar. -.PP -Adding a number of months, or a number of years, is similar; it -converts the given time to a calendar date and time of day. It then -adds the requisite number of months or years, and reconverts the resulting -date and time of day to an absolute time. -.PP -If the resulting date is impossible because the month has too few days -(for example, when adding 1 month to 31 January), the last day of the -month is substituted. Thus, adding 1 month to 31 January will result in -28 February in a common year or 29 February in a leap year. -.PP -The rules for handling anomalies relating to summer time and to the -Gregorian calendar are the same when adding/subtracting months and -years as they are when adding/subtracting days and weeks. -.PP -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 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 -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 -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 -.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 -argument is a string that specifies the time zone in which the date and time -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 -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 -\fB{}\fR rather than the current locale. The current locale may -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. -.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 -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 -.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 -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 -\fBTIME ZONES\fR for the permissible variants for the time zone. -.PP -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 -\fB{}\fR rather than the current locale. The current locale may -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. -.PP -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. -.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 -combined into a point in time, which is returned as the number of seconds -from the epoch. -.PP -Before scanning begins, the format string is preprocessed -to replace \fB%c\fR, \fB%Ec\fR, \fB%x\fR, \fB%Ex\fR, -\fB%X\fR. \fB%Ex\fR, \fB%r\fR, \fB%R\fR, \fB%T\fR, -\fB%D\fR, \fB%EY\fR and \fB%+\fR format groups with counterparts -that are appropriate to the current locale and contain none of the -above groups. For instance, \fB%D\fR will (in the \fBen_US\fR locale) -be replaced with \fB%m/%d/%Y\fR. -.PP -The date is determined according to the fields that are present in the -preprocessed format string. In order of preference: -.IP [1] -If the string contains a \fB%s\fR format group, representing -seconds from the epoch, that group is used to determine the date. -.IP [2] -If the string contains a \fB%J\fR format group, representing -the Julian Day Number, that group is used to determine the date. -.IP [3] -If the string contains a complete set of format groups specifying -century, year, month, and day of month; century, year, and day of year; -or ISO8601 fiscal year, 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 -used. -.IP [4] -If the string lacks a century but contains a set of format -groups specifying year of century, month and day of month; year of -century and day of year; or two-digit ISO8601 fiscal year, 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 -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 -(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 -used. The year is determined by interpreting the base time in the given -time zone. -.IP [6] -If the string contains none of the above sets, but has a day -of the month or day of the week, the day of the month or day of the week -are used to determine the date by interpreting the base time in the -given time zone and returning the given day of the current week or month. -(The week runs from Monday to Sunday, ISO8601-fashion.) If both day -of month and day of week are present, the day of the month takes -priority. -.IP [7] -If none of the above rules results in a usable date, the date -of the base time in the given time zone is used. -.PP -The time is also determined according to the fields that are present in the -preprocessed format string. In order of preference: -.IP [1] -If the string contains a \fB%s\fR format group, representing -seconds from the epoch, that group determines the time of day. -.IP [2] -If the string contains either an hour on the 24-hour clock -or an hour on the 12-hour clock plus an AM/PM indicator, that hour determines -the hour of the day. If the string further contains a group specifying -the minute of the hour, that group combines with the hour. If the string -further contains a group specifying the second of the minute, that group -combines with the hour and minute. -.IP [3] -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 -options, or by using the current time zone. -.PP -If a format string lacks a \fB%z\fR or \fB%Z\fR format group, -it is possible for the time to be ambiguous because it appears twice -in the same day, once without and once with Daylight Saving Time. -If this situation occurs, the first occurrence of the time is chosen. -(For this reason, it is wise to have the input string contain the -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 -\fB%a\fR -On output, receives an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day -of the week in the given locale. On input, matches the name of the day -of the week in the given locale (in either abbreviated or full form, or -any unique prefix of either form). -.TP -\fB%A\fR -On output, receives the full name (\fIe.g.,\fR \fBMonday\fR) of the day -of the week in the given locale. On input, matches the name of the day -of the week in the given locale (in either abbreviated or full form, or -any unique prefix of either form). -.TP -\fB%b\fR -On output, receives an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name -of the month in the given locale. On input, matches the name of the month -in the given locale (in either abbreviated or full form, or -any unique prefix of either form). -.TP -\fB%B\fR -On output, receives the full name (\fIe.g.,\fR \fBJanuary\fR) -of the month in the given locale. On input, matches the name of the month -in the given locale (in either abbreviated or full form, or -any unique prefix of either form). -.TP -\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 \fB%c\fR produces. -.TP -\fB%C\fR -On output, receives the number of the century in Indo-Arabic numerals. -On input, matches one or two digits, possibly with leading whitespace, -that are expected to be the number of the century. -.TP -\fB%d\fR -On output, produces the number of the day of the month, as two decimal -digits. On input, matches one or two digits, possibly with leading -whitespace, that are expected to be the number of the day of the month. -.TP -\fB%D\fR -This format group is synonymous with \fB%m/%d/%Y\fR. It should be -used only in exchanging data within the \fBen_US\fR locale, since -other locales typically do not use this order for the fields of the date. -.TP -\fB%e\fR -On output, produces the number of the day of the month, as one or -two decimal digits (with a leading blank for one-digit dates). -On input, matches one or two digits, possibly with leading -whitespace, that are expected to be the number of the day of the month. -.TP -\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 \fB%Ec\fR produces. The locale's alternative calendar need not -be the Gregorian calendar. -.TP -\fB%EC\fR -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 \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 \fB%EX\fR produces. -.TP -\fB%Ey\fR -On output, produces a locale-dependent number of the year of the era -in the locale's alternative calendar and numerals. On input, matches -such a number. -.TP -\fB%EY\fR -On output, produces a representation of the year in the locale's -alternative calendar and numerals. On input, matches what \fB%EY\fR -produces. Often synonymous with \fB%EC%Ey\fR. -.TP -\fB%g\fR -On output, produces a two-digit year number suitable for use with -the week-based ISO8601 calendar; that is, the year number corresponds -to the week number produced by \fB%V\fR. On input, accepts such -a two-digit year number, possibly with leading whitespace. -.TP -\fB%G\fR -On output, produces a four-digit year number suitable for use with -the week-based ISO8601 calendar; that is, the year number corresponds -to the week number produced by \fB%V\fR. On input, accepts such -a four-digit year number, possibly with leading whitespace. -.TP -\fB%h\fR -This format group is synonymous with \fB%b\fR. -.TP -\fB%H\fR -On output, produces a two-digit number giving the hour of the day -(00-23) on a 24-hour clock. On input, accepts such a number. -.TP -\fB%I\fR -On output, produces a two-digit number giving the hour of the day -(12-11) on a 12-hour clock. On input, accepts such a number. -.TP -\fB%j\fR -On output, produces a three-digit number giving the day of the year -(001-366). On input, accepts such a number. -.TP -\fB%J\fR -On output, produces a string of digits giving the Julian Day Number. -On input, accepts a string of digits and interprets it as a Julian Day Number. -The Julian Day Number is a count of the number of calendar days -that have elapsed since 1 January, 4713 BCE of the proleptic -Julian calendar. The epoch time of 1 January 1970 corresponds -to Julian Day Number 2440588. -.TP -\fB%k\fR -On output, produces a one- or two-digit number giving the hour of the day -(0-23) on a 24-hour clock. On input, accepts such a number. -.TP -\fB%l\fR -On output, produces a one- or two-digit number giving the hour of the day -(12-11) on a 12-hour clock. On input, accepts such a number. -.TP -\fB%m\fR -On output, produces the number of the month (01-12) with exactly two -digits. On input, accepts two digits and interprets them as the number -of the month. -.TP -\fB%M\fR -On output, produces the number of the minute of the hour (00-59) -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, -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 -.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, \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, \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 -This format group is reserved for internal use within the Tcl library. -.TP -\fB%r\fR -On output, produces a locale-dependent time of day representation on a -12-hour clock. On input, accepts whatever \fB%r\fR produces. -.TP -\fB%R\fR -On output, the time in 24-hour notation (%H:%M). For a version -including the seconds, see \fB%T\fR below. On input, accepts whatever -\fB%R\fR produces. -.TP -\fB%s\fR -On output, simply formats the \fItimeVal\fR argument as a decimal -integer and inserts it into the output string. On input, accepts -a decimal integer and uses is as the time value without any further -processing. Since \fB%s\fR uniquely determines a point in time, it -overrides all other input formats. -.TP -\fB%S\fR -On output, produces a two-digit number of the second of the minute -(00-59). On input, accepts two digits and uses them as the second of the -minute. -.TP -\fB%t\fR -On output, produces a TAB character. On input, matches a TAB character. -.TP -\fB%T\fR -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 -interprets it as the day of the week. Sunday may be either \fB0\fR or -\fB7\fR. -.TP -\fB%U\fR -On output, produces the ordinal number of the week of the year -(00-53). The first Sunday of the year is the first day of week 01. On -input accepts two digits which are otherwise ignored. This format -group is never used in determining an input date. This interpretation -of the week of the year was once common in US banking but is now -largely obsolete. See \fB%V\fR for the ISO8601 week number. -.TP -\fB%V\fR -On output, produces the number of the ISO8601 week as a two digit -number (01-53). Week 01 is the week containing January 4; or the first -week of the year containing at least 4 days; or the week containing -the first Thursday of the year (the three statements are -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 -determining an input date. It is not the ISO8601 week number; that -week is produced and accepted by \fB%V\fR. -.TP -\fB%x\fR -On output, produces the date in a locale-dependent representation. On -input, accepts whatever \fB%x\fR produces and is used to determine -calendar date. -.TP -\fB%X\fR -On output, produces the time of day in a locale-dependent -representation. On input, accepts whatever \fB%X\fR produces and is used -to determine time of day. -.TP -\fB%y\fR -On output, produces the two-digit year of the century. On input, -accepts two digits, and is used to determine calendar date. The -date is presumed to lie between 1938 and 2037 inclusive. Note -that \fB%y\fR does not yield a year appropriate for use with the ISO8601 -week number \fB%V\fR; programs should use \fB%g\fR for that purpose. -.TP -\fB%Y\fR -On output, produces the four-digit calendar year. On input, -accepts four digits and may be used to determine calendar date. Note -that \fB%Y\fR does not yield a year appropriate for use with the ISO8601 -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 -time zone specifier (see \fBTIME ZONES\fR below) that will be used to -determine the time zone. -.TP -\fB%Z\fR -On output, produces the current time zone's name, possibly -translated to the given locale. On input, accepts a time zone -specifier (see \fBTIME ZONES\fR below) that will be used to determine the -time zone. This option should, in general, be used on input only when -parsing RFC822 dates. Other uses are fraught with ambiguity; for -instance, the string \fBBST\fR may represent British Summer Time or -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 -.QW \fB%\fR -character. On input, matches a literal -.QW \fB%\fR -character. -.TP -\fB%+\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: -.IP [1] -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). -.IP [3] -A time zone specified in an environment variable \fBTCL_TZ\fR. -.IP [4] -A time zone specified in an environment variable \fBTZ\fR. -.IP [5] -The local time zone from the Control Panel on Windows systems. -.IP [6] -The C library's idea of the local time zone, as defined by the -\fBmktime\fR and \fBlocaltime\fR functions. -.PP -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 - cst cdt mst mdt pst pdt yst - ydt hst hdt cat ahst nt idlw - cet cest met mewt mest swt sst - eet eest bt it zp4 zp5 ist - zp6 wast wadt jt cct jst cast - 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 -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 -.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 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 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 -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" -.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 -.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. -.PP -For the benefit of users who need to understand legacy code that -uses free-form scan, the documentation for how free-form scan -interprets a string is included here: -.PP -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 -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. -.PP -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. -.PP -The \fIinputString\fR argument consists of zero or more specifications of the -following form: -.TP -\fItime\fR -A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR -or \fBhhmm ?meridian? ?zone?\fR -If no meridian is specified, \fBhh\fR is interpreted on -a 24-hour clock. -.TP -\fIdate\fR -A specific month and day with optional year. The -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 -.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, -\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. -Using that time as the base, day-of-week specifications are added. -Next, relative specifications are used. If a date or day is -specified, and no absolute or relative time is given, midnight is -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. -.SH "SEE ALSO" -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: |