[25] | 1 | '\" |
---|
| 2 | '\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff' |
---|
| 3 | '\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. |
---|
| 4 | '\" |
---|
| 5 | .so man.macros |
---|
| 6 | .TH "clock" n 8.5 Tcl "Tcl Built-In Commands" |
---|
| 7 | .BS |
---|
| 8 | .SH NAME |
---|
| 9 | clock \- Obtain and manipulate dates and times |
---|
| 10 | .SH "SYNOPSIS" |
---|
| 11 | package require \fBTcl 8.5\fR |
---|
| 12 | .sp |
---|
| 13 | \fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? |
---|
| 14 | .sp |
---|
| 15 | \fBclock clicks\fR ?\fI\-option\fR? |
---|
| 16 | .sp |
---|
| 17 | \fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? |
---|
| 18 | .sp |
---|
| 19 | \fBclock microseconds\fR |
---|
| 20 | .sp |
---|
| 21 | \fBclock milliseconds\fR |
---|
| 22 | .sp |
---|
| 23 | \fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? |
---|
| 24 | .sp |
---|
| 25 | \fBclock seconds\fR |
---|
| 26 | .sp |
---|
| 27 | .BE |
---|
| 28 | .SH "DESCRIPTION" |
---|
| 29 | .PP |
---|
| 30 | The \fBclock\fR command performs several operations that obtain and |
---|
| 31 | manipulate values that represent times. The command supports several |
---|
| 32 | subcommands that determine what action is carried out by the command. |
---|
| 33 | .TP |
---|
| 34 | \fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? |
---|
| 35 | Adds a (possibly negative) offset to a time that is expressed as an |
---|
| 36 | integer number of seconds. See \fBCLOCK ARITHMETIC\fR for a full description. |
---|
| 37 | .TP |
---|
| 38 | \fBclock clicks\fR ?\fI\-option\fR? |
---|
| 39 | If no \fI\-option\fR argument is supplied, returns a high-resolution |
---|
| 40 | time value as a system-dependent integer value. The unit of the value |
---|
| 41 | is system-dependent but should be the highest resolution clock available |
---|
| 42 | on the system such as a CPU cycle counter. See \fBHIGH RESOLUTION TIMERS\fR for a full description. |
---|
| 43 | .RS |
---|
| 44 | .PP |
---|
| 45 | If the \fI\-option\fR argument is \fI\-milliseconds\fR, then the command |
---|
| 46 | is synonymous with \fBclock milliseconds\fR (see below). This |
---|
| 47 | usage is obsolete, and \fBclock milliseconds\fR is to be |
---|
| 48 | considered the preferred way of obtaining a count of milliseconds. |
---|
| 49 | .PP |
---|
| 50 | If the \fI\-option\fR argument is \fI\-microseconds\fR, then the command |
---|
| 51 | is synonymous with \fBclock microseconds\fR (see below). This |
---|
| 52 | usage is obsolete, and \fBclock microseconds\fR is to be |
---|
| 53 | considered the preferred way of obtaining a count of microseconds. |
---|
| 54 | .RE |
---|
| 55 | .TP |
---|
| 56 | \fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? |
---|
| 57 | Formats a time that is expressed as an integer number of seconds into a format |
---|
| 58 | intended for consumption by users or external programs. |
---|
| 59 | See \fBFORMATTING TIMES\fR for a full description. |
---|
| 60 | .TP |
---|
| 61 | \fBclock microseconds\fR |
---|
| 62 | Returns the current time as an integer number of microseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. |
---|
| 63 | .TP |
---|
| 64 | \fBclock milliseconds\fR |
---|
| 65 | Returns the current time as an integer number of milliseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. |
---|
| 66 | .TP |
---|
| 67 | \fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? |
---|
| 68 | Scans a time that is expressed as a character string and produces an |
---|
| 69 | integer number of seconds. |
---|
| 70 | See \fBSCANNING TIMES\fR for a full description. |
---|
| 71 | .TP |
---|
| 72 | \fBclock seconds\fR |
---|
| 73 | Returns the current time as an integer number of seconds. |
---|
| 74 | .SS "PARAMETERS" |
---|
| 75 | .TP |
---|
| 76 | \fIcount\fR |
---|
| 77 | An integer representing a count of some unit of time. See |
---|
| 78 | \fBCLOCK ARITHMETIC\fR for the details. |
---|
| 79 | .TP |
---|
| 80 | \fItimeVal\fR |
---|
| 81 | An integer value passed to the \fBclock\fR command that represents an |
---|
| 82 | absolute time as a number of seconds from the \fIepoch time\fR of |
---|
| 83 | 1 January 1970, 00:00 UTC. Note that the count of seconds does not |
---|
| 84 | include any leap seconds; seconds are counted as if each UTC day has |
---|
| 85 | exactly 86400 seconds. Tcl responds to leap seconds by speeding or |
---|
| 86 | slowing its clock by a tiny fraction for some minutes until it is |
---|
| 87 | back in sync with UTC; its data model does not represent minutes that |
---|
| 88 | have 59 or 61 seconds. |
---|
| 89 | .TP |
---|
| 90 | \fIunit\fR |
---|
| 91 | One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR, |
---|
| 92 | \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or |
---|
| 93 | any unique prefix of such a word. Used in conjunction with \fIcount\fR |
---|
| 94 | to identify an interval of time, for example, \fI3 seconds\fR or |
---|
| 95 | \fI1 year\fR. |
---|
| 96 | .SS "OPTIONS" |
---|
| 97 | .TP |
---|
| 98 | \fB\-base\fR time |
---|
| 99 | Specifies that any relative times present in a \fBclock scan\fR command |
---|
| 100 | are to be given relative to \fItime\fR. \fItime\fR must be expressed as |
---|
| 101 | a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC. |
---|
| 102 | .TP |
---|
| 103 | \fB\-format\fR format |
---|
| 104 | Specifies the desired output format for \fBclock format\fR or the |
---|
| 105 | expected input format for \fBclock scan\fR. The \fIformat\fR string consists |
---|
| 106 | of any number of characters other than the per-cent sign |
---|
| 107 | .PQ \fB%\fR |
---|
| 108 | interspersed with any number of \fIformat groups\fR, which are two-character |
---|
| 109 | sequences beginning with the per-cent sign. The permissible format groups, |
---|
| 110 | and their interpretation, are described under \fBFORMAT GROUPS\fR. |
---|
| 111 | .RS |
---|
| 112 | .PP |
---|
| 113 | On \fBclock format\fR, the default format is |
---|
| 114 | .CS |
---|
| 115 | %a %b %d %H:%M:%S %z %Y |
---|
| 116 | .CE |
---|
| 117 | .PP |
---|
| 118 | On \fBclock scan\fR, the lack of a \fI\-format\fR option indicates that a |
---|
| 119 | .QW "free format scan" |
---|
| 120 | is requested; see \fBFREE FORM SCAN\fR for a description of what happens. |
---|
| 121 | .RE |
---|
| 122 | .TP |
---|
| 123 | \fB\-gmt\fR boolean |
---|
| 124 | If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR, |
---|
| 125 | \fBclock format\fR or \fBclock scan\fR should be processed in |
---|
| 126 | UTC. If \fIboolean\fR is false, the processing defaults to the local time |
---|
| 127 | zone. This usage is obsolete; the correct current usage is to |
---|
| 128 | specify the UTC time zone with |
---|
| 129 | .QW "\fB\-timezone\fR \fI:UTC\fR" |
---|
| 130 | or any of the equivalent ways to specify it. |
---|
| 131 | .TP |
---|
| 132 | \fB\-locale\fR localeName |
---|
| 133 | Specifies that locale-dependent scanning and formatting (and date arithmetic |
---|
| 134 | for dates preceding the adoption of the Gregorian calendar) is to be done in |
---|
| 135 | the locale identified by \fIlocaleName\fR. The locale name may be any of |
---|
| 136 | the locales acceptable to the \fBmsgcat\fR package, or it may be the special |
---|
| 137 | name \fIsystem\fR, which represents the current locale of the process, or |
---|
| 138 | the null string, which represents Tcl's default locale. |
---|
| 139 | .RS |
---|
| 140 | .PP |
---|
| 141 | The effect of locale on scanning and formatting is discussed in the |
---|
| 142 | descriptions of the individual format groups under \fBFORMAT GROUPS\fR. |
---|
| 143 | The effect of locale on clock arithmetic is discussed under |
---|
| 144 | \fBCLOCK ARITHMETIC\fR. |
---|
| 145 | .RE |
---|
| 146 | .TP |
---|
| 147 | \fB\-timezone\fR zoneName |
---|
| 148 | Specifies that clock arithmetic, formatting, and scanning are to be done |
---|
| 149 | according to the rules for the time zone specified by \fIzoneName\fR. |
---|
| 150 | The permissible values, and their interpretation, are discussed under |
---|
| 151 | \fBTIME ZONES\fR. |
---|
| 152 | On subcommands that expect a \fB\-timezone\fR argument, the default |
---|
| 153 | is to use the \fIcurrent time zone\fR. The current time zone is |
---|
| 154 | determined, in order of preference, by: |
---|
| 155 | .RS |
---|
| 156 | .IP [1] |
---|
| 157 | the environment variable \fBTCL_TZ\fR. |
---|
| 158 | .IP [2] |
---|
| 159 | the environment variable \fBTZ\fR. |
---|
| 160 | .IP [3] |
---|
| 161 | on Windows systems, the time zone settings from the Control Panel. |
---|
| 162 | .RE |
---|
| 163 | If none of these is present, the C \fBlocaltime\fR and \fBmktime\fR |
---|
| 164 | functions are used to attempt to convert times between local and |
---|
| 165 | Greenwich. On 32-bit systems, this approach is likely to have bugs, |
---|
| 166 | particularly for times that lie outside the window (approximately the |
---|
| 167 | years 1902 to 2037) that can be represented in a 32-bit integer. |
---|
| 168 | .SH "CLOCK ARITHMETIC" |
---|
| 169 | The \fBclock add\fR command performs clock arithmetic on a value |
---|
| 170 | (expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC) |
---|
| 171 | given as its first argument. The remaining arguments (other than the |
---|
| 172 | possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options) |
---|
| 173 | are integers and keywords in alternation, where the keywords are chosen |
---|
| 174 | from \fBseconds\fR, \fBminutes\fR, \fBhours\fR, |
---|
| 175 | \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or |
---|
| 176 | any unique prefix of such a word. |
---|
| 177 | .PP |
---|
| 178 | Addition of seconds, minutes and hours is fairly straightforward; |
---|
| 179 | the given time increment (times sixty for minutes, or 3600 for hours) |
---|
| 180 | is simply added to the \fItimeVal\fR given |
---|
| 181 | to the \fBclock add\fR command. The result is interpreted as |
---|
| 182 | a nominal number of seconds from the Epoch. |
---|
| 183 | .PP |
---|
| 184 | Surprising results |
---|
| 185 | may be obtained when crossing a point at which a leap second is |
---|
| 186 | inserted or removed; the \fBclock add\fR command simply ignores |
---|
| 187 | leap seconds and therefore assumes that times come in sequence, |
---|
| 188 | 23:59:58, 23:59:59, 00:00:00. (This assumption is handled by |
---|
| 189 | the fact that Tcl's model of time reacts to leap seconds by speeding |
---|
| 190 | or slowing the clock by a minuscule amount until Tcl's time |
---|
| 191 | is back in step with the world. |
---|
| 192 | .PP |
---|
| 193 | The fact that adding and subtracting hours is defined in terms of |
---|
| 194 | absolute time means that it will add fixed amounts of time in time zones |
---|
| 195 | that observe summer time (Daylight Saving Time). For example, |
---|
| 196 | the following code sets the value of \fBx\fR to \fB04:00:00\fR because |
---|
| 197 | the clock has changed in the interval in question. |
---|
| 198 | .CS |
---|
| 199 | set s [\fBclock scan\fR {2004-10-30 05:00:00} \e |
---|
| 200 | -format {%Y-%m-%d %H:%M:%S} \e |
---|
| 201 | -timezone :America/New_York] |
---|
| 202 | set a [\fBclock add\fR $s 24 hours -timezone :America/New_York] |
---|
| 203 | set x [\fBclock format\fR $a \e |
---|
| 204 | -format {%H:%M:%S} -timezone :America/New_York] |
---|
| 205 | .CE |
---|
| 206 | .PP |
---|
| 207 | Adding and subtracting days and weeks is accomplished by converting |
---|
| 208 | the given time to a calendar day and time of day in the appropriate |
---|
| 209 | time zone and locale. The requisite number of days (weeks are converted |
---|
| 210 | to days by multiplying by seven) is added to the calendar day, and |
---|
| 211 | the date and time are then converted back to a count of seconds from |
---|
| 212 | the epoch time. |
---|
| 213 | .PP |
---|
| 214 | Adding and subtracting a given number of days across the point that |
---|
| 215 | the time changes at the start or end of summer time (Daylight Saving Time) |
---|
| 216 | results in the \fIsame local time\fR on the day in question. For |
---|
| 217 | instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR. |
---|
| 218 | .CS |
---|
| 219 | set s [\fBclock scan\fR {2004-10-30 05:00:00} \e |
---|
| 220 | -format {%Y-%m-%d %H:%M:%S} \e |
---|
| 221 | -timezone :America/New_York] |
---|
| 222 | set a [\fBclock add\fR $s 1 day -timezone :America/New_York] |
---|
| 223 | set x [\fBclock format\fR $a \e |
---|
| 224 | -format {%H:%M:%S} -timezone :America/New_York] |
---|
| 225 | .CE |
---|
| 226 | .PP |
---|
| 227 | In cases of ambiguity, where the same local time happens twice |
---|
| 228 | on the same day, the earlier time is used. In cases where the conversion |
---|
| 229 | yields an impossible time (for instance, 02:30 during the Spring |
---|
| 230 | Daylight Saving Time change using US rules), the time is converted |
---|
| 231 | as if the clock had not changed. Thus, the following code |
---|
| 232 | will set the value of \fBx\fR to \fB03:30:00\fR. |
---|
| 233 | .CS |
---|
| 234 | set s [\fBclock scan\fR {2004-04-03 02:30:00} \e |
---|
| 235 | -format {%Y-%m-%d %H:%M:%S} \e |
---|
| 236 | -timezone :America/New_York] |
---|
| 237 | set a [\fBclock add\fR $s 1 day -timezone :America/New_York] |
---|
| 238 | set x [\fBclock format\fR $a \e |
---|
| 239 | -format {%H:%M:%S} -timezone :America/New_York] |
---|
| 240 | .CE |
---|
| 241 | .PP |
---|
| 242 | Adding a given number of days or weeks works correctly across the conversion |
---|
| 243 | between the Julian and Gregorian calendars; the omitted days are skipped. |
---|
| 244 | The following code sets \fBz\fR to \fB1752-09-14\fR. |
---|
| 245 | .CS |
---|
| 246 | set x [\fBclock scan\fR 1752-09-02 -format %Y-%m-%d -locale en_US] |
---|
| 247 | set y [\fBclock add\fR $x 1 day -locale en_US] |
---|
| 248 | set z [\fBclock format\fR $y -format %Y-%m-%d -locale en_US] |
---|
| 249 | .CE |
---|
| 250 | .PP |
---|
| 251 | In the bizarre case that adding the given number of days yields a date |
---|
| 252 | that does not exist because it falls within the dropped days of the |
---|
| 253 | Julian-to-Gregorian conversion, the date is converted as if it was |
---|
| 254 | on the Julian calendar. |
---|
| 255 | .PP |
---|
| 256 | Adding a number of months, or a number of years, is similar; it |
---|
| 257 | converts the given time to a calendar date and time of day. It then |
---|
| 258 | adds the requisite number of months or years, and reconverts the resulting |
---|
| 259 | date and time of day to an absolute time. |
---|
| 260 | .PP |
---|
| 261 | If the resulting date is impossible because the month has too few days |
---|
| 262 | (for example, when adding 1 month to 31 January), the last day of the |
---|
| 263 | month is substituted. Thus, adding 1 month to 31 January will result in |
---|
| 264 | 28 February in a common year or 29 February in a leap year. |
---|
| 265 | .PP |
---|
| 266 | The rules for handling anomalies relating to summer time and to the |
---|
| 267 | Gregorian calendar are the same when adding/subtracting months and |
---|
| 268 | years as they are when adding/subtracting days and weeks. |
---|
| 269 | .PP |
---|
| 270 | If multiple \fIcount unit\fR pairs are present on the command, they |
---|
| 271 | are evaluated consecutively, from left to right. |
---|
| 272 | .SH "HIGH RESOLUTION TIMERS" |
---|
| 273 | Most of the subcommands supported by the \fBclock\fR command deal with |
---|
| 274 | times represented as a count of seconds from the epoch time, and this is the |
---|
| 275 | representation that \fBclock seconds\fR returns. There are three exceptions, |
---|
| 276 | which are all intended for use where higher-resolution times are required. |
---|
| 277 | \fBclock milliseconds\fR returns the count of milliseconds from the |
---|
| 278 | epoch time, and \fBclock microseconds\fR returns the count of microseconds |
---|
| 279 | from the epoch time. In addition, there is a \fBclock clicks\fR command |
---|
| 280 | that returns a platform-dependent high-resolution timer. Unlike |
---|
| 281 | \fBclock seconds\fR and \fBclock milliseconds\fR, the value |
---|
| 282 | of \fBclock clicks\fR is not guaranteed to be tied to any fixed |
---|
| 283 | epoch; it is simply intended to be the most precise interval timer |
---|
| 284 | available, and is intended only for relative timing studies such as |
---|
| 285 | benchmarks. |
---|
| 286 | .SH "FORMATTING TIMES" |
---|
| 287 | The \fBclock format\fR command produces times for display to a user |
---|
| 288 | or writing to an external medium. The command accepts times that are |
---|
| 289 | expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC, |
---|
| 290 | as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR, |
---|
| 291 | \fBfile atime\fR or \fBfile mtime\fR. |
---|
| 292 | .PP |
---|
| 293 | If a \fB\-format\fR option is present, the following argument is |
---|
| 294 | a string that specifies how the date and time are to be formatted. |
---|
| 295 | The string consists |
---|
| 296 | of any number of characters other than the per-cent sign |
---|
| 297 | .PQ \fB%\fR |
---|
| 298 | interspersed with any number of \fIformat groups\fR, which are two-character |
---|
| 299 | sequences beginning with the per-cent sign. The permissible format groups, |
---|
| 300 | and their interpretation, are described under \fBFORMAT GROUPS\fR. |
---|
| 301 | .PP |
---|
| 302 | If a \fB\-timezone\fR option is present, the following |
---|
| 303 | argument is a string that specifies the time zone in which the date and time |
---|
| 304 | are to be formatted. As an alternative to |
---|
| 305 | .QW "\fB\-timezone\fR \fI:UTC\fR" , |
---|
| 306 | the obsolete usage |
---|
| 307 | .QW "\fB\-gmt\fR \fItrue\fR" |
---|
| 308 | may be used. See |
---|
| 309 | \fBTIME ZONES\fR for the permissible variants for the time zone. |
---|
| 310 | .PP |
---|
| 311 | If a \fB\-locale\fR option is present, the following argument is |
---|
| 312 | a string that specifies the locale in which the time is to be formatted, |
---|
| 313 | in the same format that is used for the \fBmsgcat\fR package. Note |
---|
| 314 | that the default, if \fB\-locale\fR is not specified, is the root locale |
---|
| 315 | \fB{}\fR rather than the current locale. The current locale may |
---|
| 316 | be obtained by using \fB\-locale\fR \fBcurrent\fR. |
---|
| 317 | In addition, some platforms support a \fBsystem\fR locale that |
---|
| 318 | reflects the user's current choices. For instance, on Windows, the |
---|
| 319 | format that the user has selected from dates and times in the Control |
---|
| 320 | Panel can be obtained by using the \fBsystem\fR locale. On |
---|
| 321 | platforms that do not define a user selection of date and time formats |
---|
| 322 | separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is |
---|
| 323 | synonymous with \fB\-locale\fR \fBcurrent\fR. |
---|
| 324 | .SH "SCANNING TIMES" |
---|
| 325 | The \fBclock scan\fR command accepts times that are formatted as |
---|
| 326 | strings and converts them to counts of seconds from the epoch time |
---|
| 327 | of 1 January 1970, 00:00 UTC. It normally takes a \fB\-format\fR |
---|
| 328 | option that is followed by a string describing |
---|
| 329 | the expected format of the input. (See |
---|
| 330 | \fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR |
---|
| 331 | without such an argument.) The string consists of any number of |
---|
| 332 | characters other than the per-cent sign |
---|
| 333 | .PQ \fB%\fR "" , |
---|
| 334 | interspersed with any number of \fIformat groups\fR, which are two-character |
---|
| 335 | sequences beginning with the per-cent sign. The permissible format groups, |
---|
| 336 | and their interpretation, are described under \fBFORMAT GROUPS\fR. |
---|
| 337 | .PP |
---|
| 338 | If a \fB\-timezone\fR option is present, the following |
---|
| 339 | argument is a string that specifies the time zone in which the date and time |
---|
| 340 | are to be interpreted. As an alternative to \fB\-timezone\fR \fI:UTC\fR, |
---|
| 341 | the obsolete usage \fB\-gmt\fR \fItrue\fR may be used. See |
---|
| 342 | \fBTIME ZONES\fR for the permissible variants for the time zone. |
---|
| 343 | .PP |
---|
| 344 | If a \fB\-locale\fR option is present, the following argument is |
---|
| 345 | a string that specifies the locale in which the time is to be interpreted, |
---|
| 346 | in the same format that is used for the \fBmsgcat\fR package. Note |
---|
| 347 | that the default, if \fB\-locale\fR is not specified, is the root locale |
---|
| 348 | \fB{}\fR rather than the current locale. The current locale may |
---|
| 349 | be obtained by using \fB\-locale\fR \fBcurrent\fR. |
---|
| 350 | In addition, some platforms support a \fBsystem\fR locale that |
---|
| 351 | reflects the user's current choices. For instance, on Windows, the |
---|
| 352 | format that the user has selected from dates and times in the Control |
---|
| 353 | Panel can be obtained by using the \fBsystem\fR locale. On |
---|
| 354 | platforms that do not define a user selection of date and time formats |
---|
| 355 | separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is |
---|
| 356 | synonymous with \fB\-locale\fR \fBcurrent\fR. |
---|
| 357 | .PP |
---|
| 358 | If a \fB\-base\fR option is present, the following argument is |
---|
| 359 | a time (expressed in seconds from the epoch time) that is used as |
---|
| 360 | a \fIbase time\fR for interpreting relative times. If no |
---|
| 361 | \fB\-base\fR option is present, the base time is the current time. |
---|
| 362 | .PP |
---|
| 363 | Scanning of times in fixed format works by determining three things: |
---|
| 364 | the date, the time of day, and the time zone. These three are then |
---|
| 365 | combined into a point in time, which is returned as the number of seconds |
---|
| 366 | from the epoch. |
---|
| 367 | .PP |
---|
| 368 | Before scanning begins, the format string is preprocessed |
---|
| 369 | to replace \fB%c\fR, \fB%Ec\fR, \fB%x\fR, \fB%Ex\fR, |
---|
| 370 | \fB%X\fR. \fB%Ex\fR, \fB%r\fR, \fB%R\fR, \fB%T\fR, |
---|
| 371 | \fB%D\fR, \fB%EY\fR and \fB%+\fR format groups with counterparts |
---|
| 372 | that are appropriate to the current locale and contain none of the |
---|
| 373 | above groups. For instance, \fB%D\fR will (in the \fBen_US\fR locale) |
---|
| 374 | be replaced with \fB%m/%d/%Y\fR. |
---|
| 375 | .PP |
---|
| 376 | The date is determined according to the fields that are present in the |
---|
| 377 | preprocessed format string. In order of preference: |
---|
| 378 | .IP [1] |
---|
| 379 | If the string contains a \fB%s\fR format group, representing |
---|
| 380 | seconds from the epoch, that group is used to determine the date. |
---|
| 381 | .IP [2] |
---|
| 382 | If the string contains a \fB%J\fR format group, representing |
---|
| 383 | the Julian Day Number, that group is used to determine the date. |
---|
| 384 | .IP [3] |
---|
| 385 | If the string contains a complete set of format groups specifying |
---|
| 386 | century, year, month, and day of month; century, year, and day of year; |
---|
| 387 | or ISO8601 fiscal year, week of year, and day of week; those groups are |
---|
| 388 | combined and used to determine the date. If more than one complete |
---|
| 389 | set is present, the one at the rightmost position in the string is |
---|
| 390 | used. |
---|
| 391 | .IP [4] |
---|
| 392 | If the string lacks a century but contains a set of format |
---|
| 393 | groups specifying year of century, month and day of month; year of |
---|
| 394 | century and day of year; or two-digit ISO8601 fiscal year, week of year, |
---|
| 395 | and day of week; those groups are |
---|
| 396 | combined and used to determine the date. If more than one complete |
---|
| 397 | set is present, the one at the rightmost position in the string is |
---|
| 398 | used. The year is presumed to lie in the range 1938 to 2037 inclusive. |
---|
| 399 | .IP [5] |
---|
| 400 | If the string entirely lacks any specification for the year |
---|
| 401 | (or contains the year only on the locale's alternative calendar) |
---|
| 402 | and contains a set of format groups specifying month and day of month, |
---|
| 403 | day of year, or week of year and day of week, those groups are |
---|
| 404 | combined and used to determine the date. If more than one complete |
---|
| 405 | set is present, the one at the rightmost position in the string is |
---|
| 406 | used. The year is determined by interpreting the base time in the given |
---|
| 407 | time zone. |
---|
| 408 | .IP [6] |
---|
| 409 | If the string contains none of the above sets, but has a day |
---|
| 410 | of the month or day of the week, the day of the month or day of the week |
---|
| 411 | are used to determine the date by interpreting the base time in the |
---|
| 412 | given time zone and returning the given day of the current week or month. |
---|
| 413 | (The week runs from Monday to Sunday, ISO8601-fashion.) If both day |
---|
| 414 | of month and day of week are present, the day of the month takes |
---|
| 415 | priority. |
---|
| 416 | .IP [7] |
---|
| 417 | If none of the above rules results in a usable date, the date |
---|
| 418 | of the base time in the given time zone is used. |
---|
| 419 | .PP |
---|
| 420 | The time is also determined according to the fields that are present in the |
---|
| 421 | preprocessed format string. In order of preference: |
---|
| 422 | .IP [1] |
---|
| 423 | If the string contains a \fB%s\fR format group, representing |
---|
| 424 | seconds from the epoch, that group determines the time of day. |
---|
| 425 | .IP [2] |
---|
| 426 | If the string contains either an hour on the 24-hour clock |
---|
| 427 | or an hour on the 12-hour clock plus an AM/PM indicator, that hour determines |
---|
| 428 | the hour of the day. If the string further contains a group specifying |
---|
| 429 | the minute of the hour, that group combines with the hour. If the string |
---|
| 430 | further contains a group specifying the second of the minute, that group |
---|
| 431 | combines with the hour and minute. |
---|
| 432 | .IP [3] |
---|
| 433 | If the string contains neither a \fB%s\fR format group nor |
---|
| 434 | a group specifying the hour of the day, then midnight (\fB00:00\fR, the start |
---|
| 435 | of the given date) is used. |
---|
| 436 | The time zone is determined by either the \fB\-timezone\fR or \fB\-gmt\fR |
---|
| 437 | options, or by using the current time zone. |
---|
| 438 | .PP |
---|
| 439 | If a format string lacks a \fB%z\fR or \fB%Z\fR format group, |
---|
| 440 | it is possible for the time to be ambiguous because it appears twice |
---|
| 441 | in the same day, once without and once with Daylight Saving Time. |
---|
| 442 | If this situation occurs, the first occurrence of the time is chosen. |
---|
| 443 | (For this reason, it is wise to have the input string contain the |
---|
| 444 | time zone when converting local times. This caveat does not apply to |
---|
| 445 | UTC times.) |
---|
| 446 | .SH "FORMAT GROUPS" |
---|
| 447 | The following format groups are recognized by the \fBclock scan\fR and |
---|
| 448 | \fBclock format\fR commands. |
---|
| 449 | .TP |
---|
| 450 | \fB%a\fR |
---|
| 451 | On output, receives an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day |
---|
| 452 | of the week in the given locale. On input, matches the name of the day |
---|
| 453 | of the week in the given locale (in either abbreviated or full form, or |
---|
| 454 | any unique prefix of either form). |
---|
| 455 | .TP |
---|
| 456 | \fB%A\fR |
---|
| 457 | On output, receives the full name (\fIe.g.,\fR \fBMonday\fR) of the day |
---|
| 458 | of the week in the given locale. On input, matches the name of the day |
---|
| 459 | of the week in the given locale (in either abbreviated or full form, or |
---|
| 460 | any unique prefix of either form). |
---|
| 461 | .TP |
---|
| 462 | \fB%b\fR |
---|
| 463 | On output, receives an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name |
---|
| 464 | of the month in the given locale. On input, matches the name of the month |
---|
| 465 | in the given locale (in either abbreviated or full form, or |
---|
| 466 | any unique prefix of either form). |
---|
| 467 | .TP |
---|
| 468 | \fB%B\fR |
---|
| 469 | On output, receives the full name (\fIe.g.,\fR \fBJanuary\fR) |
---|
| 470 | of the month in the given locale. On input, matches the name of the month |
---|
| 471 | in the given locale (in either abbreviated or full form, or |
---|
| 472 | any unique prefix of either form). |
---|
| 473 | .TP |
---|
| 474 | \fB%c\fR |
---|
| 475 | On output, receives a localized representation of date and time of day; |
---|
| 476 | the localized representation is expected to use the Gregorian calendar. |
---|
| 477 | On input, matches whatever \fB%c\fR produces. |
---|
| 478 | .TP |
---|
| 479 | \fB%C\fR |
---|
| 480 | On output, receives the number of the century in Indo-Arabic numerals. |
---|
| 481 | On input, matches one or two digits, possibly with leading whitespace, |
---|
| 482 | that are expected to be the number of the century. |
---|
| 483 | .TP |
---|
| 484 | \fB%d\fR |
---|
| 485 | On output, produces the number of the day of the month, as two decimal |
---|
| 486 | digits. On input, matches one or two digits, possibly with leading |
---|
| 487 | whitespace, that are expected to be the number of the day of the month. |
---|
| 488 | .TP |
---|
| 489 | \fB%D\fR |
---|
| 490 | This format group is synonymous with \fB%m/%d/%Y\fR. It should be |
---|
| 491 | used only in exchanging data within the \fBen_US\fR locale, since |
---|
| 492 | other locales typically do not use this order for the fields of the date. |
---|
| 493 | .TP |
---|
| 494 | \fB%e\fR |
---|
| 495 | On output, produces the number of the day of the month, as one or |
---|
| 496 | two decimal digits (with a leading blank for one-digit dates). |
---|
| 497 | On input, matches one or two digits, possibly with leading |
---|
| 498 | whitespace, that are expected to be the number of the day of the month. |
---|
| 499 | .TP |
---|
| 500 | \fB%Ec\fR |
---|
| 501 | On output, produces a locale-dependent representation of the date and |
---|
| 502 | time of day in the locale's alternative calendar. On input, matches |
---|
| 503 | whatever \fB%Ec\fR produces. The locale's alternative calendar need not |
---|
| 504 | be the Gregorian calendar. |
---|
| 505 | .TP |
---|
| 506 | \fB%EC\fR |
---|
| 507 | On output, produces a locale-dependent name of an era in the locale's |
---|
| 508 | alternative calendar. On input, matches the name of the era or any |
---|
| 509 | unique prefix. |
---|
| 510 | .TP |
---|
| 511 | \fB%EE\fR |
---|
| 512 | On output, produces the string \fBB.C.E.\fR or \fBC.E.\fR, or a |
---|
| 513 | string of the same meaning in the locale, to indicate whether \fB%Y\fR refers |
---|
| 514 | to years before or after Year 1 of the Common Era. On input, accepts |
---|
| 515 | the string \fBB.C.E.\fR, \fBB.C.\fR, \fBC.E.\fR, \fBA.D.\fR, or the |
---|
| 516 | abbreviation appropriate to the current locale, and uses it to fix |
---|
| 517 | whether \fB%Y\fR refers to years before or after Year 1 of the |
---|
| 518 | Common Era. |
---|
| 519 | .TP |
---|
| 520 | \fB%Ex\fR |
---|
| 521 | On output, produces a locale-dependent representation of the date |
---|
| 522 | in the locale's alternative calendar. On input, matches |
---|
| 523 | whatever \fB%Ex\fR produces. The locale's alternative calendar need not |
---|
| 524 | be the Gregorian calendar. |
---|
| 525 | .TP |
---|
| 526 | \fB%EX\fR |
---|
| 527 | On output, produces a locale-dependent representation of the |
---|
| 528 | time of day in the locale's alternative numerals. On input, matches |
---|
| 529 | whatever \fB%EX\fR produces. |
---|
| 530 | .TP |
---|
| 531 | \fB%Ey\fR |
---|
| 532 | On output, produces a locale-dependent number of the year of the era |
---|
| 533 | in the locale's alternative calendar and numerals. On input, matches |
---|
| 534 | such a number. |
---|
| 535 | .TP |
---|
| 536 | \fB%EY\fR |
---|
| 537 | On output, produces a representation of the year in the locale's |
---|
| 538 | alternative calendar and numerals. On input, matches what \fB%EY\fR |
---|
| 539 | produces. Often synonymous with \fB%EC%Ey\fR. |
---|
| 540 | .TP |
---|
| 541 | \fB%g\fR |
---|
| 542 | On output, produces a two-digit year number suitable for use with |
---|
| 543 | the week-based ISO8601 calendar; that is, the year number corresponds |
---|
| 544 | to the week number produced by \fB%V\fR. On input, accepts such |
---|
| 545 | a two-digit year number, possibly with leading whitespace. |
---|
| 546 | .TP |
---|
| 547 | \fB%G\fR |
---|
| 548 | On output, produces a four-digit year number suitable for use with |
---|
| 549 | the week-based ISO8601 calendar; that is, the year number corresponds |
---|
| 550 | to the week number produced by \fB%V\fR. On input, accepts such |
---|
| 551 | a four-digit year number, possibly with leading whitespace. |
---|
| 552 | .TP |
---|
| 553 | \fB%h\fR |
---|
| 554 | This format group is synonymous with \fB%b\fR. |
---|
| 555 | .TP |
---|
| 556 | \fB%H\fR |
---|
| 557 | On output, produces a two-digit number giving the hour of the day |
---|
| 558 | (00-23) on a 24-hour clock. On input, accepts such a number. |
---|
| 559 | .TP |
---|
| 560 | \fB%I\fR |
---|
| 561 | On output, produces a two-digit number giving the hour of the day |
---|
| 562 | (12-11) on a 12-hour clock. On input, accepts such a number. |
---|
| 563 | .TP |
---|
| 564 | \fB%j\fR |
---|
| 565 | On output, produces a three-digit number giving the day of the year |
---|
| 566 | (001-366). On input, accepts such a number. |
---|
| 567 | .TP |
---|
| 568 | \fB%J\fR |
---|
| 569 | On output, produces a string of digits giving the Julian Day Number. |
---|
| 570 | On input, accepts a string of digits and interprets it as a Julian Day Number. |
---|
| 571 | The Julian Day Number is a count of the number of calendar days |
---|
| 572 | that have elapsed since 1 January, 4713 BCE of the proleptic |
---|
| 573 | Julian calendar. The epoch time of 1 January 1970 corresponds |
---|
| 574 | to Julian Day Number 2440588. |
---|
| 575 | .TP |
---|
| 576 | \fB%k\fR |
---|
| 577 | On output, produces a one- or two-digit number giving the hour of the day |
---|
| 578 | (0-23) on a 24-hour clock. On input, accepts such a number. |
---|
| 579 | .TP |
---|
| 580 | \fB%l\fR |
---|
| 581 | On output, produces a one- or two-digit number giving the hour of the day |
---|
| 582 | (12-11) on a 12-hour clock. On input, accepts such a number. |
---|
| 583 | .TP |
---|
| 584 | \fB%m\fR |
---|
| 585 | On output, produces the number of the month (01-12) with exactly two |
---|
| 586 | digits. On input, accepts two digits and interprets them as the number |
---|
| 587 | of the month. |
---|
| 588 | .TP |
---|
| 589 | \fB%M\fR |
---|
| 590 | On output, produces the number of the minute of the hour (00-59) |
---|
| 591 | with exactly two digits. On input, accepts two digits and interprets them |
---|
| 592 | as the number of the minute of the hour. |
---|
| 593 | .TP |
---|
| 594 | \fB%N\fR |
---|
| 595 | On output, produces the number of the month (1-12) with one or two digits, |
---|
| 596 | and a leading blank for one-digit dates. |
---|
| 597 | On input, accepts one or two digits, possibly with leading whitespace, |
---|
| 598 | and interprets them as the number of the month. |
---|
| 599 | .TP |
---|
| 600 | \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 |
---|
| 601 | All of these format groups are synonymous with their counterparts |
---|
| 602 | without the |
---|
| 603 | .QW \fBO\fR , |
---|
| 604 | except that the string is produced and parsed in the |
---|
| 605 | locale-dependent alternative numerals. |
---|
| 606 | .TP |
---|
| 607 | \fB%p\fR |
---|
| 608 | On output, produces an indicator for the part of the day, \fBAM\fR |
---|
| 609 | or \fBPM\fR, appropriate to the given locale. If the script of the |
---|
| 610 | given locale supports multiple letterforms, lowercase is preferred. |
---|
| 611 | On input, matches the representation \fBAM\fR or \fBPM\fR in |
---|
| 612 | the given locale, in either case. |
---|
| 613 | .TP |
---|
| 614 | \fB%P\fR |
---|
| 615 | On output, produces an indicator for the part of the day, \fBam\fR |
---|
| 616 | or \fBpm\fR, appropriate to the given locale. If the script of the |
---|
| 617 | given locale supports multiple letterforms, uppercase is preferred. |
---|
| 618 | On input, matches the representation \fBAM\fR or \fBPM\fR in |
---|
| 619 | the given locale, in either case. |
---|
| 620 | .TP |
---|
| 621 | \fB%Q\fR |
---|
| 622 | This format group is reserved for internal use within the Tcl library. |
---|
| 623 | .TP |
---|
| 624 | \fB%r\fR |
---|
| 625 | On output, produces a locale-dependent time of day representation on a |
---|
| 626 | 12-hour clock. On input, accepts whatever \fB%r\fR produces. |
---|
| 627 | .TP |
---|
| 628 | \fB%R\fR |
---|
| 629 | On output, produces a locale-dependent time of day representation on a |
---|
| 630 | 24-hour clock. On input, accepts whatever \fB%R\fR produces. |
---|
| 631 | .TP |
---|
| 632 | \fB%s\fR |
---|
| 633 | On output, simply formats the \fItimeVal\fR argument as a decimal |
---|
| 634 | integer and inserts it into the output string. On input, accepts |
---|
| 635 | a decimal integer and uses is as the time value without any further |
---|
| 636 | processing. Since \fB%s\fR uniquely determines a point in time, it |
---|
| 637 | overrides all other input formats. |
---|
| 638 | .TP |
---|
| 639 | \fB%S\fR |
---|
| 640 | On output, produces a two-digit number of the second of the minute |
---|
| 641 | (00-59). On input, accepts two digits and uses them as the second of the |
---|
| 642 | minute. |
---|
| 643 | .TP |
---|
| 644 | \fB%t\fR |
---|
| 645 | On output, produces a TAB character. On input, matches a TAB character. |
---|
| 646 | .TP |
---|
| 647 | \fB%T\fR |
---|
| 648 | Synonymous with \fB%H:%M:%S\fR. |
---|
| 649 | .TP |
---|
| 650 | \fB%u\fR |
---|
| 651 | On output, produces the number of the day of the week |
---|
| 652 | (\fB1\fR\(->Monday, \fB7\fR\(->Sunday). On input, accepts a single digit and |
---|
| 653 | interprets it as the day of the week. Sunday may be either \fB0\fR or |
---|
| 654 | \fB7\fR. |
---|
| 655 | .TP |
---|
| 656 | \fB%U\fR |
---|
| 657 | On output, produces the ordinal number of the week of the year |
---|
| 658 | (00-53). The first Sunday of the year is the first day of week 01. On |
---|
| 659 | input accepts two digits which are otherwise ignored. This format |
---|
| 660 | group is never used in determining an input date. This interpretation |
---|
| 661 | of the week of the year was once common in US banking but is now |
---|
| 662 | largely obsolete. See \fB%V\fR for the ISO8601 week number. |
---|
| 663 | .TP |
---|
| 664 | \fB%V\fR |
---|
| 665 | On output, produces the number of the ISO8601 week as a two digit |
---|
| 666 | number (01-53). Week 01 is the week containing January 4; or the first |
---|
| 667 | week of the year containing at least 4 days; or the week containing |
---|
| 668 | the first Thursday of the year (the three statements are |
---|
| 669 | equivalent). Each week begins on a Monday. On input, accepts the |
---|
| 670 | ISO8601 week number. |
---|
| 671 | .TP |
---|
| 672 | \fB%w\fR |
---|
| 673 | On output, produces the ordinal number of the day of the week |
---|
| 674 | (Sunday==0; Saturday==6). On input, accepts a single digit and |
---|
| 675 | interprets it as the day of the week; Sunday may be represented as |
---|
| 676 | either 0 or 7. Note that \fB%w\fR is not the ISO8601 weekday number, |
---|
| 677 | which is produced and accepted by \fB%u\fR. |
---|
| 678 | .TP |
---|
| 679 | \fB%W\fR |
---|
| 680 | On output, produces a week number (00-53) within the year; week 01 |
---|
| 681 | begins on the first Monday of the year. On input, accepts two digits, |
---|
| 682 | which are otherwise ignored. This format group is never used in |
---|
| 683 | determining an input date. It is not the ISO8601 week number; that |
---|
| 684 | week is produced and accepted by \fB%V\fR. |
---|
| 685 | .TP |
---|
| 686 | \fB%x\fR |
---|
| 687 | On output, produces the date in a locale-dependent representation. On |
---|
| 688 | input, accepts whatever \fB%x\fR produces and is used to determine |
---|
| 689 | calendar date. |
---|
| 690 | .TP |
---|
| 691 | \fB%X\fR |
---|
| 692 | On output, produces the time of day in a locale-dependent |
---|
| 693 | representation. On input, accepts whatever \fB%X\fR produces and is used |
---|
| 694 | to determine time of day. |
---|
| 695 | .TP |
---|
| 696 | \fB%y\fR |
---|
| 697 | On output, produces the two-digit year of the century. On input, |
---|
| 698 | accepts two digits, and is used to determine calendar date. The |
---|
| 699 | date is presumed to lie between 1938 and 2037 inclusive. Note |
---|
| 700 | that \fB%y\fR does not yield a year appropriate for use with the ISO8601 |
---|
| 701 | week number \fB%V\fR; programs should use \fB%g\fR for that purpose. |
---|
| 702 | .TP |
---|
| 703 | \fB%Y\fR |
---|
| 704 | On output, produces the four-digit calendar year. On input, |
---|
| 705 | accepts four digits and may be used to determine calendar date. Note |
---|
| 706 | that \fB%Y\fR does not yield a year appropriate for use with the ISO8601 |
---|
| 707 | week number \fB%V\fR; programs should use \fB%G\fR for that purpose. |
---|
| 708 | .TP |
---|
| 709 | \fB%z\fR |
---|
| 710 | On output, produces the current time zone, expressed in hours and |
---|
| 711 | minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a |
---|
| 712 | time zone specifier (see \fBTIME ZONES\fR below) that will be used to |
---|
| 713 | determine the time zone. |
---|
| 714 | .TP |
---|
| 715 | \fB%Z\fR |
---|
| 716 | On output, produces the current time zone's name, possibly |
---|
| 717 | translated to the given locale. On input, accepts a time zone |
---|
| 718 | specifier (see \fBTIME ZONES\fR below) that will be used to determine the |
---|
| 719 | time zone. This option should, in general, be used on input only when |
---|
| 720 | parsing RFC822 dates. Other uses are fraught with ambiguity; for |
---|
| 721 | instance, the string \fBBST\fR may represent British Summer Time or |
---|
| 722 | Brazilian Standard Time. It is recommended that date/time strings for |
---|
| 723 | use by computers use numeric time zones instead. |
---|
| 724 | .TP |
---|
| 725 | \fB%%\fR |
---|
| 726 | On output, produces a literal |
---|
| 727 | .QW \fB%\fR |
---|
| 728 | character. On input, matches a literal |
---|
| 729 | .QW \fB%\fR |
---|
| 730 | character. |
---|
| 731 | .TP |
---|
| 732 | \fB%+\fR |
---|
| 733 | Synonymous with |
---|
| 734 | .QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" . |
---|
| 735 | .SH "TIME ZONES" |
---|
| 736 | When the \fBclock\fR command is processing a local time, it has several |
---|
| 737 | possible sources for the time zone to use. In order of preference, they |
---|
| 738 | are: |
---|
| 739 | .IP [1] |
---|
| 740 | A time zone specified inside a string being parsed and matched by a \fB%z\fR |
---|
| 741 | or \fB%Z\fR format group. |
---|
| 742 | .IP [2] |
---|
| 743 | A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR |
---|
| 744 | command (or, equivalently, by \fB\-gmt\fR \fB1\fR). |
---|
| 745 | .IP [3] |
---|
| 746 | A time zone specified in an environment variable \fBTCL_TZ\fR. |
---|
| 747 | .IP [4] |
---|
| 748 | A time zone specified in an environment variable \fBTZ\fR. |
---|
| 749 | .IP [5] |
---|
| 750 | The local time zone from the Control Panel on Windows systems. |
---|
| 751 | .IP [6] |
---|
| 752 | The C library's idea of the local time zone, as defined by the |
---|
| 753 | \fBmktime\fR and \fBlocaltime\fR functions. |
---|
| 754 | .PP |
---|
| 755 | In case [1] \fIonly,\fR the string is tested to see if it is one |
---|
| 756 | of the strings: |
---|
| 757 | .CS |
---|
| 758 | gmt ut utc bst wet wat at |
---|
| 759 | nft nst ndt ast adt est edt |
---|
| 760 | cst cdt mst mdt pst pdt yst |
---|
| 761 | ydt hst hdt cat ahst nt idlw |
---|
| 762 | cet cest met mewt mest swt sst |
---|
| 763 | eet eest bt it zp4 zp5 ist |
---|
| 764 | zp6 wast wadt jt cct jst cast |
---|
| 765 | cadt east eadt gst nzt nzst nzdt |
---|
| 766 | idle |
---|
| 767 | .CE |
---|
| 768 | If it is a string in the above list, it designates a known |
---|
| 769 | time zone, and is interpreted as such. |
---|
| 770 | .PP |
---|
| 771 | For time zones in case [1] that do not match any of the above strings, |
---|
| 772 | and always for cases [2]-[6], the following rules apply. |
---|
| 773 | .PP |
---|
| 774 | If the time zone begins with a colon, it is one of a |
---|
| 775 | standardized list of names like \fB:America/New_York\fR |
---|
| 776 | that give the rules for various locales. A complete list |
---|
| 777 | of the location names is too lengthy to be listed here. |
---|
| 778 | On most Tcl installations, the definitions of the locations |
---|
| 779 | are to be found in named files in the directory |
---|
| 780 | .QW "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR" . |
---|
| 781 | On some Unix systems, these files are omitted, and the definitions are |
---|
| 782 | instead obtained from system files in |
---|
| 783 | .QW "\fI/usr/share/zoneinfo\fR" , |
---|
| 784 | .QW "\fI/usr/share/lib/zoneinfo\fR" |
---|
| 785 | or |
---|
| 786 | .QW "\fI/usr/local/etc/zoneinfo\fR" . |
---|
| 787 | As a special case, the name \fB:localtime\fR refers to |
---|
| 788 | the local time zone as defined by the C library. |
---|
| 789 | .PP |
---|
| 790 | A time zone string consisting of a plus or minus sign followed by |
---|
| 791 | four or six decimal digits is interpreted as an offset in |
---|
| 792 | hours, minutes, and seconds (if six digits are present) from |
---|
| 793 | UTC. The plus sign denotes a sign east of Greenwich; |
---|
| 794 | the minus sign one west of Greenwich. |
---|
| 795 | .PP |
---|
| 796 | A time zone string conforming to the Posix specification of the \fBTZ\fR |
---|
| 797 | environment variable will be recognized. The specification |
---|
| 798 | may be found at |
---|
| 799 | \fIhttp://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR. |
---|
| 800 | .PP |
---|
| 801 | Any other time zone string is processed by prefixing a colon and attempting |
---|
| 802 | to use it as a location name, as above. |
---|
| 803 | .SH "LOCALIZATION" |
---|
| 804 | Developers wishing to localize the date and time formatting and parsing |
---|
| 805 | are referred to \fIhttp://tip.tcl.tk/173\fR for a |
---|
| 806 | specification. |
---|
| 807 | .SH "FREE FORM SCAN" |
---|
| 808 | If the \fBclock scan\fR command is invoked without a \fB\-format\fR |
---|
| 809 | option, then it requests a \fIfree-form scan.\fR \fI |
---|
| 810 | This form of scan is deprecated.\fR The reason for the deprecation |
---|
| 811 | is that there are too many ambiguities. (Does the string |
---|
| 812 | .QW 2000 |
---|
| 813 | represent a year, a time of day, or a quantity?) No set of rules |
---|
| 814 | for interpreting free-form dates and times has been found to |
---|
| 815 | give unsurprising results in all cases. |
---|
| 816 | .PP |
---|
| 817 | If free-form scan is used, only the \fB\-base\fR and \fB\-gmt\fR |
---|
| 818 | options are accepted. The \fB\-timezone\fR and \fB\-locale\fR |
---|
| 819 | options will result in an error if \fB\-format\fR is not supplied. |
---|
| 820 | .PP |
---|
| 821 | For the benefit of users who need to understand legacy code that |
---|
| 822 | uses free-form scan, the documentation for how free-form scan |
---|
| 823 | interprets a string is included here: |
---|
| 824 | .PP |
---|
| 825 | If only a time is |
---|
| 826 | specified, the current date is assumed. If the \fIinputString\fR |
---|
| 827 | does not contain a |
---|
| 828 | time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR |
---|
| 829 | argument is true, in which case the clock value is calculated assuming |
---|
| 830 | that the specified time is relative to Greenwich Mean Time. |
---|
| 831 | \fB\-gmt\fR, if specified, affects only the computed time value; it does not |
---|
| 832 | impact the interpretation of \fB\-base\fR. |
---|
| 833 | .PP |
---|
| 834 | If the \fB\-base\fR flag is specified, the next argument should contain |
---|
| 835 | an integer clock value. Only the date in this value is used, not the |
---|
| 836 | time. This is useful for determining the time on a specific day or |
---|
| 837 | doing other date-relative conversions. |
---|
| 838 | .PP |
---|
| 839 | The \fIinputString\fR argument consists of zero or more specifications of the |
---|
| 840 | following form: |
---|
| 841 | .TP |
---|
| 842 | \fItime\fR |
---|
| 843 | A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR |
---|
| 844 | or \fBhhmm ?meridian? ?zone?\fR |
---|
| 845 | If no meridian is specified, \fBhh\fR is interpreted on |
---|
| 846 | a 24-hour clock. |
---|
| 847 | .TP |
---|
| 848 | \fIdate\fR |
---|
| 849 | A specific month and day with optional year. The |
---|
| 850 | acceptable formats are |
---|
| 851 | .QW "\fBmm/dd\fR?\fB/yy\fR?" , |
---|
| 852 | .QW "\fBmonthname dd\fR?\fB, yy\fR?" , |
---|
| 853 | .QW "\fBday, dd monthname \fR?\fByy\fR?" , |
---|
| 854 | .QW "\fBdd monthname yy\fR" , |
---|
| 855 | .QW "?\fBCC\fR?\fByymmdd\fR" , |
---|
| 856 | and |
---|
| 857 | .QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" . |
---|
| 858 | The default year is the current year. If the year is less |
---|
| 859 | than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 |
---|
| 860 | as 1969-1999. Not all platforms can represent the years 38-70, so |
---|
| 861 | an error may result if these years are used. |
---|
| 862 | .TP |
---|
| 863 | \fIISO 8601 point-in-time\fR |
---|
| 864 | An ISO 8601 point-in-time specification, such as |
---|
| 865 | .QW \fICCyymmdd\fBT\fIhhmmss\fR, |
---|
| 866 | where \fBT\fR is the literal |
---|
| 867 | .QW T , |
---|
| 868 | .QW "\fICCyymmdd hhmmss\fR" , |
---|
| 869 | or |
---|
| 870 | .QW \fICCyymmdd\fBT\fIhh:mm:ss\fR . |
---|
| 871 | Note that only these three formats are accepted. |
---|
| 872 | The command does \fInot\fR accept the full range of point-in-time |
---|
| 873 | specifications specified in ISO8601. Other formats can be recognized by |
---|
| 874 | giving an explicit \fI\-format\fR option to the \fBclock scan\fR command. |
---|
| 875 | .TP |
---|
| 876 | \fIrelative time\fR |
---|
| 877 | A specification relative to the current time. The format is \fBnumber |
---|
| 878 | unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR, |
---|
| 879 | \fBmonth\fR, \fBweek\fR, \fBday\fR, |
---|
| 880 | \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR). The |
---|
| 881 | unit can be specified as a singular or plural, as in \fB3 weeks\fR. |
---|
| 882 | These modifiers may also be specified: |
---|
| 883 | \fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR, |
---|
| 884 | \fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR. |
---|
| 885 | .PP |
---|
| 886 | The actual date is calculated according to the following steps. |
---|
| 887 | .PP |
---|
| 888 | First, any absolute date and/or time is processed and converted. |
---|
| 889 | Using that time as the base, day-of-week specifications are added. |
---|
| 890 | Next, relative specifications are used. If a date or day is |
---|
| 891 | specified, and no absolute or relative time is given, midnight is |
---|
| 892 | used. Finally, a correction is applied so that the correct hour of |
---|
| 893 | the day is produced after allowing for daylight savings time |
---|
| 894 | differences and the correct date is given when going from the end |
---|
| 895 | of a long month to a short month. |
---|
| 896 | .SH "SEE ALSO" |
---|
| 897 | msgcat(n) |
---|
| 898 | .SH KEYWORDS |
---|
| 899 | clock, date, time |
---|
| 900 | .SH "COPYRIGHT" |
---|
| 901 | Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. |
---|