1clock(n) Tcl Built-In Commands clock(n)
2______________________________________________________________________________
6
8 clock - Obtain and manipulate dates and times
9
11 package require Tcl 8.5
12 clock add timeVal ?count unit...? ?-option value?
14 clock clicks ?-option?
16 clock format timeVal ?-option value...?
18 clock microseconds
20 clock milliseconds
22 clock scan inputString ?-option value...?
24 clock seconds
26______________________________________________________________________________
28
30 The clock command performs several operations that obtain and manipu‐
31 late values that represent times. The command supports several subcom‐
32 mands that determine what action is carried out by the command.
33 clock add timeVal ?count unit...? ?-option value?
35 Adds a (possibly negative) offset to a time that is expressed as
36 an integer number of seconds. See CLOCK ARITHMETIC for a full
37 description.
38 clock clicks ?-option?
40 If no -option argument is supplied, returns a high-resolution
41 time value as a system-dependent integer value. The unit of the
42 value is system-dependent but should be the highest resolution
43 clock available on the system such as a CPU cycle counter. See
44 HIGH RESOLUTION TIMERS for a full description.
45 If the -option argument is -milliseconds, then the command is
47 synonymous with clock milliseconds (see below). This usage is
48 obsolete, and clock milliseconds is to be considered the pre‐
49 ferred way of obtaining a count of milliseconds.
50 If the -option argument is -microseconds, then the command is
52 synonymous with clock microseconds (see below). This usage is
53 obsolete, and clock microseconds is to be considered the pre‐
54 ferred way of obtaining a count of microseconds.
55 clock format timeVal ?-option value...?
57 Formats a time that is expressed as an integer number of seconds
58 into a format intended for consumption by users or external pro‐
59 grams. See FORMATTING TIMES for a full description.
60 clock microseconds
62 Returns the current time as an integer number of microseconds.
63 See HIGH RESOLUTION TIMERS for a full description.
64 clock milliseconds
66 Returns the current time as an integer number of milliseconds.
67 See HIGH RESOLUTION TIMERS for a full description.
68 clock scan inputString ?-option value...?
70 Scans a time that is expressed as a character string and pro‐
71 duces an integer number of seconds. See SCANNING TIMES for a
72 full description.
73 clock seconds
75 Returns the current time as an integer number of seconds.
76 PARAMETERS
78 count An integer representing a count of some unit of time. See CLOCK
79 ARITHMETIC for the details.
80 timeVal
82 An integer value passed to the clock command that represents an
83 absolute time as a number of seconds from the epoch time of 1
84 January 1970, 00:00 UTC. Note that the count of seconds does
85 not include any leap seconds; seconds are counted as if each UTC
86 day has exactly 86400 seconds. Tcl responds to leap seconds by
87 speeding or slowing its clock by a tiny fraction for some min‐
88 utes until it is back in sync with UTC; its data model does not
89 represent minutes that have 59 or 61 seconds.
90 unit One of the words, seconds, minutes, hours, days, weeks, months,
92 or years, or any unique prefix of such a word. Used in conjunc‐
93 tion with count to identify an interval of time, for example, 3
94 seconds or 1 year.
95 OPTIONS
97 -base time
98 Specifies that any relative times present in a clock scan com‐
99 mand are to be given relative to time. time must be expressed
100 as a count of nominal seconds from the epoch time of 1 January
101 1970, 00:00 UTC.
102 -format format
104 Specifies the desired output format for clock format or the ex‐
105 pected input format for clock scan. The format string consists
106 of any number of characters other than the per-cent sign (“%”)
107 interspersed with any number of format groups, which are two-
108 character sequences beginning with the per-cent sign. The per‐
109 missible format groups, and their interpretation, are described
110 under FORMAT GROUPS.
111 On clock format, the default format is
113 %a %b %d %H:%M:%S %Z %Y
115 On clock scan, the lack of a -format option indicates that a
117 “free format scan” is requested; see FREE FORM SCAN for a de‐
118 scription of what happens.
119 -gmt boolean
121 If boolean is true, specifies that a time specified to clock
122 add, clock format or clock scan should be processed in UTC. If
123 boolean is false, the processing defaults to the local time
124 zone. This usage is obsolete; the correct current usage is to
125 specify the UTC time zone with “-timezone :UTC” or any of the
126 equivalent ways to specify it.
127 -locale localeName
129 Specifies that locale-dependent scanning and formatting (and
130 date arithmetic for dates preceding the adoption of the Grego‐
131 rian calendar) is to be done in the locale identified by locale‐
132 Name. The locale name may be any of the locales acceptable to
133 the msgcat package, or it may be the special name system, which
134 represents the current locale of the process, or the null
135 string, which represents Tcl's default locale.
136 The effect of locale on scanning and formatting is discussed in
138 the descriptions of the individual format groups under FORMAT
139 GROUPS. The effect of locale on clock arithmetic is discussed
140 under CLOCK ARITHMETIC.
141 -timezone zoneName
143 Specifies that clock arithmetic, formatting, and scanning are to
144 be done according to the rules for the time zone specified by
145 zoneName. The permissible values, and their interpretation, are
146 discussed under TIME ZONES. On subcommands that expect a -time‐
147 zone argument, the default is to use the current time zone. The
148 current time zone is determined, in order of preference, by:
149 [1] the environment variable TCL_TZ.
151 [2] the environment variable TZ.
153 [3] on Windows systems, the time zone settings from the Con‐
155 trol Panel.
156 If none of these is present, the C localtime and mktime functions are
158 used to attempt to convert times between local and Greenwich. On
159 32-bit systems, this approach is likely to have bugs, particularly for
160 times that lie outside the window (approximately the years 1902 to
161 2037) that can be represented in a 32-bit integer.
162
164 The clock add command performs clock arithmetic on a value (expressed
165 as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC)
166 given as its first argument. The remaining arguments (other than the
167 possible -timezone, -locale and -gmt options) are integers and keywords
168 in alternation, where the keywords are chosen from seconds, minutes,
169 hours, days, weeks, months, or years, or any unique prefix of such a
170 word.
171 Addition of seconds, minutes and hours is fairly straightforward; the
173 given time increment (times sixty for minutes, or 3600 for hours) is
174 simply added to the timeVal given to the clock add command. The result
175 is interpreted as a nominal number of seconds from the Epoch.
176 Surprising results may be obtained when crossing a point at which a
178 leap second is inserted or removed; the clock add command simply ig‐
179 nores leap seconds and therefore assumes that times come in sequence,
180 23:59:58, 23:59:59, 00:00:00. (This assumption is handled by the fact
181 that Tcl's model of time reacts to leap seconds by speeding or slowing
182 the clock by a minuscule amount until Tcl's time is back in step with
183 the world.
184 The fact that adding and subtracting hours is defined in terms of abso‐
186 lute time means that it will add fixed amounts of time in time zones
187 that observe summer time (Daylight Saving Time). For example, the fol‐
188 lowing code sets the value of x to 04:00:00 because the clock has
189 changed in the interval in question.
190 set s [clock scan {2004-10-30 05:00:00} \
192 -format {%Y-%m-%d %H:%M:%S} \
193 -timezone :America/New_York]
194 set a [clock add $s 24 hours -timezone :America/New_York]
195 set x [clock format $a \
196 -format {%H:%M:%S} -timezone :America/New_York]
197 Adding and subtracting days and weeks is accomplished by converting the
199 given time to a calendar day and time of day in the appropriate time
200 zone and locale. The requisite number of days (weeks are converted to
201 days by multiplying by seven) is added to the calendar day, and the
202 date and time are then converted back to a count of seconds from the
203 epoch time.
204 Adding and subtracting a given number of days across the point that the
206 time changes at the start or end of summer time (Daylight Saving Time)
207 results in the same local time on the day in question. For instance,
208 the following code sets the value of x to 05:00:00.
209 set s [clock scan {2004-10-30 05:00:00} \
211 -format {%Y-%m-%d %H:%M:%S} \
212 -timezone :America/New_York]
213 set a [clock add $s 1 day -timezone :America/New_York]
214 set x [clock format $a \
215 -format {%H:%M:%S} -timezone :America/New_York]
216 In cases of ambiguity, where the same local time happens twice on the
218 same day, the earlier time is used. In cases where the conversion
219 yields an impossible time (for instance, 02:30 during the Spring Day‐
220 light Saving Time change using US rules), the time is converted as if
221 the clock had not changed. Thus, the following code will set the value
222 of x to 03:30:00.
223 set s [clock scan {2004-04-03 02:30:00} \
225 -format {%Y-%m-%d %H:%M:%S} \
226 -timezone :America/New_York]
227 set a [clock add $s 1 day -timezone :America/New_York]
228 set x [clock format $a \
229 -format {%H:%M:%S} -timezone :America/New_York]
230 Adding a given number of days or weeks works correctly across the con‐
232 version between the Julian and Gregorian calendars; the omitted days
233 are skipped. The following code sets z to 1752-09-14.
234 set x [clock scan 1752-09-02 -format %Y-%m-%d -locale en_US]
236 set y [clock add $x 1 day -locale en_US]
237 set z [clock format $y -format %Y-%m-%d -locale en_US]
238 In the bizarre case that adding the given number of days yields a date
240 that does not exist because it falls within the dropped days of the Ju‐
241 lian-to-Gregorian conversion, the date is converted as if it was on the
242 Julian calendar.
243 Adding a number of months, or a number of years, is similar; it con‐
245 verts the given time to a calendar date and time of day. It then adds
246 the requisite number of months or years, and reconverts the resulting
247 date and time of day to an absolute time.
248 If the resulting date is impossible because the month has too few days
250 (for example, when adding 1 month to 31 January), the last day of the
251 month is substituted. Thus, adding 1 month to 31 January will result
252 in 28 February in a common year or 29 February in a leap year.
253 The rules for handling anomalies relating to summer time and to the
255 Gregorian calendar are the same when adding/subtracting months and
256 years as they are when adding/subtracting days and weeks.
257 If multiple count unit pairs are present on the command, they are eval‐
259 uated consecutively, from left to right.
260
262 Most of the subcommands supported by the clock command deal with times
263 represented as a count of seconds from the epoch time, and this is the
264 representation that clock seconds returns. There are three exceptions,
265 which are all intended for use where higher-resolution times are re‐
266 quired. clock milliseconds returns the count of milliseconds from the
267 epoch time, and clock microseconds returns the count of microseconds
268 from the epoch time. In addition, there is a clock clicks command that
269 returns a platform-dependent high-resolution timer. Unlike clock sec‐
270 onds and clock milliseconds, the value of clock clicks is not guaran‐
271 teed to be tied to any fixed epoch; it is simply intended to be the
272 most precise interval timer available, and is intended only for rela‐
273 tive timing studies such as benchmarks.
274
276 The clock format command produces times for display to a user or writ‐
277 ing to an external medium. The command accepts times that are ex‐
278 pressed in seconds from the epoch time of 1 January 1970, 00:00 UTC, as
279 returned by clock seconds, clock scan, clock add, file atime or file
280 mtime.
281 If a -format option is present, the following argument is a string that
283 specifies how the date and time are to be formatted. The string con‐
284 sists of any number of characters other than the per-cent sign (“%”)
285 interspersed with any number of format groups, which are two-character
286 sequences beginning with the per-cent sign. The permissible format
287 groups, and their interpretation, are described under FORMAT GROUPS.
288 If a -timezone option is present, the following argument is a string
290 that specifies the time zone in which the date and time are to be for‐
291 matted. As an alternative to “-timezone :UTC”, the obsolete usage
292 “-gmt true” may be used. See TIME ZONES for the permissible variants
293 for the time zone.
294 If a -locale option is present, the following argument is a string that
296 specifies the locale in which the time is to be formatted, in the same
297 format that is used for the msgcat package. Note that the default, if
298 -locale is not specified, is the root locale {} rather than the current
299 locale. The current locale may be obtained by using -locale current.
300 In addition, some platforms support a system locale that reflects the
301 user's current choices. For instance, on Windows, the format that the
302 user has selected from dates and times in the Control Panel can be ob‐
303 tained by using the system locale. On platforms that do not define a
304 user selection of date and time formats separate from LC_TIME, -locale
305 system is synonymous with -locale current.
306
308 The clock scan command accepts times that are formatted as strings and
309 converts them to counts of seconds from the epoch time of 1 January
310 1970, 00:00 UTC. It normally takes a -format option that is followed
311 by a string describing the expected format of the input. (See FREE
312 FORM SCAN for the effect of clock scan without such an argument.) The
313 string consists of any number of characters other than the per-cent
314 sign (“%”), interspersed with any number of format groups, which are
315 two-character sequences beginning with the per-cent sign. The permis‐
316 sible format groups, and their interpretation, are described under FOR‐
317 MAT GROUPS.
318 If a -timezone option is present, the following argument is a string
320 that specifies the time zone in which the date and time are to be in‐
321 terpreted. As an alternative to -timezone :UTC, the obsolete usage
322 -gmt true may be used. See TIME ZONES for the permissible variants for
323 the time zone.
324 If a -locale option is present, the following argument is a string that
326 specifies the locale in which the time is to be interpreted, in the
327 same format that is used for the msgcat package. Note that the de‐
328 fault, if -locale is not specified, is the root locale {} rather than
329 the current locale. The current locale may be obtained by using -lo‐
330 cale current. In addition, some platforms support a system locale that
331 reflects the user's current choices. For instance, on Windows, the
332 format that the user has selected from dates and times in the Control
333 Panel can be obtained by using the system locale. On platforms that do
334 not define a user selection of date and time formats separate from
335 LC_TIME, -locale system is synonymous with -locale current.
336 If a -base option is present, the following argument is a time (ex‐
338 pressed in seconds from the epoch time) that is used as a base time for
339 interpreting relative times. If no -base option is present, the base
340 time is the current time.
341 Scanning of times in fixed format works by determining three things:
343 the date, the time of day, and the time zone. These three are then
344 combined into a point in time, which is returned as the number of sec‐
345 onds from the epoch.
346 Before scanning begins, the format string is preprocessed to replace
348 %c, %Ec, %x, %Ex, %X. %Ex, %r, %R, %T, %D, %EY and %+ format groups
349 with counterparts that are appropriate to the current locale and con‐
350 tain none of the above groups. For instance, %D will (in the en_US lo‐
351 cale) be replaced with %m/%d/%Y.
352 The date is determined according to the fields that are present in the
354 preprocessed format string. In order of preference:
355 [1] If the string contains a %s format group, representing seconds
357 from the epoch, that group is used to determine the date.
358 [2] If the string contains a %J format group, representing the Ju‐
360 lian Day Number, that group is used to determine the date.
361 [3] If the string contains a complete set of format groups specify‐
363 ing century, year, month, and day of month; century, year, and
364 day of year; or ISO8601 fiscal year, week of year, and day of
365 week; those groups are combined and used to determine the date.
366 If more than one complete set is present, the one at the right‐
367 most position in the string is used.
368 [4] If the string lacks a century but contains a set of format
370 groups specifying year of century, month and day of month; year
371 of century and day of year; or two-digit ISO8601 fiscal year,
372 week of year, and day of week; those groups are combined and
373 used to determine the date. If more than one complete set is
374 present, the one at the rightmost position in the string is
375 used. The year is presumed to lie in the range 1938 to 2037 in‐
376 clusive.
377 [5] If the string entirely lacks any specification for the year (or
379 contains the year only on the locale's alternative calendar) and
380 contains a set of format groups specifying month and day of
381 month, day of year, or week of year and day of week, those
382 groups are combined and used to determine the date. If more
383 than one complete set is present, the one at the rightmost posi‐
384 tion in the string is used. The year is determined by inter‐
385 preting the base time in the given time zone.
386 [6] If the string contains none of the above sets, but has a day of
388 the month or day of the week, the day of the month or day of the
389 week are used to determine the date by interpreting the base
390 time in the given time zone and returning the given day of the
391 current week or month. (The week runs from Monday to Sunday,
392 ISO8601-fashion.) If both day of month and day of week are
393 present, the day of the month takes priority.
394 [7] If none of the above rules results in a usable date, the date of
396 the base time in the given time zone is used.
397 The time is also determined according to the fields that are present in
399 the preprocessed format string. In order of preference:
400 [1] If the string contains a %s format group, representing seconds
402 from the epoch, that group determines the time of day.
403 [2] If the string contains either an hour on the 24-hour clock or an
405 hour on the 12-hour clock plus an AM/PM indicator, that hour de‐
406 termines the hour of the day. If the string further contains a
407 group specifying the minute of the hour, that group combines
408 with the hour. If the string further contains a group specify‐
409 ing the second of the minute, that group combines with the hour
410 and minute.
411 [3] If the string contains neither a %s format group nor a group
413 specifying the hour of the day, then midnight (00:00, the start
414 of the given date) is used. The time zone is determined by ei‐
415 ther the -timezone or -gmt options, or by using the current time
416 zone.
417 If a format string lacks a %z or %Z format group, it is possible for
419 the time to be ambiguous because it appears twice in the same day, once
420 without and once with Daylight Saving Time. If this situation occurs,
421 the first occurrence of the time is chosen. (For this reason, it is
422 wise to have the input string contain the time zone when converting lo‐
423 cal times. This caveat does not apply to UTC times.)
424 If the interpretation of the groups yields an impossible time because a
426 field is out of range, enough of that field's unit will be added to or
427 subtracted from the time to bring it in range. Thus, if attempting to
428 scan or format day 0 of the month, one day will be subtracted from day
429 1 of the month, yielding the last day of the previous month.
430 If the interpretation of the groups yields an impossible time because a
432 Daylight Saving Time change skips over that time, or an ambiguous time
433 because a Daylight Saving Time change skips back so that the clock ob‐
434 serves the given time twice, and no time zone specifier (%z or %Z) is
435 present in the format, the time is interpreted as if the clock had not
436 changed.
437
439 The following format groups are recognized by the clock scan and clock
440 format commands.
441 %a On output, produces an abbreviation (e.g., Mon) for the day of
443 the week in the given locale. On input, matches the name of the
444 day of the week in the given locale (in either abbreviated or
445 full form, or any unique prefix of either form).
446 %A On output, produces the full name (e.g., Monday) of the day of
448 the week in the given locale. On input, matches the name of the
449 day of the week in the given locale (in either abbreviated or
450 full form, or any unique prefix of either form).
451 %b On output, produces an abbreviation (e.g., Jan) for the name of
453 the month in the given locale. On input, matches the name of
454 the month in the given locale (in either abbreviated or full
455 form, or any unique prefix of either form).
456 %B On output, produces the full name (e.g., January) of the month
458 in the given locale. On input, matches the name of the month in
459 the given locale (in either abbreviated or full form, or any
460 unique prefix of either form).
461 %c On output, produces a localized representation of date and time
463 of day; the localized representation is expected to use the Gre‐
464 gorian calendar. On input, matches whatever %c produces.
465 %C On output, produces the number of the century in Indo-Arabic nu‐
467 merals. On input, matches one or two digits, possibly with
468 leading whitespace, that are expected to be the number of the
469 century.
470 %d On output, produces the number of the day of the month, as two
472 decimal digits. On input, matches one or two digits, possibly
473 with leading whitespace, that are expected to be the number of
474 the day of the month.
475 %D This format group is synonymous with %m/%d/%Y. It should be
477 used only in exchanging data within the en_US locale, since
478 other locales typically do not use this order for the fields of
479 the date.
480 %e On output, produces the number of the day of the month, as one
482 or two decimal digits (with a leading blank for one-digit
483 dates). On input, matches one or two digits, possibly with
484 leading whitespace, that are expected to be the number of the
485 day of the month.
486 %Ec On output, produces a locale-dependent representation of the
488 date and time of day in the locale's alternative calendar. On
489 input, matches whatever %Ec produces. The locale's alternative
490 calendar need not be the Gregorian calendar.
491 %EC On output, produces a locale-dependent name of an era in the lo‐
493 cale's alternative calendar. On input, matches the name of the
494 era or any unique prefix.
495 %EE On output, produces the string B.C.E. or C.E., or a string of
497 the same meaning in the locale, to indicate whether %Y refers to
498 years before or after Year 1 of the Common Era. On input, ac‐
499 cepts the string B.C.E., B.C., C.E., A.D., or the abbreviation
500 appropriate to the current locale, and uses it to fix whether %Y
501 refers to years before or after Year 1 of the Common Era.
502 %Ex On output, produces a locale-dependent representation of the
504 date in the locale's alternative calendar. On input, matches
505 whatever %Ex produces. The locale's alternative calendar need
506 not be the Gregorian calendar.
507 %EX On output, produces a locale-dependent representation of the
509 time of day in the locale's alternative numerals. On input,
510 matches whatever %EX produces.
511 %Ey On output, produces a locale-dependent number of the year of the
513 era in the locale's alternative calendar and numerals. On in‐
514 put, matches such a number.
515 %EY On output, produces a representation of the year in the locale's
517 alternative calendar and numerals. On input, matches what %EY
518 produces. Often synonymous with %EC%Ey.
519 %g On output, produces a two-digit year number suitable for use
521 with the week-based ISO8601 calendar; that is, the year number
522 corresponds to the week number produced by %V. On input, ac‐
523 cepts such a two-digit year number, possibly with leading white‐
524 space.
525 %G On output, produces a four-digit year number suitable for use
527 with the week-based ISO8601 calendar; that is, the year number
528 corresponds to the week number produced by %V. On input, ac‐
529 cepts such a four-digit year number, possibly with leading
530 whitespace.
531 %h This format group is synonymous with %b.
533 %H On output, produces a two-digit number giving the hour of the
535 day (00-23) on a 24-hour clock. On input, accepts such a num‐
536 ber.
537 %I On output, produces a two-digit number giving the hour of the
539 day (12-11) on a 12-hour clock. On input, accepts such a num‐
540 ber.
541 %j On output, produces a three-digit number giving the day of the
543 year (001-366). On input, accepts such a number.
544 %J On output, produces a string of digits giving the Julian Day
546 Number. On input, accepts a string of digits and interprets it
547 as a Julian Day Number. The Julian Day Number is a count of the
548 number of calendar days that have elapsed since 1 January, 4713
549 BCE of the proleptic Julian calendar. The epoch time of 1 Janu‐
550 ary 1970 corresponds to Julian Day Number 2440588.
551 %k On output, produces a one- or two-digit number giving the hour
553 of the day (0-23) on a 24-hour clock. On input, accepts such a
554 number.
555 %l On output, produces a one- or two-digit number giving the hour
557 of the day (12-11) on a 12-hour clock. On input, accepts such a
558 number.
559 %m On output, produces the number of the month (01-12) with exactly
561 two digits. On input, accepts two digits and interprets them as
562 the number of the month.
563 %M On output, produces the number of the minute of the hour (00-59)
565 with exactly two digits. On input, accepts two digits and in‐
566 terprets them as the number of the minute of the hour.
567 %N On output, produces the number of the month (1-12) with one or
569 two digits, and a leading blank for one-digit dates. On input,
570 accepts one or two digits, possibly with leading whitespace, and
571 interprets them as the number of the month.
572 %Od, %Oe, %OH, %OI, %Ok, %Ol, %Om, %OM, %OS, %Ou, %Ow, %Oy
574 All of these format groups are synonymous with their counter‐
575 parts without the “O”, except that the string is produced and
576 parsed in the locale-dependent alternative numerals.
577 %p On output, produces an indicator for the part of the day, AM or
579 PM, appropriate to the given locale. If the script of the given
580 locale supports multiple letterforms, lowercase is preferred.
581 On input, matches the representation AM or PM in the given lo‐
582 cale, in either case.
583 %P On output, produces an indicator for the part of the day, am or
585 pm, appropriate to the given locale. If the script of the given
586 locale supports multiple letterforms, uppercase is preferred.
587 On input, matches the representation AM or PM in the given lo‐
588 cale, in either case.
589 %Q This format group is reserved for internal use within the Tcl
591 library.
592 %r On output, produces a locale-dependent time of day representa‐
594 tion on a 12-hour clock. On input, accepts whatever %r produces.
595 %R On output, the time in 24-hour notation (%H:%M). For a version
597 including the seconds, see %T below. On input, accepts whatever
598 %R produces.
599 %s On output, simply formats the timeVal argument as a decimal in‐
601 teger and inserts it into the output string. On input, accepts
602 a decimal integer and uses is as the time value without any fur‐
603 ther processing. Since %s uniquely determines a point in time,
604 it overrides all other input formats.
605 %S On output, produces a two-digit number of the second of the
607 minute (00-59). On input, accepts two digits and uses them as
608 the second of the minute.
609 %t On output, produces a TAB character. On input, matches a TAB
611 character.
612 %T Synonymous with %H:%M:%S.
614 %u On output, produces the number of the day of the week (1→Monday,
616 7→Sunday). On input, accepts a single digit and interprets it as
617 the day of the week. Sunday may be either 0 or 7.
618 %U On output, produces the ordinal number of the week of the year
620 (00-53). The first Sunday of the year is the first day of week
621 01. On input accepts two digits which are otherwise ignored.
622 This format group is never used in determining an input date.
623 This interpretation of the week of the year was once common in
624 US banking but is now largely obsolete. See %V for the ISO8601
625 week number.
626 %V On output, produces the number of the ISO8601 week as a two
628 digit number (01-53). Week 01 is the week containing January 4;
629 or the first week of the year containing at least 4 days; or the
630 week containing the first Thursday of the year (the three state‐
631 ments are equivalent). Each week begins on a Monday. On input,
632 accepts the ISO8601 week number.
633 %w On output, produces the ordinal number of the day of the week
635 (Sunday==0; Saturday==6). On input, accepts a single digit and
636 interprets it as the day of the week; Sunday may be represented
637 as either 0 or 7. Note that %w is not the ISO8601 weekday num‐
638 ber, which is produced and accepted by %u.
639 %W On output, produces a week number (00-53) within the year; week
641 01 begins on the first Monday of the year. On input, accepts two
642 digits, which are otherwise ignored. This format group is never
643 used in determining an input date. It is not the ISO8601 week
644 number; that week is produced and accepted by %V.
645 %x On output, produces the date in a locale-dependent representa‐
647 tion. On input, accepts whatever %x produces and is used to de‐
648 termine calendar date.
649 %X On output, produces the time of day in a locale-dependent repre‐
651 sentation. On input, accepts whatever %X produces and is used to
652 determine time of day.
653 %y On output, produces the two-digit year of the century. On input,
655 accepts two digits, and is used to determine calendar date. The
656 date is presumed to lie between 1938 and 2037 inclusive. Note
657 that %y does not yield a year appropriate for use with the
658 ISO8601 week number %V; programs should use %g for that purpose.
659 %Y On output, produces the four-digit calendar year. On input, ac‐
661 cepts four digits and may be used to determine calendar date.
662 Note that %Y does not yield a year appropriate for use with the
663 ISO8601 week number %V; programs should use %G for that purpose.
664 %z On output, produces the current time zone, expressed in hours
666 and minutes east (+hhmm) or west (-hhmm) of Greenwich. On input,
667 accepts a time zone specifier (see TIME ZONES below) that will
668 be used to determine the time zone.
669 %Z On output, produces the current time zone's name, possibly
671 translated to the given locale. On input, accepts a time zone
672 specifier (see TIME ZONES below) that will be used to determine
673 the time zone. This option should, in general, be used on input
674 only when parsing RFC822 dates. Other uses are fraught with am‐
675 biguity; for instance, the string BST may represent British Sum‐
676 mer Time or Brazilian Standard Time. It is recommended that
677 date/time strings for use by computers use numeric time zones
678 instead.
679 %% On output, produces a literal “%” character. On input, matches a
681 literal “%” character.
682 %+ Synonymous with “%a %b %e %H:%M:%S %Z %Y”.
684
686 When the clock command is processing a local time, it has several pos‐
687 sible sources for the time zone to use. In order of preference, they
688 are:
689 [1] A time zone specified inside a string being parsed and matched
691 by a %z or %Z format group.
692 [2] A time zone specified with the -timezone option to the clock
694 command (or, equivalently, by -gmt 1).
695 [3] A time zone specified in an environment variable TCL_TZ.
697 [4] A time zone specified in an environment variable TZ.
699 [5] The local time zone from the Control Panel on Windows systems.
701 [6] The C library's idea of the local time zone, as defined by the
703 mktime and localtime functions.
704 In case [1] only, the string is tested to see if it is one of the
706 strings:
707 gmt ut utc bst wet wat at
709 nft nst ndt ast adt est edt
710 cst cdt mst mdt pst pdt yst
711 ydt hst hdt cat ahst nt idlw
712 cet cest met mewt mest swt sst
713 eet eest bt it zp4 zp5 ist
714 zp6 wast wadt jt cct jst cast
715 cadt east eadt gst nzt nzst nzdt
716 idle
717 If it is a string in the above list, it designates a known time zone,
719 and is interpreted as such.
720 For time zones in case [1] that do not match any of the above strings,
722 and always for cases [2]-[6], the following rules apply.
723 If the time zone begins with a colon, it is one of a standardized list
725 of names like :America/New_York that give the rules for various lo‐
726 cales. A complete list of the location names is too lengthy to be
727 listed here. On most Tcl installations, the definitions of the loca‐
728 tions are to be found in named files in the directory
729 “/no_backup/tools/lib/tcl8.5/clock/tzdata”. On some Unix systems,
730 these files are omitted, and the definitions are instead obtained from
731 system files in “/usr/share/zoneinfo”, “/usr/share/lib/zoneinfo” or
732 “/usr/local/etc/zoneinfo”. As a special case, the name :localtime
733 refers to the local time zone as defined by the C library.
734 A time zone string consisting of a plus or minus sign followed by four
736 or six decimal digits is interpreted as an offset in hours, minutes,
737 and seconds (if six digits are present) from UTC. The plus sign de‐
738 notes a sign east of Greenwich; the minus sign one west of Greenwich.
739 A time zone string conforming to the Posix specification of the TZ en‐
741 vironment variable will be recognized. The specification may be found
742 at https://pubs.opengroup.org/on‐
743 linepubs/009695399/basedefs/xbd_chap08.html.
744 If the Posix time zone string contains a DST (Daylight Savings Time)
746 part, but doesn't contain a rule stating when DST starts or ends, then
747 default rules are used. For Timezones with an offset between 0 and +12,
748 the current European/Russian rules are used, otherwise the current US
749 rules are used. In Europe (offset +0 to +2) the switch to summertime is
750 done each last Sunday in March at 1:00 GMT, and the switch back is each
751 last Sunday in October at 2:00 GMT. In Russia (offset +3 to +12), the
752 switch dates are the same, only the switch to summertime is at 2:00 lo‐
753 cal time, and the switch back is at 3:00 local time in all time zones.
754 The US switch to summertime takes place each second Sunday in March at
755 2:00 local time, and the switch back is each first Sunday in November
756 at 3:00 local time. These default rules mean that in all European, Rus‐
757 sian and US (or compatible) time zones, DST calculations will be cor‐
758 rect for dates in 2007 and later, unless in the future the rules change
759 again.
760 Any other time zone string is processed by prefixing a colon and at‐
762 tempting to use it as a location name, as above.
763
765 Developers wishing to localize the date and time formatting and parsing
766 are referred to https://tip.tcl-lang.org/173 for a specification.
767
769 If the clock scan command is invoked without a -format option, then it
770 requests a free-form scan. This form of scan is deprecated. The rea‐
771 son for the deprecation is that there are too many ambiguities. (Does
772 the string “2000” represent a year, a time of day, or a quantity?) No
773 set of rules for interpreting free-form dates and times has been found
774 to give unsurprising results in all cases.
775 If free-form scan is used, only the -base and -gmt options are ac‐
777 cepted. The -timezone and -locale options will result in an error if
778 -format is not supplied.
779 For the benefit of users who need to understand legacy code that uses
781 free-form scan, the documentation for how free-form scan interprets a
782 string is included here:
783 If only a time is specified, the current date is assumed. If the in‐
785 putString does not contain a time zone mnemonic, the local time zone is
786 assumed, unless the -gmt argument is true, in which case the clock
787 value is calculated assuming that the specified time is relative to
788 Greenwich Mean Time. -gmt, if specified, affects only the computed
789 time value; it does not impact the interpretation of -base.
790 If the -base flag is specified, the next argument should contain an in‐
792 teger clock value. Only the date in this value is used, not the time.
793 This is useful for determining the time on a specific day or doing
794 other date-relative conversions.
795 The inputString argument consists of zero or more specifications of the
797 following form:
798 time A time of day, which is of the form: hh?:mm?:ss?? ?meridian?
800 ?zone? or hhmm ?meridian? ?zone? If no meridian is specified,
801 hh is interpreted on a 24-hour clock.
802 date A specific month and day with optional year. The acceptable
804 formats are “mm/dd?/yy?”, “monthname dd?, yy?”, “day, dd month‐
805 name ?yy?”, “dd monthname yy”, “?CC?yymmdd”, and “dd-month‐
806 name-?CC?yy”. The default year is the current year. If the
807 year is less than 100, we treat the years 00-68 as 2000-2068 and
808 the years 69-99 as 1969-1999. Not all platforms can represent
809 the years 38-70, so an error may result if these years are used.
810 ISO 8601 point-in-time
812 An ISO 8601 point-in-time specification, such as “CCyymmddThh‐
813 mmss,” where T is the literal “T”, “CCyymmdd hhmmss”, “CCyymmd‐
814 dThh:mm:ss”, or “CCyy-mm-ddThh:mm:ss.” Note that only these
815 four formats are accepted. The command does not accept the full
816 range of point-in-time specifications specified in ISO8601.
817 Other formats can be recognized by giving an explicit -format
818 option to the clock scan command.
819 relative time
821 A specification relative to the current time. The format is
822 number unit. Acceptable units are year, fortnight, month, week,
823 day, hour, minute (or min), and second (or sec). The unit can
824 be specified as a singular or plural, as in 3 weeks. These mod‐
825 ifiers may also be specified: tomorrow, yesterday, today, now,
826 last, this, next, ago.
827 The actual date is calculated according to the following steps.
829 First, any absolute date and/or time is processed and converted. Using
831 that time as the base, day-of-week specifications are added. Next,
832 relative specifications are used. If a date or day is specified, and
833 no absolute or relative time is given, midnight is used. Finally, a
834 correction is applied so that the correct hour of the day is produced
835 after allowing for daylight savings time differences and the correct
836 date is given when going from the end of a long month to a short month.
837
839 msgcat(n)
840
842 clock, date, time
843
845 Copyright © 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
846Tcl 8.5 clock(n)