1clock(n)                     Tcl Built-In Commands                    clock(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       clock - Obtain and manipulate dates and times
9

SYNOPSIS

11       package require Tcl 8.5
12
13       clock add timeVal ?count unit...? ?-option value?
14
15       clock clicks ?-option?
16
17       clock format timeVal ?-option value...?
18
19       clock microseconds
20
21       clock milliseconds
22
23       clock scan inputString ?-option value...?
24
25       clock seconds
26
27______________________________________________________________________________
28

DESCRIPTION

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
34       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
39       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
46              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
51              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
56       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
61       clock microseconds
62              Returns  the  current time as an integer number of microseconds.
63              See HIGH RESOLUTION TIMERS for a full description.
64
65       clock milliseconds
66              Returns the current time as an integer number  of  milliseconds.
67              See HIGH RESOLUTION TIMERS for a full description.
68
69       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
74       clock seconds
75              Returns the current time as an integer number of seconds.
76
77   PARAMETERS
78       count  An integer representing a count of some unit of time.  See CLOCK
79              ARITHMETIC for the details.
80
81       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
91       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
96   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
103       -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
112              On clock format, the default format is
113
114                     %a %b %d %H:%M:%S %Z %Y
115
116              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
120       -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
128       -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
137              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
142       -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
150              [1]    the environment variable TCL_TZ.
151
152              [2]    the environment variable TZ.
153
154              [3]    on Windows systems, the time zone settings from the  Con‐
155                     trol Panel.
156
157       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

CLOCK ARITHMETIC

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
172       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
177       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
185       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
191              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
198       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
205       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
210              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
217       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
224              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
231       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
235              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
239       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
244       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
249       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
254       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
258       If multiple count unit pairs are present on the command, they are eval‐
259       uated consecutively, from left to right.
260

HIGH RESOLUTION TIMERS

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

FORMATTING TIMES

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
282       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
289       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
295       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

SCANNING TIMES

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
319       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
325       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
337       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
342       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
347       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
353       The date is determined according to the fields that are present in  the
354       preprocessed format string.  In order of preference:
355
356       [1]    If  the  string contains a %s format group, representing seconds
357              from the epoch, that group is used to determine the date.
358
359       [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
362       [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
369       [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
378       [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
387       [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
395       [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
398       The time is also determined according to the fields that are present in
399       the preprocessed format string.  In order of preference:
400
401       [1]    If the string contains a %s format group,  representing  seconds
402              from the epoch, that group determines the time of day.
403
404       [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
412       [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
418       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
425       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
431       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

FORMAT GROUPS

439       The  following format groups are recognized by the clock scan and clock
440       format commands.
441
442       %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
447       %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
452       %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
457       %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
462       %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
466       %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
471       %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
476       %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
481       %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
487       %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
492       %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
496       %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
503       %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
508       %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
512       %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
516       %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
520       %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
526       %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
532       %h     This format group is synonymous with %b.
533
534       %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
538       %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
542       %j     On output, produces a three-digit number giving the day  of  the
543              year (001-366).  On input, accepts such a number.
544
545       %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
552       %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
556       %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
560       %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
564       %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
568       %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
573       %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
578       %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
584       %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
590       %Q     This  format  group  is reserved for internal use within the Tcl
591              library.
592
593       %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
596       %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
600       %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
606       %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
610       %t     On  output,  produces  a  TAB character. On input, matches a TAB
611              character.
612
613       %T     Synonymous with %H:%M:%S.
614
615       %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
619       %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
627       %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
634       %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
640       %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
646       %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
650       %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
654       %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
660       %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
665       %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
670       %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
680       %%     On output, produces a literal “%” character. On input, matches a
681              literal “%” character.
682
683       %+     Synonymous with “%a %b %e %H:%M:%S %Z %Y”.
684

TIME ZONES

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
690       [1]    A time zone specified inside a string being parsed  and  matched
691              by a %z or %Z format group.
692
693       [2]    A  time  zone  specified  with the -timezone option to the clock
694              command (or, equivalently, by -gmt 1).
695
696       [3]    A time zone specified in an environment variable TCL_TZ.
697
698       [4]    A time zone specified in an environment variable TZ.
699
700       [5]    The local time zone from the Control Panel on Windows systems.
701
702       [6]    The C library's idea of the local time zone, as defined  by  the
703              mktime and localtime functions.
704
705       In  case  [1]  only,  the  string  is tested to see if it is one of the
706       strings:
707
708               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
718       If it is a string in the above list, it designates a known  time  zone,
719       and is interpreted as such.
720
721       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
724       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
735       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
740       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
745       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
761       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

LOCALIZATION

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

FREE FORM SCAN

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
776       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
780       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
784       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
791       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
796       The inputString argument consists of zero or more specifications of the
797       following form:
798
799       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
803       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
811       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
820       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
828       The actual date is calculated according to the following steps.
829
830       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

SEE ALSO

839       msgcat(n)
840

KEYWORDS

842       clock, date, time
843
845       Copyright © 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
846
847
848
849Tcl                                   8.5                             clock(n)
Impressum