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
105 expected input format for clock scan. The format string con‐
106 sists of any number of characters other than the per-cent sign
107 (“%”) interspersed with any number of format groups, which are
108 two-character sequences beginning with the per-cent sign. The
109 permissible format groups, and their interpretation, are
110 described under FORMAT GROUPS.
111 On clock format, the default format is
113 %a %b %d %H:%M:%S %z %Y
114 On clock scan, the lack of a -format option indicates that a
116 “free format scan” is requested; see FREE FORM SCAN for a
117 description of what happens.
118 -gmt boolean
120 If boolean is true, specifies that a time specified to clock
121 add, clock format or clock scan should be processed in UTC. If
122 boolean is false, the processing defaults to the local time
123 zone. This usage is obsolete; the correct current usage is to
124 specify the UTC time zone with “-timezone :UTC” or any of the
125 equivalent ways to specify it.
126 -locale localeName
128 Specifies that locale-dependent scanning and formatting (and
129 date arithmetic for dates preceding the adoption of the Grego‐
130 rian calendar) is to be done in the locale identified by locale‐
131 Name. The locale name may be any of the locales acceptable to
132 the msgcat package, or it may be the special name system, which
133 represents the current locale of the process, or the null
134 string, which represents Tcl's default locale.
135 The effect of locale on scanning and formatting is discussed in
137 the descriptions of the individual format groups under FORMAT
138 GROUPS. The effect of locale on clock arithmetic is discussed
139 under CLOCK ARITHMETIC.
140 -timezone zoneName
142 Specifies that clock arithmetic, formatting, and scanning are to
143 be done according to the rules for the time zone specified by
144 zoneName. The permissible values, and their interpretation, are
145 discussed under TIME ZONES. On subcommands that expect a -time‐
146 zone argument, the default is to use the current time zone. The
147 current time zone is determined, in order of preference, by:
148 [1] the environment variable TCL_TZ.
150 [2] the environment variable TZ.
152 [3] on Windows systems, the time zone settings from the Con‐
154 trol Panel.
155 If none of these is present, the C localtime and mktime functions are
156 used to attempt to convert times between local and Greenwich. On
157 32-bit systems, this approach is likely to have bugs, particularly for
158 times that lie outside the window (approximately the years 1902 to
159 2037) that can be represented in a 32-bit integer.
160
162 The clock add command performs clock arithmetic on a value (expressed
163 as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC)
164 given as its first argument. The remaining arguments (other than the
165 possible -timezone, -locale and -gmt options) are integers and keywords
166 in alternation, where the keywords are chosen from seconds, minutes,
167 hours, days, weeks, months, or years, or any unique prefix of such a
168 word.
169 Addition of seconds, minutes and hours is fairly straightforward; the
171 given time increment (times sixty for minutes, or 3600 for hours) is
172 simply added to the timeVal given to the clock add command. The result
173 is interpreted as a nominal number of seconds from the Epoch.
174 Surprising results may be obtained when crossing a point at which a
176 leap second is inserted or removed; the clock add command simply
177 ignores leap seconds and therefore assumes that times come in sequence,
178 23:59:58, 23:59:59, 00:00:00. (This assumption is handled by the fact
179 that Tcl's model of time reacts to leap seconds by speeding or slowing
180 the clock by a minuscule amount until Tcl's time is back in step with
181 the world.
182 The fact that adding and subtracting hours is defined in terms of abso‐
184 lute time means that it will add fixed amounts of time in time zones
185 that observe summer time (Daylight Saving Time). For example, the fol‐
186 lowing code sets the value of x to 04:00:00 because the clock has
187 changed in the interval in question.
188 set s [clock scan {2004-10-30 05:00:00} \
189 -format {%Y-%m-%d %H:%M:%S} \
190 -timezone :America/New_York]
191 set a [clock add $s 24 hours -timezone :America/New_York]
192 set x [clock format $a \
193 -format {%H:%M:%S} -timezone :America/New_York]
194 Adding and subtracting days and weeks is accomplished by converting the
196 given time to a calendar day and time of day in the appropriate time
197 zone and locale. The requisite number of days (weeks are converted to
198 days by multiplying by seven) is added to the calendar day, and the
199 date and time are then converted back to a count of seconds from the
200 epoch time.
201 Adding and subtracting a given number of days across the point that the
203 time changes at the start or end of summer time (Daylight Saving Time)
204 results in the same local time on the day in question. For instance,
205 the following code sets the value of x to 05:00:00.
206 set s [clock scan {2004-10-30 05:00:00} \
207 -format {%Y-%m-%d %H:%M:%S} \
208 -timezone :America/New_York]
209 set a [clock add $s 1 day -timezone :America/New_York]
210 set x [clock format $a \
211 -format {%H:%M:%S} -timezone :America/New_York]
212 In cases of ambiguity, where the same local time happens twice on the
214 same day, the earlier time is used. In cases where the conversion
215 yields an impossible time (for instance, 02:30 during the Spring Day‐
216 light Saving Time change using US rules), the time is converted as if
217 the clock had not changed. Thus, the following code will set the value
218 of x to 03:30:00.
219 set s [clock scan {2004-04-03 02:30:00} \
220 -format {%Y-%m-%d %H:%M:%S} \
221 -timezone :America/New_York]
222 set a [clock add $s 1 day -timezone :America/New_York]
223 set x [clock format $a \
224 -format {%H:%M:%S} -timezone :America/New_York]
225 Adding a given number of days or weeks works correctly across the con‐
227 version between the Julian and Gregorian calendars; the omitted days
228 are skipped. The following code sets z to 1752-09-14.
229 set x [clock scan 1752-09-02 -format %Y-%m-%d -locale en_US]
230 set y [clock add $x 1 day -locale en_US]
231 set z [clock format $y -format %Y-%m-%d -locale en_US]
232 In the bizarre case that adding the given number of days yields a date
234 that does not exist because it falls within the dropped days of the
235 Julian-to-Gregorian conversion, the date is converted as if it was on
236 the Julian calendar.
237 Adding a number of months, or a number of years, is similar; it con‐
239 verts the given time to a calendar date and time of day. It then adds
240 the requisite number of months or years, and reconverts the resulting
241 date and time of day to an absolute time.
242 If the resulting date is impossible because the month has too few days
244 (for example, when adding 1 month to 31 January), the last day of the
245 month is substituted. Thus, adding 1 month to 31 January will result
246 in 28 February in a common year or 29 February in a leap year.
247 The rules for handling anomalies relating to summer time and to the
249 Gregorian calendar are the same when adding/subtracting months and
250 years as they are when adding/subtracting days and weeks.
251 If multiple count unit pairs are present on the command, they are eval‐
253 uated consecutively, from left to right.
254
256 Most of the subcommands supported by the clock command deal with times
257 represented as a count of seconds from the epoch time, and this is the
258 representation that clock seconds returns. There are three exceptions,
259 which are all intended for use where higher-resolution times are
260 required. clock milliseconds returns the count of milliseconds from
261 the epoch time, and clock microseconds returns the count of microsec‐
262 onds from the epoch time. In addition, there is a clock clicks command
263 that returns a platform-dependent high-resolution timer. Unlike clock
264 seconds and clock milliseconds, the value of clock clicks is not guar‐
265 anteed to be tied to any fixed epoch; it is simply intended to be the
266 most precise interval timer available, and is intended only for rela‐
267 tive timing studies such as benchmarks.
268
270 The clock format command produces times for display to a user or writ‐
271 ing to an external medium. The command accepts times that are
272 expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC,
273 as returned by clock seconds, clock scan, clock add, file atime or file
274 mtime.
275 If a -format option is present, the following argument is a string that
277 specifies how the date and time are to be formatted. The string con‐
278 sists of any number of characters other than the per-cent sign (“%”)
279 interspersed with any number of format groups, which are two-character
280 sequences beginning with the per-cent sign. The permissible format
281 groups, and their interpretation, are described under FORMAT GROUPS.
282 If a -timezone option is present, the following argument is a string
284 that specifies the time zone in which the date and time are to be for‐
285 matted. As an alternative to “-timezone :UTC”, the obsolete usage
286 “-gmt true” may be used. See TIME ZONES for the permissible variants
287 for the time zone.
288 If a -locale option is present, the following argument is a string that
290 specifies the locale in which the time is to be formatted, in the same
291 format that is used for the msgcat package. Note that the default, if
292 -locale is not specified, is the root locale {} rather than the current
293 locale. The current locale may be obtained by using -locale current.
294 In addition, some platforms support a system locale that reflects the
295 user's current choices. For instance, on Windows, the format that the
296 user has selected from dates and times in the Control Panel can be
297 obtained by using the system locale. On platforms that do not define a
298 user selection of date and time formats separate from LC_TIME, -locale
299 system is synonymous with -locale current.
300
302 The clock scan command accepts times that are formatted as strings and
303 converts them to counts of seconds from the epoch time of 1 January
304 1970, 00:00 UTC. It normally takes a -format option that is followed
305 by a string describing the expected format of the input. (See FREE
306 FORM SCAN for the effect of clock scan without such an argument.) The
307 string consists of any number of characters other than the per-cent
308 sign (“%”), interspersed with any number of format groups, which are
309 two-character sequences beginning with the per-cent sign. The permis‐
310 sible format groups, and their interpretation, are described under FOR‐
311 MAT GROUPS.
312 If a -timezone option is present, the following argument is a string
314 that specifies the time zone in which the date and time are to be
315 interpreted. As an alternative to -timezone :UTC, the obsolete usage
316 -gmt true may be used. See TIME ZONES for the permissible variants for
317 the time zone.
318 If a -locale option is present, the following argument is a string that
320 specifies the locale in which the time is to be interpreted, in the
321 same format that is used for the msgcat package. Note that the
322 default, if -locale is not specified, is the root locale {} rather than
323 the current locale. The current locale may be obtained by using
324 -locale current. In addition, some platforms support a system locale
325 that reflects the user's current choices. For instance, on Windows,
326 the format that the user has selected from dates and times in the Con‐
327 trol Panel can be obtained by using the system locale. On platforms
328 that do not define a user selection of date and time formats separate
329 from LC_TIME, -locale system is synonymous with -locale current.
330 If a -base option is present, the following argument is a time
332 (expressed in seconds from the epoch time) that is used as a base time
333 for interpreting relative times. If no -base option is present, the
334 base time is the current time.
335 Scanning of times in fixed format works by determining three things:
337 the date, the time of day, and the time zone. These three are then
338 combined into a point in time, which is returned as the number of sec‐
339 onds from the epoch.
340 Before scanning begins, the format string is preprocessed to replace
342 %c, %Ec, %x, %Ex, %X. %Ex, %r, %R, %T, %D, %EY and %+ format groups
343 with counterparts that are appropriate to the current locale and con‐
344 tain none of the above groups. For instance, %D will (in the en_US
345 locale) be replaced with %m/%d/%Y.
346 The date is determined according to the fields that are present in the
348 preprocessed format string. In order of preference:
349 [1] If the string contains a %s format group, representing seconds
351 from the epoch, that group is used to determine the date.
352 [2] If the string contains a %J format group, representing the
354 Julian Day Number, that group is used to determine the date.
355 [3] If the string contains a complete set of format groups specify‐
357 ing century, year, month, and day of month; century, year, and
358 day of year; or ISO8601 fiscal year, week of year, and day of
359 week; those groups are combined and used to determine the date.
360 If more than one complete set is present, the one at the right‐
361 most position in the string is used.
362 [4] If the string lacks a century but contains a set of format
364 groups specifying year of century, month and day of month; year
365 of century and day of year; or two-digit ISO8601 fiscal year,
366 week of year, and day of week; those groups are combined and
367 used to determine the date. If more than one complete set is
368 present, the one at the rightmost position in the string is
369 used. The year is presumed to lie in the range 1938 to 2037
370 inclusive.
371 [5] If the string entirely lacks any specification for the year (or
373 contains the year only on the locale's alternative calendar) and
374 contains a set of format groups specifying month and day of
375 month, day of year, or week of year and day of week, those
376 groups are combined and used to determine the date. If more
377 than one complete set is present, the one at the rightmost posi‐
378 tion in the string is used. The year is determined by inter‐
379 preting the base time in the given time zone.
380 [6] If the string contains none of the above sets, but has a day of
382 the month or day of the week, the day of the month or day of the
383 week are used to determine the date by interpreting the base
384 time in the given time zone and returning the given day of the
385 current week or month. (The week runs from Monday to Sunday,
386 ISO8601-fashion.) If both day of month and day of week are
387 present, the day of the month takes priority.
388 [7] If none of the above rules results in a usable date, the date of
390 the base time in the given time zone is used.
391 The time is also determined according to the fields that are present in
393 the preprocessed format string. In order of preference:
394 [1] If the string contains a %s format group, representing seconds
396 from the epoch, that group determines the time of day.
397 [2] If the string contains either an hour on the 24-hour clock or an
399 hour on the 12-hour clock plus an AM/PM indicator, that hour
400 determines the hour of the day. If the string further contains
401 a group specifying the minute of the hour, that group combines
402 with the hour. If the string further contains a group specify‐
403 ing the second of the minute, that group combines with the hour
404 and minute.
405 [3] If the string contains neither a %s format group nor a group
407 specifying the hour of the day, then midnight (00:00, the start
408 of the given date) is used. The time zone is determined by
409 either the -timezone or -gmt options, or by using the current
410 time zone.
411 If a format string lacks a %z or %Z format group, it is possible for
413 the time to be ambiguous because it appears twice in the same day, once
414 without and once with Daylight Saving Time. If this situation occurs,
415 the first occurrence of the time is chosen. (For this reason, it is
416 wise to have the input string contain the time zone when converting
417 local times. This caveat does not apply to UTC times.)
418
420 The following format groups are recognized by the clock scan and clock
421 format commands.
422 %a On output, receives an abbreviation (e.g., Mon) for the day of
424 the week in the given locale. On input, matches the name of the
425 day of the week in the given locale (in either abbreviated or
426 full form, or any unique prefix of either form).
427 %A On output, receives the full name (e.g., Monday) of the day of
429 the week in the given locale. On input, matches the name of the
430 day of the week in the given locale (in either abbreviated or
431 full form, or any unique prefix of either form).
432 %b On output, receives an abbreviation (e.g., Jan) for the name of
434 the month in the given locale. On input, matches the name of
435 the month in the given locale (in either abbreviated or full
436 form, or any unique prefix of either form).
437 %B On output, receives the full name (e.g., January) of the month
439 in the given locale. On input, matches the name of the month in
440 the given locale (in either abbreviated or full form, or any
441 unique prefix of either form).
442 %c On output, receives a localized representation of date and time
444 of day; the localized representation is expected to use the Gre‐
445 gorian calendar. On input, matches whatever %c produces.
446 %C On output, receives the number of the century in Indo-Arabic
448 numerals. On input, matches one or two digits, possibly with
449 leading whitespace, that are expected to be the number of the
450 century.
451 %d On output, produces the number of the day of the month, as two
453 decimal digits. On input, matches one or two digits, possibly
454 with leading whitespace, that are expected to be the number of
455 the day of the month.
456 %D This format group is synonymous with %m/%d/%Y. It should be
458 used only in exchanging data within the en_US locale, since
459 other locales typically do not use this order for the fields of
460 the date.
461 %e On output, produces the number of the day of the month, as one
463 or two decimal digits (with a leading blank for one-digit
464 dates). On input, matches one or two digits, possibly with
465 leading whitespace, that are expected to be the number of the
466 day of the month.
467 %Ec On output, produces a locale-dependent representation of the
469 date and time of day in the locale's alternative calendar. On
470 input, matches whatever %Ec produces. The locale's alternative
471 calendar need not be the Gregorian calendar.
472 %EC On output, produces a locale-dependent name of an era in the
474 locale's alternative calendar. On input, matches the name of
475 the era or any unique prefix.
476 %EE On output, produces the string B.C.E. or C.E., or a string of
478 the same meaning in the locale, to indicate whether %Y refers to
479 years before or after Year 1 of the Common Era. On input,
480 accepts the string B.C.E., B.C., C.E., A.D., or the abbreviation
481 appropriate to the current locale, and uses it to fix whether %Y
482 refers to years before or after Year 1 of the Common Era.
483 %Ex On output, produces a locale-dependent representation of the
485 date in the locale's alternative calendar. On input, matches
486 whatever %Ex produces. The locale's alternative calendar need
487 not be the Gregorian calendar.
488 %EX On output, produces a locale-dependent representation of the
490 time of day in the locale's alternative numerals. On input,
491 matches whatever %EX produces.
492 %Ey On output, produces a locale-dependent number of the year of the
494 era in the locale's alternative calendar and numerals. On
495 input, matches such a number.
496 %EY On output, produces a representation of the year in the locale's
498 alternative calendar and numerals. On input, matches what %EY
499 produces. Often synonymous with %EC%Ey.
500 %g On output, produces a two-digit year number suitable for use
502 with the week-based ISO8601 calendar; that is, the year number
503 corresponds to the week number produced by %V. On input,
504 accepts such a two-digit year number, possibly with leading
505 whitespace.
506 %G On output, produces a four-digit year number suitable for use
508 with the week-based ISO8601 calendar; that is, the year number
509 corresponds to the week number produced by %V. On input,
510 accepts such a four-digit year number, possibly with leading
511 whitespace.
512 %h This format group is synonymous with %b.
514 %H On output, produces a two-digit number giving the hour of the
516 day (00-23) on a 24-hour clock. On input, accepts such a num‐
517 ber.
518 %I On output, produces a two-digit number giving the hour of the
520 day (12-11) on a 12-hour clock. On input, accepts such a num‐
521 ber.
522 %j On output, produces a three-digit number giving the day of the
524 year (001-366). On input, accepts such a number.
525 %J On output, produces a string of digits giving the Julian Day
527 Number. On input, accepts a string of digits and interprets it
528 as a Julian Day Number. The Julian Day Number is a count of the
529 number of calendar days that have elapsed since 1 January, 4713
530 BCE of the proleptic Julian calendar. The epoch time of 1 Janu‐
531 ary 1970 corresponds to Julian Day Number 2440588.
532 %k On output, produces a one- or two-digit number giving the hour
534 of the day (0-23) on a 24-hour clock. On input, accepts such a
535 number.
536 %l On output, produces a one- or two-digit number giving the hour
538 of the day (12-11) on a 12-hour clock. On input, accepts such a
539 number.
540 %m On output, produces the number of the month (01-12) with exactly
542 two digits. On input, accepts two digits and interprets them as
543 the number of the month.
544 %M On output, produces the number of the minute of the hour (00-59)
546 with exactly two digits. On input, accepts two digits and
547 interprets them as the number of the minute of the hour.
548 %N On output, produces the number of the month (1-12) with one or
550 two digits, and a leading blank for one-digit dates. On input,
551 accepts one or two digits, possibly with leading whitespace, and
552 interprets them as the number of the month.
553 %Od, %Oe, %OH, %OI, %Ok, %Ol, %Om, %OM, %OS, %Ou, %Ow, %Oy
555 All of these format groups are synonymous with their counter‐
556 parts without the “O”, except that the string is produced and
557 parsed in the locale-dependent alternative numerals.
558 %p On output, produces an indicator for the part of the day, AM or
560 PM, appropriate to the given locale. If the script of the given
561 locale supports multiple letterforms, lowercase is preferred.
562 On input, matches the representation AM or PM in the given
563 locale, in either case.
564 %P On output, produces an indicator for the part of the day, am or
566 pm, appropriate to the given locale. If the script of the given
567 locale supports multiple letterforms, uppercase is preferred.
568 On input, matches the representation AM or PM in the given
569 locale, in either case.
570 %Q This format group is reserved for internal use within the Tcl
572 library.
573 %r On output, produces a locale-dependent time of day representa‐
575 tion on a 12-hour clock. On input, accepts whatever %r produces.
576 %R On output, produces a locale-dependent time of day representa‐
578 tion on a 24-hour clock. On input, accepts whatever %R produces.
579 %s On output, simply formats the timeVal argument as a decimal
581 integer and inserts it into the output string. On input,
582 accepts a decimal integer and uses is as the time value without
583 any further processing. Since %s uniquely determines a point in
584 time, it overrides all other input formats.
585 %S On output, produces a two-digit number of the second of the
587 minute (00-59). On input, accepts two digits and uses them as
588 the second of the minute.
589 %t On output, produces a TAB character. On input, matches a TAB
591 character.
592 %T Synonymous with %H:%M:%S.
594 %u On output, produces the number of the day of the week (1→Monday,
596 7→Sunday). On input, accepts a single digit and interprets it as
597 the day of the week. Sunday may be either 0 or 7.
598 %U On output, produces the ordinal number of the week of the year
600 (00-53). The first Sunday of the year is the first day of week
601 01. On input accepts two digits which are otherwise ignored.
602 This format group is never used in determining an input date.
603 This interpretation of the week of the year was once common in
604 US banking but is now largely obsolete. See %V for the ISO8601
605 week number.
606 %V On output, produces the number of the ISO8601 week as a two
608 digit number (01-53). Week 01 is the week containing January 4;
609 or the first week of the year containing at least 4 days; or the
610 week containing the first Thursday of the year (the three state‐
611 ments are equivalent). Each week begins on a Monday. On input,
612 accepts the ISO8601 week number.
613 %w On output, produces the ordinal number of the day of the week
615 (Sunday==0; Saturday==6). On input, accepts a single digit and
616 interprets it as the day of the week; Sunday may be represented
617 as either 0 or 7. Note that %w is not the ISO8601 weekday num‐
618 ber, which is produced and accepted by %u.
619 %W On output, produces a week number (00-53) within the year; week
621 01 begins on the first Monday of the year. On input, accepts two
622 digits, which are otherwise ignored. This format group is never
623 used in determining an input date. It is not the ISO8601 week
624 number; that week is produced and accepted by %V.
625 %x On output, produces the date in a locale-dependent representa‐
627 tion. On input, accepts whatever %x produces and is used to
628 determine calendar date.
629 %X On output, produces the time of day in a locale-dependent repre‐
631 sentation. On input, accepts whatever %X produces and is used to
632 determine time of day.
633 %y On output, produces the two-digit year of the century. On input,
635 accepts two digits, and is used to determine calendar date. The
636 date is presumed to lie between 1938 and 2037 inclusive. Note
637 that %y does not yield a year appropriate for use with the
638 ISO8601 week number %V; programs should use %g for that purpose.
639 %Y On output, produces the four-digit calendar year. On input,
641 accepts four digits and may be used to determine calendar date.
642 Note that %Y does not yield a year appropriate for use with the
643 ISO8601 week number %V; programs should use %G for that purpose.
644 %z On output, produces the current time zone, expressed in hours
646 and minutes east (+hhmm) or west (-hhmm) of Greenwich. On input,
647 accepts a time zone specifier (see TIME ZONES below) that will
648 be used to determine the time zone.
649 %Z On output, produces the current time zone's name, possibly
651 translated to the given locale. On input, accepts a time zone
652 specifier (see TIME ZONES below) that will be used to determine
653 the time zone. This option should, in general, be used on input
654 only when parsing RFC822 dates. Other uses are fraught with
655 ambiguity; for instance, the string BST may represent British
656 Summer Time or Brazilian Standard Time. It is recommended that
657 date/time strings for use by computers use numeric time zones
658 instead.
659 %% On output, produces a literal “%” character. On input, matches a
661 literal “%” character.
662 %+ Synonymous with “%a %b %e %H:%M:%S %Z %Y”.
664
666 When the clock command is processing a local time, it has several pos‐
667 sible sources for the time zone to use. In order of preference, they
668 are:
669 [1] A time zone specified inside a string being parsed and matched
671 by a %z or %Z format group.
672 [2] A time zone specified with the -timezone option to the clock
674 command (or, equivalently, by -gmt 1).
675 [3] A time zone specified in an environment variable TCL_TZ.
677 [4] A time zone specified in an environment variable TZ.
679 [5] The local time zone from the Control Panel on Windows systems.
681 [6] The C library's idea of the local time zone, as defined by the
683 mktime and localtime functions.
684 In case [1] only, the string is tested to see if it is one of the
686 strings:
687 gmt ut utc bst wet wat at
688 nft nst ndt ast adt est edt
689 cst cdt mst mdt pst pdt yst
690 ydt hst hdt cat ahst nt idlw
691 cet cest met mewt mest swt sst
692 eet eest bt it zp4 zp5 ist
693 zp6 wast wadt jt cct jst cast
694 cadt east eadt gst nzt nzst nzdt
695 idle
696 If it is a string in the above list, it designates a known time zone,
697 and is interpreted as such.
698 For time zones in case [1] that do not match any of the above strings,
700 and always for cases [2]-[6], the following rules apply.
701 If the time zone begins with a colon, it is one of a standardized list
703 of names like :America/New_York that give the rules for various
704 locales. A complete list of the location names is too lengthy to be
705 listed here. On most Tcl installations, the definitions of the loca‐
706 tions are to be found in named files in the directory
707 “/no_backup/tools/lib/tcl8.5/clock/tzdata”. On some Unix systems,
708 these files are omitted, and the definitions are instead obtained from
709 system files in “/usr/share/zoneinfo”, “/usr/share/lib/zoneinfo” or
710 “/usr/local/etc/zoneinfo”. As a special case, the name :localtime
711 refers to the local time zone as defined by the C library.
712 A time zone string consisting of a plus or minus sign followed by four
714 or six decimal digits is interpreted as an offset in hours, minutes,
715 and seconds (if six digits are present) from UTC. The plus sign
716 denotes a sign east of Greenwich; the minus sign one west of Greenwich.
717 A time zone string conforming to the Posix specification of the TZ
719 environment variable will be recognized. The specification may be
720 found at http://www.open‐
721 group.org/onlinepubs/009695399/basedefs/xbd_chap08.html.
722 Any other time zone string is processed by prefixing a colon and
724 attempting to use it as a location name, as above.
725
727 Developers wishing to localize the date and time formatting and parsing
728 are referred to http://tip.tcl.tk/173 for a specification.
729
731 If the clock scan command is invoked without a -format option, then it
732 requests a free-form scan. This form of scan is deprecated. The rea‐
733 son for the deprecation is that there are too many ambiguities. (Does
734 the string “2000” represent a year, a time of day, or a quantity?) No
735 set of rules for interpreting free-form dates and times has been found
736 to give unsurprising results in all cases.
737 If free-form scan is used, only the -base and -gmt options are
739 accepted. The -timezone and -locale options will result in an error if
740 -format is not supplied.
741 For the benefit of users who need to understand legacy code that uses
743 free-form scan, the documentation for how free-form scan interprets a
744 string is included here:
745 If only a time is specified, the current date is assumed. If the
747 inputString does not contain a time zone mnemonic, the local time zone
748 is assumed, unless the -gmt argument is true, in which case the clock
749 value is calculated assuming that the specified time is relative to
750 Greenwich Mean Time. -gmt, if specified, affects only the computed
751 time value; it does not impact the interpretation of -base.
752 If the -base flag is specified, the next argument should contain an
754 integer clock value. Only the date in this value is used, not the
755 time. This is useful for determining the time on a specific day or
756 doing other date-relative conversions.
757 The inputString argument consists of zero or more specifications of the
759 following form:
760 time A time of day, which is of the form: hh?:mm?:ss?? ?meridian?
762 ?zone? or hhmm ?meridian? ?zone? If no meridian is specified,
763 hh is interpreted on a 24-hour clock.
764 date A specific month and day with optional year. The acceptable
766 formats are “mm/dd?/yy?”, “monthname dd?, yy?”, “day, dd month‐
767 name ?yy?”, “dd monthname yy”, “?CC?yymmdd”, and “dd-month‐
768 name-?CC?yy”. The default year is the current year. If the
769 year is less than 100, we treat the years 00-68 as 2000-2068 and
770 the years 69-99 as 1969-1999. Not all platforms can represent
771 the years 38-70, so an error may result if these years are used.
772 ISO 8601 point-in-time
774 An ISO 8601 point-in-time specification, such as “CCyymmddThh‐
775 mmss,” where T is the literal “T”, “CCyymmdd hhmmss”, or “CCyym‐
776 mddThh:mm:ss”. Note that only these three formats are accepted.
777 The command does not accept the full range of point-in-time
778 specifications specified in ISO8601. Other formats can be rec‐
779 ognized by giving an explicit -format option to the clock scan
780 command.
781 relative time
783 A specification relative to the current time. The format is
784 number unit. Acceptable units are year, fortnight, month, week,
785 day, hour, minute (or min), and second (or sec). The unit can
786 be specified as a singular or plural, as in 3 weeks. These mod‐
787 ifiers may also be specified: tomorrow, yesterday, today, now,
788 last, this, next, ago.
789 The actual date is calculated according to the following steps.
791 First, any absolute date and/or time is processed and converted. Using
793 that time as the base, day-of-week specifications are added. Next,
794 relative specifications are used. If a date or day is specified, and
795 no absolute or relative time is given, midnight is used. Finally, a
796 correction is applied so that the correct hour of the day is produced
797 after allowing for daylight savings time differences and the correct
798 date is given when going from the end of a long month to a short month.
799
801 msgcat(n)
802
804 clock, date, time
805
807 Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights
808 reserved.
809Tcl 8.5 clock(n)