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.
5 .TH "clock" n 8.5 Tcl "Tcl Built-In Commands"
9 clock \- Obtain and manipulate dates and times
11 package require \fBTcl 8.5\fR
13 \fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
15 \fBclock clicks\fR ?\fI\-option\fR?
17 \fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
19 \fBclock microseconds\fR
21 \fBclock milliseconds\fR
23 \fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
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.
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.
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.
45 If the \fI\-option\fR argument is \fB\-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.
50 If the \fI\-option\fR argument is \fB\-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.
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.
61 \fBclock microseconds\fR
62 Returns the current time as an integer number of microseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description.
64 \fBclock milliseconds\fR
65 Returns the current time as an integer number of milliseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description.
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.
73 Returns the current time as an integer number of seconds.
77 An integer representing a count of some unit of time. See
78 \fBCLOCK ARITHMETIC\fR for the details.
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.
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
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.
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
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.
113 On \fBclock format\fR, the default format is
116 %a %b %d %H:%M:%S %Z %Y
119 On \fBclock scan\fR, the lack of a \fB\-format\fR option indicates that a
120 .QW "free format scan"
121 is requested; see \fBFREE FORM SCAN\fR for a description of what happens.
125 If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR,
126 \fBclock format\fR or \fBclock scan\fR should be processed in
127 UTC. If \fIboolean\fR is false, the processing defaults to the local time
128 zone. This usage is obsolete; the correct current usage is to
129 specify the UTC time zone with
130 .QW "\fB\-timezone\fR \fI:UTC\fR"
131 or any of the equivalent ways to specify it.
133 \fB\-locale\fR localeName
134 Specifies that locale-dependent scanning and formatting (and date arithmetic
135 for dates preceding the adoption of the Gregorian calendar) is to be done in
136 the locale identified by \fIlocaleName\fR. The locale name may be any of
137 the locales acceptable to the \fBmsgcat\fR package, or it may be the special
138 name \fIsystem\fR, which represents the current locale of the process, or
139 the null string, which represents Tcl's default locale.
142 The effect of locale on scanning and formatting is discussed in the
143 descriptions of the individual format groups under \fBFORMAT GROUPS\fR.
144 The effect of locale on clock arithmetic is discussed under
145 \fBCLOCK ARITHMETIC\fR.
148 \fB\-timezone\fR zoneName
149 Specifies that clock arithmetic, formatting, and scanning are to be done
150 according to the rules for the time zone specified by \fIzoneName\fR.
151 The permissible values, and their interpretation, are discussed under
153 On subcommands that expect a \fB\-timezone\fR argument, the default
154 is to use the \fIcurrent time zone\fR. The current time zone is
155 determined, in order of preference, by:
158 the environment variable \fBTCL_TZ\fR.
160 the environment variable \fBTZ\fR.
162 on Windows systems, the time zone settings from the Control Panel.
165 If none of these is present, the C \fBlocaltime\fR and \fBmktime\fR
166 functions are used to attempt to convert times between local and
167 Greenwich. On 32-bit systems, this approach is likely to have bugs,
168 particularly for times that lie outside the window (approximately the
169 years 1902 to 2037) that can be represented in a 32-bit integer.
170 .SH "CLOCK ARITHMETIC"
172 The \fBclock add\fR command performs clock arithmetic on a value
173 (expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC)
174 given as its first argument. The remaining arguments (other than the
175 possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options)
176 are integers and keywords in alternation, where the keywords are chosen
177 from \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
178 \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
179 any unique prefix of such a word.
181 Addition of seconds, minutes and hours is fairly straightforward;
182 the given time increment (times sixty for minutes, or 3600 for hours)
183 is simply added to the \fItimeVal\fR given
184 to the \fBclock add\fR command. The result is interpreted as
185 a nominal number of seconds from the Epoch.
188 may be obtained when crossing a point at which a leap second is
189 inserted or removed; the \fBclock add\fR command simply ignores
190 leap seconds and therefore assumes that times come in sequence,
191 23:59:58, 23:59:59, 00:00:00. (This assumption is handled by
192 the fact that Tcl's model of time reacts to leap seconds by speeding
193 or slowing the clock by a minuscule amount until Tcl's time
194 is back in step with the world.
196 The fact that adding and subtracting hours is defined in terms of
197 absolute time means that it will add fixed amounts of time in time zones
198 that observe summer time (Daylight Saving Time). For example,
199 the following code sets the value of \fBx\fR to \fB04:00:00\fR because
200 the clock has changed in the interval in question.
203 set s [\fBclock scan\fR {2004-10-30 05:00:00} \e
204 -format {%Y-%m-%d %H:%M:%S} \e
205 -timezone :America/New_York]
206 set a [\fBclock add\fR $s 24 hours -timezone :America/New_York]
207 set x [\fBclock format\fR $a \e
208 -format {%H:%M:%S} -timezone :America/New_York]
211 Adding and subtracting days and weeks is accomplished by converting
212 the given time to a calendar day and time of day in the appropriate
213 time zone and locale. The requisite number of days (weeks are converted
214 to days by multiplying by seven) is added to the calendar day, and
215 the date and time are then converted back to a count of seconds from
218 Adding and subtracting a given number of days across the point that
219 the time changes at the start or end of summer time (Daylight Saving Time)
220 results in the \fIsame local time\fR on the day in question. For
221 instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR.
224 set s [\fBclock scan\fR {2004-10-30 05:00:00} \e
225 -format {%Y-%m-%d %H:%M:%S} \e
226 -timezone :America/New_York]
227 set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
228 set x [\fBclock format\fR $a \e
229 -format {%H:%M:%S} -timezone :America/New_York]
232 In cases of ambiguity, where the same local time happens twice
233 on the same day, the earlier time is used. In cases where the conversion
234 yields an impossible time (for instance, 02:30 during the Spring
235 Daylight Saving Time change using US rules), the time is converted
236 as if the clock had not changed. Thus, the following code
237 will set the value of \fBx\fR to \fB03:30:00\fR.
240 set s [\fBclock scan\fR {2004-04-03 02:30:00} \e
241 -format {%Y-%m-%d %H:%M:%S} \e
242 -timezone :America/New_York]
243 set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
244 set x [\fBclock format\fR $a \e
245 -format {%H:%M:%S} -timezone :America/New_York]
248 Adding a given number of days or weeks works correctly across the conversion
249 between the Julian and Gregorian calendars; the omitted days are skipped.
250 The following code sets \fBz\fR to \fB1752-09-14\fR.
253 set x [\fBclock scan\fR 1752-09-02 -format %Y-%m-%d -locale en_US]
254 set y [\fBclock add\fR $x 1 day -locale en_US]
255 set z [\fBclock format\fR $y -format %Y-%m-%d -locale en_US]
258 In the bizarre case that adding the given number of days yields a date
259 that does not exist because it falls within the dropped days of the
260 Julian-to-Gregorian conversion, the date is converted as if it was
261 on the Julian calendar.
263 Adding a number of months, or a number of years, is similar; it
264 converts the given time to a calendar date and time of day. It then
265 adds the requisite number of months or years, and reconverts the resulting
266 date and time of day to an absolute time.
268 If the resulting date is impossible because the month has too few days
269 (for example, when adding 1 month to 31 January), the last day of the
270 month is substituted. Thus, adding 1 month to 31 January will result in
271 28 February in a common year or 29 February in a leap year.
273 The rules for handling anomalies relating to summer time and to the
274 Gregorian calendar are the same when adding/subtracting months and
275 years as they are when adding/subtracting days and weeks.
277 If multiple \fIcount unit\fR pairs are present on the command, they
278 are evaluated consecutively, from left to right.
279 .SH "HIGH RESOLUTION TIMERS"
281 Most of the subcommands supported by the \fBclock\fR command deal with
282 times represented as a count of seconds from the epoch time, and this is the
283 representation that \fBclock seconds\fR returns. There are three exceptions,
284 which are all intended for use where higher-resolution times are required.
285 \fBclock milliseconds\fR returns the count of milliseconds from the
286 epoch time, and \fBclock microseconds\fR returns the count of microseconds
287 from the epoch time. In addition, there is a \fBclock clicks\fR command
288 that returns a platform-dependent high-resolution timer. Unlike
289 \fBclock seconds\fR and \fBclock milliseconds\fR, the value
290 of \fBclock clicks\fR is not guaranteed to be tied to any fixed
291 epoch; it is simply intended to be the most precise interval timer
292 available, and is intended only for relative timing studies such as
294 .SH "FORMATTING TIMES"
296 The \fBclock format\fR command produces times for display to a user
297 or writing to an external medium. The command accepts times that are
298 expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC,
299 as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR,
300 \fBfile atime\fR or \fBfile mtime\fR.
302 If a \fB\-format\fR option is present, the following argument is
303 a string that specifies how the date and time are to be formatted.
305 of any number of characters other than the per-cent sign
307 interspersed with any number of \fIformat groups\fR, which are two-character
308 sequences beginning with the per-cent sign. The permissible format groups,
309 and their interpretation, are described under \fBFORMAT GROUPS\fR.
311 If a \fB\-timezone\fR option is present, the following
312 argument is a string that specifies the time zone in which the date and time
313 are to be formatted. As an alternative to
314 .QW "\fB\-timezone\fR \fI:UTC\fR" ,
316 .QW "\fB\-gmt\fR \fItrue\fR"
318 \fBTIME ZONES\fR for the permissible variants for the time zone.
320 If a \fB\-locale\fR option is present, the following argument is
321 a string that specifies the locale in which the time is to be formatted,
322 in the same format that is used for the \fBmsgcat\fR package. Note
323 that the default, if \fB\-locale\fR is not specified, is the root locale
324 \fB{}\fR rather than the current locale. The current locale may
325 be obtained by using \fB\-locale\fR \fBcurrent\fR.
326 In addition, some platforms support a \fBsystem\fR locale that
327 reflects the user's current choices. For instance, on Windows, the
328 format that the user has selected from dates and times in the Control
329 Panel can be obtained by using the \fBsystem\fR locale. On
330 platforms that do not define a user selection of date and time formats
331 separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is
332 synonymous with \fB\-locale\fR \fBcurrent\fR.
335 The \fBclock scan\fR command accepts times that are formatted as
336 strings and converts them to counts of seconds from the epoch time
337 of 1 January 1970, 00:00 UTC. It normally takes a \fB\-format\fR
338 option that is followed by a string describing
339 the expected format of the input. (See
340 \fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR
341 without such an argument.) The string consists of any number of
342 characters other than the per-cent sign
344 interspersed with any number of \fIformat groups\fR, which are two-character
345 sequences beginning with the per-cent sign. The permissible format groups,
346 and their interpretation, are described under \fBFORMAT GROUPS\fR.
348 If a \fB\-timezone\fR option is present, the following
349 argument is a string that specifies the time zone in which the date and time
350 are to be interpreted. As an alternative to \fB\-timezone\fR \fI:UTC\fR,
351 the obsolete usage \fB\-gmt\fR \fItrue\fR may be used. See
352 \fBTIME ZONES\fR for the permissible variants for the time zone.
354 If a \fB\-locale\fR option is present, the following argument is
355 a string that specifies the locale in which the time is to be interpreted,
356 in the same format that is used for the \fBmsgcat\fR package. Note
357 that the default, if \fB\-locale\fR is not specified, is the root locale
358 \fB{}\fR rather than the current locale. The current locale may
359 be obtained by using \fB\-locale\fR \fBcurrent\fR.
360 In addition, some platforms support a \fBsystem\fR locale that
361 reflects the user's current choices. For instance, on Windows, the
362 format that the user has selected from dates and times in the Control
363 Panel can be obtained by using the \fBsystem\fR locale. On
364 platforms that do not define a user selection of date and time formats
365 separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is
366 synonymous with \fB\-locale\fR \fBcurrent\fR.
368 If a \fB\-base\fR option is present, the following argument is
369 a time (expressed in seconds from the epoch time) that is used as
370 a \fIbase time\fR for interpreting relative times. If no
371 \fB\-base\fR option is present, the base time is the current time.
373 Scanning of times in fixed format works by determining three things:
374 the date, the time of day, and the time zone. These three are then
375 combined into a point in time, which is returned as the number of seconds
378 Before scanning begins, the format string is preprocessed
379 to replace \fB%c\fR, \fB%Ec\fR, \fB%x\fR, \fB%Ex\fR,
380 \fB%X\fR. \fB%Ex\fR, \fB%r\fR, \fB%R\fR, \fB%T\fR,
381 \fB%D\fR, \fB%EY\fR and \fB%+\fR format groups with counterparts
382 that are appropriate to the current locale and contain none of the
383 above groups. For instance, \fB%D\fR will (in the \fBen_US\fR locale)
384 be replaced with \fB%m/%d/%Y\fR.
386 The date is determined according to the fields that are present in the
387 preprocessed format string. In order of preference:
389 If the string contains a \fB%s\fR format group, representing
390 seconds from the epoch, that group is used to determine the date.
392 If the string contains a \fB%J\fR format group, representing
393 the Julian Day Number, that group is used to determine the date.
395 If the string contains a complete set of format groups specifying
396 century, year, month, and day of month; century, year, and day of year;
397 or ISO8601 fiscal year, week of year, and day of week; those groups are
398 combined and used to determine the date. If more than one complete
399 set is present, the one at the rightmost position in the string is
402 If the string lacks a century but contains a set of format
403 groups specifying year of century, month and day of month; year of
404 century and day of year; or two-digit ISO8601 fiscal year, week of year,
405 and day of week; those groups are
406 combined and used to determine the date. If more than one complete
407 set is present, the one at the rightmost position in the string is
408 used. The year is presumed to lie in the range 1938 to 2037 inclusive.
410 If the string entirely lacks any specification for the year
411 (or contains the year only on the locale's alternative calendar)
412 and contains a set of format groups specifying month and day of month,
413 day of year, or week of year and day of week, those groups are
414 combined and used to determine the date. If more than one complete
415 set is present, the one at the rightmost position in the string is
416 used. The year is determined by interpreting the base time in the given
419 If the string contains none of the above sets, but has a day
420 of the month or day of the week, the day of the month or day of the week
421 are used to determine the date by interpreting the base time in the
422 given time zone and returning the given day of the current week or month.
423 (The week runs from Monday to Sunday, ISO8601-fashion.) If both day
424 of month and day of week are present, the day of the month takes
427 If none of the above rules results in a usable date, the date
428 of the base time in the given time zone is used.
430 The time is also determined according to the fields that are present in the
431 preprocessed format string. In order of preference:
433 If the string contains a \fB%s\fR format group, representing
434 seconds from the epoch, that group determines the time of day.
436 If the string contains either an hour on the 24-hour clock
437 or an hour on the 12-hour clock plus an AM/PM indicator, that hour determines
438 the hour of the day. If the string further contains a group specifying
439 the minute of the hour, that group combines with the hour. If the string
440 further contains a group specifying the second of the minute, that group
441 combines with the hour and minute.
443 If the string contains neither a \fB%s\fR format group nor
444 a group specifying the hour of the day, then midnight (\fB00:00\fR, the start
445 of the given date) is used.
446 The time zone is determined by either the \fB\-timezone\fR or \fB\-gmt\fR
447 options, or by using the current time zone.
449 If a format string lacks a \fB%z\fR or \fB%Z\fR format group,
450 it is possible for the time to be ambiguous because it appears twice
451 in the same day, once without and once with Daylight Saving Time.
452 If this situation occurs, the first occurrence of the time is chosen.
453 (For this reason, it is wise to have the input string contain the
454 time zone when converting local times. This caveat does not apply to
457 If the interpretation of the groups yields an impossible time because
458 a field is out of range, enough of that field's unit will be added to
459 or subtracted from the time to bring it in range. Thus, if attempting to
460 scan or format day 0 of the month, one day will be subtracted from day
461 1 of the month, yielding the last day of the previous month.
463 If the interpretation of the groups yields an impossible time because
464 a Daylight Saving Time change skips over that time, or an ambiguous
465 time because a Daylight Saving Time change skips back so that the clock
466 observes the given time twice, and no time zone specifier (\fB%z\fR
467 or \fB%Z\fR) is present in the format, the time is interpreted as
468 if the clock had not changed.
471 The following format groups are recognized by the \fBclock scan\fR and
472 \fBclock format\fR commands.
475 On output, produces an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day
476 of the week in the given locale. On input, matches the name of the day
477 of the week in the given locale (in either abbreviated or full form, or
478 any unique prefix of either form).
481 On output, produces the full name (\fIe.g.,\fR \fBMonday\fR) of the day
482 of the week in the given locale. On input, matches the name of the day
483 of the week in the given locale (in either abbreviated or full form, or
484 any unique prefix of either form).
487 On output, produces an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name
488 of the month in the given locale. On input, matches the name of the month
489 in the given locale (in either abbreviated or full form, or
490 any unique prefix of either form).
493 On output, produces the full name (\fIe.g.,\fR \fBJanuary\fR)
494 of the month in the given locale. On input, matches the name of the month
495 in the given locale (in either abbreviated or full form, or
496 any unique prefix of either form).
499 On output, produces a localized representation of date and time of day;
500 the localized representation is expected to use the Gregorian calendar.
501 On input, matches whatever \fB%c\fR produces.
504 On output, produces the number of the century in Indo-Arabic numerals.
505 On input, matches one or two digits, possibly with leading whitespace,
506 that are expected to be the number of the century.
509 On output, produces the number of the day of the month, as two decimal
510 digits. On input, matches one or two digits, possibly with leading
511 whitespace, that are expected to be the number of the day of the month.
514 This format group is synonymous with \fB%m/%d/%Y\fR. It should be
515 used only in exchanging data within the \fBen_US\fR locale, since
516 other locales typically do not use this order for the fields of the date.
519 On output, produces the number of the day of the month, as one or
520 two decimal digits (with a leading blank for one-digit dates).
521 On input, matches one or two digits, possibly with leading
522 whitespace, that are expected to be the number of the day of the month.
525 On output, produces a locale-dependent representation of the date and
526 time of day in the locale's alternative calendar. On input, matches
527 whatever \fB%Ec\fR produces. The locale's alternative calendar need not
528 be the Gregorian calendar.
531 On output, produces a locale-dependent name of an era in the locale's
532 alternative calendar. On input, matches the name of the era or any
536 On output, produces the string \fBB.C.E.\fR or \fBC.E.\fR, or a
537 string of the same meaning in the locale, to indicate whether \fB%Y\fR refers
538 to years before or after Year 1 of the Common Era. On input, accepts
539 the string \fBB.C.E.\fR, \fBB.C.\fR, \fBC.E.\fR, \fBA.D.\fR, or the
540 abbreviation appropriate to the current locale, and uses it to fix
541 whether \fB%Y\fR refers to years before or after Year 1 of the
545 On output, produces a locale-dependent representation of the date
546 in the locale's alternative calendar. On input, matches
547 whatever \fB%Ex\fR produces. The locale's alternative calendar need not
548 be the Gregorian calendar.
551 On output, produces a locale-dependent representation of the
552 time of day in the locale's alternative numerals. On input, matches
553 whatever \fB%EX\fR produces.
556 On output, produces a locale-dependent number of the year of the era
557 in the locale's alternative calendar and numerals. On input, matches
561 On output, produces a representation of the year in the locale's
562 alternative calendar and numerals. On input, matches what \fB%EY\fR
563 produces. Often synonymous with \fB%EC%Ey\fR.
566 On output, produces a two-digit year number suitable for use with
567 the week-based ISO8601 calendar; that is, the year number corresponds
568 to the week number produced by \fB%V\fR. On input, accepts such
569 a two-digit year number, possibly with leading whitespace.
572 On output, produces a four-digit year number suitable for use with
573 the week-based ISO8601 calendar; that is, the year number corresponds
574 to the week number produced by \fB%V\fR. On input, accepts such
575 a four-digit year number, possibly with leading whitespace.
578 This format group is synonymous with \fB%b\fR.
581 On output, produces a two-digit number giving the hour of the day
582 (00-23) on a 24-hour clock. On input, accepts such a number.
585 On output, produces a two-digit number giving the hour of the day
586 (12-11) on a 12-hour clock. On input, accepts such a number.
589 On output, produces a three-digit number giving the day of the year
590 (001-366). On input, accepts such a number.
593 On output, produces a string of digits giving the Julian Day Number.
594 On input, accepts a string of digits and interprets it as a Julian Day Number.
595 The Julian Day Number is a count of the number of calendar days
596 that have elapsed since 1 January, 4713 BCE of the proleptic
597 Julian calendar. The epoch time of 1 January 1970 corresponds
598 to Julian Day Number 2440588.
601 On output, produces a one- or two-digit number giving the hour of the day
602 (0-23) on a 24-hour clock. On input, accepts such a number.
605 On output, produces a one- or two-digit number giving the hour of the day
606 (12-11) on a 12-hour clock. On input, accepts such a number.
609 On output, produces the number of the month (01-12) with exactly two
610 digits. On input, accepts two digits and interprets them as the number
614 On output, produces the number of the minute of the hour (00-59)
615 with exactly two digits. On input, accepts two digits and interprets them
616 as the number of the minute of the hour.
619 On output, produces the number of the month (1-12) with one or two digits,
620 and a leading blank for one-digit dates.
621 On input, accepts one or two digits, possibly with leading whitespace,
622 and interprets them as the number of the month.
624 \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
625 All of these format groups are synonymous with their counterparts
628 except that the string is produced and parsed in the
629 locale-dependent alternative numerals.
632 On output, produces an indicator for the part of the day, \fBAM\fR
633 or \fBPM\fR, appropriate to the given locale. If the script of the
634 given locale supports multiple letterforms, lowercase is preferred.
635 On input, matches the representation \fBAM\fR or \fBPM\fR in
636 the given locale, in either case.
639 On output, produces an indicator for the part of the day, \fBam\fR
640 or \fBpm\fR, appropriate to the given locale. If the script of the
641 given locale supports multiple letterforms, uppercase is preferred.
642 On input, matches the representation \fBAM\fR or \fBPM\fR in
643 the given locale, in either case.
646 This format group is reserved for internal use within the Tcl library.
649 On output, produces a locale-dependent time of day representation on a
650 12-hour clock. On input, accepts whatever \fB%r\fR produces.
653 On output, the time in 24-hour notation (%H:%M). For a version
654 including the seconds, see \fB%T\fR below. On input, accepts whatever
658 On output, simply formats the \fItimeVal\fR argument as a decimal
659 integer and inserts it into the output string. On input, accepts
660 a decimal integer and uses is as the time value without any further
661 processing. Since \fB%s\fR uniquely determines a point in time, it
662 overrides all other input formats.
665 On output, produces a two-digit number of the second of the minute
666 (00-59). On input, accepts two digits and uses them as the second of the
670 On output, produces a TAB character. On input, matches a TAB character.
673 Synonymous with \fB%H:%M:%S\fR.
676 On output, produces the number of the day of the week
677 (\fB1\fR\(->Monday, \fB7\fR\(->Sunday). On input, accepts a single digit and
678 interprets it as the day of the week. Sunday may be either \fB0\fR or
682 On output, produces the ordinal number of the week of the year
683 (00-53). The first Sunday of the year is the first day of week 01. On
684 input accepts two digits which are otherwise ignored. This format
685 group is never used in determining an input date. This interpretation
686 of the week of the year was once common in US banking but is now
687 largely obsolete. See \fB%V\fR for the ISO8601 week number.
690 On output, produces the number of the ISO8601 week as a two digit
691 number (01-53). Week 01 is the week containing January 4; or the first
692 week of the year containing at least 4 days; or the week containing
693 the first Thursday of the year (the three statements are
694 equivalent). Each week begins on a Monday. On input, accepts the
698 On output, produces the ordinal number of the day of the week
699 (Sunday==0; Saturday==6). On input, accepts a single digit and
700 interprets it as the day of the week; Sunday may be represented as
701 either 0 or 7. Note that \fB%w\fR is not the ISO8601 weekday number,
702 which is produced and accepted by \fB%u\fR.
705 On output, produces a week number (00-53) within the year; week 01
706 begins on the first Monday of the year. On input, accepts two digits,
707 which are otherwise ignored. This format group is never used in
708 determining an input date. It is not the ISO8601 week number; that
709 week is produced and accepted by \fB%V\fR.
712 On output, produces the date in a locale-dependent representation. On
713 input, accepts whatever \fB%x\fR produces and is used to determine
717 On output, produces the time of day in a locale-dependent
718 representation. On input, accepts whatever \fB%X\fR produces and is used
719 to determine time of day.
722 On output, produces the two-digit year of the century. On input,
723 accepts two digits, and is used to determine calendar date. The
724 date is presumed to lie between 1938 and 2037 inclusive. Note
725 that \fB%y\fR does not yield a year appropriate for use with the ISO8601
726 week number \fB%V\fR; programs should use \fB%g\fR for that purpose.
729 On output, produces the four-digit calendar year. On input,
730 accepts four digits and may be used to determine calendar date. Note
731 that \fB%Y\fR does not yield a year appropriate for use with the ISO8601
732 week number \fB%V\fR; programs should use \fB%G\fR for that purpose.
735 On output, produces the current time zone, expressed in hours and
736 minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a
737 time zone specifier (see \fBTIME ZONES\fR below) that will be used to
738 determine the time zone.
741 On output, produces the current time zone's name, possibly
742 translated to the given locale. On input, accepts a time zone
743 specifier (see \fBTIME ZONES\fR below) that will be used to determine the
744 time zone. This option should, in general, be used on input only when
745 parsing RFC822 dates. Other uses are fraught with ambiguity; for
746 instance, the string \fBBST\fR may represent British Summer Time or
747 Brazilian Standard Time. It is recommended that date/time strings for
748 use by computers use numeric time zones instead.
751 On output, produces a literal
753 character. On input, matches a literal
759 .QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" .
762 When the \fBclock\fR command is processing a local time, it has several
763 possible sources for the time zone to use. In order of preference, they
766 A time zone specified inside a string being parsed and matched by a \fB%z\fR
767 or \fB%Z\fR format group.
769 A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR
770 command (or, equivalently, by \fB\-gmt\fR \fB1\fR).
772 A time zone specified in an environment variable \fBTCL_TZ\fR.
774 A time zone specified in an environment variable \fBTZ\fR.
776 The local time zone from the Control Panel on Windows systems.
778 The C library's idea of the local time zone, as defined by the
779 \fBmktime\fR and \fBlocaltime\fR functions.
781 In case [1] \fIonly,\fR the string is tested to see if it is one
785 gmt ut utc bst wet wat at
786 nft nst ndt ast adt est edt
787 cst cdt mst mdt pst pdt yst
788 ydt hst hdt cat ahst nt idlw
789 cet cest met mewt mest swt sst
790 eet eest bt it zp4 zp5 ist
791 zp6 wast wadt jt cct jst cast
792 cadt east eadt gst nzt nzst nzdt
796 If it is a string in the above list, it designates a known
797 time zone, and is interpreted as such.
799 For time zones in case [1] that do not match any of the above strings,
800 and always for cases [2]-[6], the following rules apply.
802 If the time zone begins with a colon, it is one of a
803 standardized list of names like \fB:America/New_York\fR
804 that give the rules for various locales. A complete list
805 of the location names is too lengthy to be listed here.
806 On most Tcl installations, the definitions of the locations
807 are to be found in named files in the directory
808 .QW "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR" .
809 On some Unix systems, these files are omitted, and the definitions are
810 instead obtained from system files in
811 .QW "\fI/usr/share/zoneinfo\fR" ,
812 .QW "\fI/usr/share/lib/zoneinfo\fR"
814 .QW "\fI/usr/local/etc/zoneinfo\fR" .
815 As a special case, the name \fB:localtime\fR refers to
816 the local time zone as defined by the C library.
818 A time zone string consisting of a plus or minus sign followed by
819 four or six decimal digits is interpreted as an offset in
820 hours, minutes, and seconds (if six digits are present) from
821 UTC. The plus sign denotes a sign east of Greenwich;
822 the minus sign one west of Greenwich.
824 A time zone string conforming to the Posix specification of the \fBTZ\fR
825 environment variable will be recognized. The specification
827 \fIhttps://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR.
829 If the Posix time zone string contains a DST (Daylight Savings Time)
830 part, but doesn't contain a rule stating when DST starts or ends,
831 then default rules are used. For Timezones with an offset between 0
832 and +12, the current European/Russian rules are used, otherwise the
833 current US rules are used. In Europe (offset +0 to +2) the switch
834 to summertime is done each last Sunday in March at 1:00 GMT, and
835 the switch back is each last Sunday in October at 2:00 GMT. In
836 Russia (offset +3 to +12), the switch dates are the same, only
837 the switch to summertime is at 2:00 local time, and the switch
838 back is at 3:00 local time in all time zones. The US switch to
839 summertime takes place each second Sunday in March at 2:00 local
840 time, and the switch back is each first Sunday in November at
841 3:00 local time. These default rules mean that in all European,
842 Russian and US (or compatible) time zones, DST calculations will
843 be correct for dates in 2007 and later, unless in the future the
846 Any other time zone string is processed by prefixing a colon and attempting
847 to use it as a location name, as above.
850 Developers wishing to localize the date and time formatting and parsing
851 are referred to \fIhttps://tip.tcl-lang.org/173\fR for a
855 If the \fBclock scan\fR command is invoked without a \fB\-format\fR
856 option, then it requests a \fIfree-form scan.\fR \fI
857 This form of scan is deprecated.\fR The reason for the deprecation
858 is that there are too many ambiguities. (Does the string
860 represent a year, a time of day, or a quantity?) No set of rules
861 for interpreting free-form dates and times has been found to
862 give unsurprising results in all cases.
864 If free-form scan is used, only the \fB\-base\fR and \fB\-gmt\fR
865 options are accepted. The \fB\-timezone\fR and \fB\-locale\fR
866 options will result in an error if \fB\-format\fR is not supplied.
868 For the benefit of users who need to understand legacy code that
869 uses free-form scan, the documentation for how free-form scan
870 interprets a string is included here:
873 specified, the current date is assumed. If the \fIinputString\fR
875 time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR
876 argument is true, in which case the clock value is calculated assuming
877 that the specified time is relative to Greenwich Mean Time.
878 \fB\-gmt\fR, if specified, affects only the computed time value; it does not
879 impact the interpretation of \fB\-base\fR.
881 If the \fB\-base\fR flag is specified, the next argument should contain
882 an integer clock value. Only the date in this value is used, not the
883 time. This is useful for determining the time on a specific day or
884 doing other date-relative conversions.
886 The \fIinputString\fR argument consists of zero or more specifications of the
890 A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR
891 or \fBhhmm ?meridian? ?zone?\fR
892 If no meridian is specified, \fBhh\fR is interpreted on
896 A specific month and day with optional year. The
897 acceptable formats are
898 .QW "\fBmm/dd\fR?\fB/yy\fR?" ,
899 .QW "\fBmonthname dd\fR?\fB, yy\fR?" ,
900 .QW "\fBday, dd monthname \fR?\fByy\fR?" ,
901 .QW "\fBdd monthname yy\fR" ,
902 .QW "?\fBCC\fR?\fByymmdd\fR" ,
904 .QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" .
905 The default year is the current year. If the year is less
906 than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
907 as 1969-1999. Not all platforms can represent the years 38-70, so
908 an error may result if these years are used.
910 \fIISO 8601 point-in-time\fR
911 An ISO 8601 point-in-time specification, such as
912 .QW \fICCyymmdd\fBT\fIhhmmss\fR,
913 where \fBT\fR is the literal
915 .QW "\fICCyymmdd hhmmss\fR" ,
916 .QW \fICCyymmdd\fBT\fIhh:mm:ss\fR ,
918 .QW \fICCyy-mm-dd\fBT\fIhh:mm:ss\fR.
919 Note that only these four formats are accepted.
920 The command does \fInot\fR accept the full range of point-in-time
921 specifications specified in ISO8601. Other formats can be recognized by
922 giving an explicit \fB\-format\fR option to the \fBclock scan\fR command.
925 A specification relative to the current time. The format is \fBnumber
926 unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR,
927 \fBmonth\fR, \fBweek\fR, \fBday\fR,
928 \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR). The
929 unit can be specified as a singular or plural, as in \fB3 weeks\fR.
930 These modifiers may also be specified:
931 \fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR,
932 \fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR.
934 The actual date is calculated according to the following steps.
936 First, any absolute date and/or time is processed and converted.
937 Using that time as the base, day-of-week specifications are added.
938 Next, relative specifications are used. If a date or day is
939 specified, and no absolute or relative time is given, midnight is
940 used. Finally, a correction is applied so that the correct hour of
941 the day is produced after allowing for daylight savings time
942 differences and the correct date is given when going from the end
943 of a long month to a short month.
949 Copyright \(co 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
OSDN Git Service
