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
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
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
118              description 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
179       ignores 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
241       Julian-to-Gregorian  conversion,  the date is converted as if it was on
242       the 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
266       required.   clock  milliseconds  returns the count of milliseconds from
267       the epoch time, and clock microseconds returns the count  of  microsec‐
268       onds  from the epoch time. In addition, there is a clock clicks command
269       that returns a platform-dependent high-resolution timer.  Unlike  clock
270       seconds  and clock milliseconds, the value of clock clicks is not guar‐
271       anteed 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
278       expressed in seconds from the epoch time of 1 January 1970, 00:00  UTC,
279       as 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
303       obtained 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
321       interpreted.  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
328       default, if -locale is not specified, is the root locale {} rather than
329       the current locale.  The  current  locale  may  be  obtained  by  using
330       -locale  current.   In addition, some platforms support a system locale
331       that reflects the user's current choices.  For  instance,  on  Windows,
332       the  format that the user has selected from dates and times in the Con‐
333       trol Panel can be obtained by using the system  locale.   On  platforms
334       that  do  not define a user selection of date and time formats separate
335       from LC_TIME, -locale system is synonymous with -locale current.
336
337       If a -base  option  is  present,  the  following  argument  is  a  time
338       (expressed  in seconds from the epoch time) that is used as a base time
339       for interpreting relative times.  If no -base option  is  present,  the
340       base 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
351       locale) 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
360              Julian 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
376              inclusive.
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
406              determines  the hour of the day.  If the string further contains
407              a 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
415              either the -timezone or -gmt options, or by  using  the  current
416              time 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
423       local times.  This caveat does not apply to UTC times.)
424

FORMAT GROUPS

426       The following format groups are recognized by the clock scan and  clock
427       format commands.
428
429       %a     On  output,  receives an abbreviation (e.g., Mon) for the day of
430              the week in the given locale.  On input, matches the name of the
431              day  of  the  week in the given locale (in either abbreviated or
432              full form, or any unique prefix of either form).
433
434       %A     On output, receives the full name (e.g., Monday) of the  day  of
435              the week in the given locale.  On input, matches the name of the
436              day of the week in the given locale (in  either  abbreviated  or
437              full form, or any unique prefix of either form).
438
439       %b     On  output, receives an abbreviation (e.g., Jan) for the name of
440              the month in the given locale.  On input, matches  the  name  of
441              the  month  in  the  given locale (in either abbreviated or full
442              form, or any unique prefix of either form).
443
444       %B     On output, receives the full name (e.g., January) of  the  month
445              in the given locale.  On input, matches the name of the month in
446              the given locale (in either abbreviated or  full  form,  or  any
447              unique prefix of either form).
448
449       %c     On  output, receives a localized representation of date and time
450              of day; the localized representation is expected to use the Gre‐
451              gorian calendar.  On input, matches whatever %c produces.
452
453       %C     On  output,  receives  the  number of the century in Indo-Arabic
454              numerals.  On input, matches one or two  digits,  possibly  with
455              leading  whitespace,  that  are expected to be the number of the
456              century.
457
458       %d     On output, produces the number of the day of the month,  as  two
459              decimal  digits.   On input, matches one or two digits, possibly
460              with leading whitespace, that are expected to be the  number  of
461              the day of the month.
462
463       %D     This  format  group  is  synonymous with %m/%d/%Y.  It should be
464              used only in exchanging data  within  the  en_US  locale,  since
465              other  locales typically do not use this order for the fields of
466              the date.
467
468       %e     On output, produces the number of the day of the month,  as  one
469              or  two  decimal  digits  (with  a  leading  blank for one-digit
470              dates).  On input, matches one  or  two  digits,  possibly  with
471              leading  whitespace,  that  are expected to be the number of the
472              day of the month.
473
474       %Ec    On output, produces a  locale-dependent  representation  of  the
475              date  and  time of day in the locale's alternative calendar.  On
476              input, matches whatever %Ec produces.  The locale's  alternative
477              calendar need not be the Gregorian calendar.
478
479       %EC    On  output,  produces  a  locale-dependent name of an era in the
480              locale's alternative calendar.  On input, matches  the  name  of
481              the era or any unique prefix.
482
483       %EE    On  output,  produces  the string B.C.E. or C.E., or a string of
484              the same meaning in the locale, to indicate whether %Y refers to
485              years  before  or  after  Year  1  of the Common Era.  On input,
486              accepts the string B.C.E., B.C., C.E., A.D., or the abbreviation
487              appropriate to the current locale, and uses it to fix whether %Y
488              refers to years before or after Year 1 of the Common Era.
489
490       %Ex    On output, produces a  locale-dependent  representation  of  the
491              date  in  the  locale's alternative calendar.  On input, matches
492              whatever %Ex produces.  The locale's alternative  calendar  need
493              not be the Gregorian calendar.
494
495       %EX    On  output,  produces  a  locale-dependent representation of the
496              time of day in the locale's  alternative  numerals.   On  input,
497              matches whatever %EX produces.
498
499       %Ey    On output, produces a locale-dependent number of the year of the
500              era in the  locale's  alternative  calendar  and  numerals.   On
501              input, matches such a number.
502
503       %EY    On output, produces a representation of the year in the locale's
504              alternative calendar and numerals.  On input, matches  what  %EY
505              produces.  Often synonymous with %EC%Ey.
506
507       %g     On  output,  produces  a  two-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 two-digit  year  number,  possibly  with  leading
511              whitespace.
512
513       %G     On  output,  produces  a four-digit year number suitable for use
514              with the week-based ISO8601 calendar; that is, the  year  number
515              corresponds  to  the  week  number  produced  by  %V.  On input,
516              accepts such a four-digit year  number,  possibly  with  leading
517              whitespace.
518
519       %h     This format group is synonymous with %b.
520
521       %H     On  output,  produces  a two-digit number giving the hour of the
522              day (00-23) on a 24-hour clock.  On input, accepts such  a  num‐
523              ber.
524
525       %I     On  output,  produces  a two-digit number giving the hour of the
526              day (12-11) on a 12-hour clock.  On input, accepts such  a  num‐
527              ber.
528
529       %j     On  output,  produces a three-digit number giving the day of the
530              year (001-366).  On input, accepts such a number.
531
532       %J     On output, produces a string of digits  giving  the  Julian  Day
533              Number.   On input, accepts a string of digits and interprets it
534              as a Julian Day Number.  The Julian Day Number is a count of the
535              number  of calendar days that have elapsed since 1 January, 4713
536              BCE of the proleptic Julian calendar.  The epoch time of 1 Janu‐
537              ary 1970 corresponds to Julian Day Number 2440588.
538
539       %k     On  output,  produces a one- or two-digit number giving the hour
540              of the day (0-23) on a 24-hour clock.  On input, accepts such  a
541              number.
542
543       %l     On  output,  produces a one- or two-digit number giving the hour
544              of the day (12-11) on a 12-hour clock.  On input, accepts such a
545              number.
546
547       %m     On output, produces the number of the month (01-12) with exactly
548              two digits.  On input, accepts two digits and interprets them as
549              the number of the month.
550
551       %M     On output, produces the number of the minute of the hour (00-59)
552              with exactly two digits.   On  input,  accepts  two  digits  and
553              interprets them as the number of the minute of the hour.
554
555       %N     On  output,  produces the number of the month (1-12) with one or
556              two digits, and a leading blank for one-digit dates.  On  input,
557              accepts one or two digits, possibly with leading whitespace, and
558              interprets them as the number of the month.
559
560       %Od, %Oe, %OH, %OI, %Ok, %Ol, %Om, %OM, %OS, %Ou, %Ow, %Oy
561              All of these format groups are synonymous  with  their  counter‐
562              parts  without  the  “O”, except that the string is produced and
563              parsed in the locale-dependent alternative numerals.
564
565       %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,  lowercase  is  preferred.
568              On  input,  matches  the  representation  AM  or PM in the given
569              locale, in either case.
570
571       %P     On output, produces an indicator for the part of the day, am  or
572              pm, appropriate to the given locale.  If the script of the given
573              locale supports multiple letterforms,  uppercase  is  preferred.
574              On  input,  matches  the  representation  AM  or PM in the given
575              locale, in either case.
576
577       %Q     This format group is reserved for internal use  within  the  Tcl
578              library.
579
580       %r     On  output,  produces a locale-dependent time of day representa‐
581              tion on a 12-hour clock. On input, accepts whatever %r produces.
582
583       %R     On output, the time in 24-hour notation (%H:%M). For  a  version
584              including  the seconds, see %T below. On input, accepts whatever
585              %R produces.
586
587       %s     On output, simply formats the  timeVal  argument  as  a  decimal
588              integer  and  inserts  it  into  the  output  string.  On input,
589              accepts a decimal integer and uses is as the time value  without
590              any  further processing. Since %s uniquely determines a point in
591              time, it overrides all other input formats.
592
593       %S     On output, produces a two-digit number  of  the  second  of  the
594              minute  (00-59).  On  input, accepts two digits and uses them as
595              the second of the minute.
596
597       %t     On output, produces a TAB character. On  input,  matches  a  TAB
598              character.
599
600       %T     Synonymous with %H:%M:%S.
601
602       %u     On output, produces the number of the day of the week (1→Monday,
603              7→Sunday). On input, accepts a single digit and interprets it as
604              the day of the week. Sunday may be either 0 or 7.
605
606       %U     On  output,  produces the ordinal number of the week of the year
607              (00-53). The first Sunday of the year is the first day  of  week
608              01.  On  input  accepts  two digits which are otherwise ignored.
609              This format group is never used in determining  an  input  date.
610              This  interpretation  of the week of the year was once common in
611              US banking but is now largely obsolete.  See %V for the  ISO8601
612              week number.
613
614       %V     On  output,  produces  the  number  of the ISO8601 week as a two
615              digit number (01-53). Week 01 is the week containing January  4;
616              or the first week of the year containing at least 4 days; or the
617              week containing the first Thursday of the year (the three state‐
618              ments  are  equivalent). Each week begins on a Monday. On input,
619              accepts the ISO8601 week number.
620
621       %w     On output, produces the ordinal number of the day  of  the  week
622              (Sunday==0;  Saturday==6).  On input, accepts a single digit and
623              interprets it as the day of the week; Sunday may be  represented
624              as  either 0 or 7.  Note that %w is not the ISO8601 weekday num‐
625              ber, which is produced and accepted by %u.
626
627       %W     On output, produces a week number (00-53) within the year;  week
628              01 begins on the first Monday of the year. On input, accepts two
629              digits, which are otherwise ignored. This format group is  never
630              used  in  determining an input date.  It is not the ISO8601 week
631              number; that week is produced and accepted by %V.
632
633       %x     On output, produces the date in a  locale-dependent  representa‐
634              tion.  On  input,  accepts  whatever  %x produces and is used to
635              determine calendar date.
636
637       %X     On output, produces the time of day in a locale-dependent repre‐
638              sentation. On input, accepts whatever %X produces and is used to
639              determine time of day.
640
641       %y     On output, produces the two-digit year of the century. On input,
642              accepts  two digits, and is used to determine calendar date. The
643              date is presumed to lie between 1938 and  2037  inclusive.  Note
644              that  %y  does  not  yield  a  year appropriate for use with the
645              ISO8601 week number %V; programs should use %g for that purpose.
646
647       %Y     On output, produces the  four-digit  calendar  year.  On  input,
648              accepts  four digits and may be used to determine calendar date.
649              Note that %Y does not yield a year appropriate for use with  the
650              ISO8601 week number %V; programs should use %G for that purpose.
651
652       %z     On  output,  produces  the current time zone, expressed in hours
653              and minutes east (+hhmm) or west (-hhmm) of Greenwich. On input,
654              accepts  a  time zone specifier (see TIME ZONES below) that will
655              be used to determine the time zone.
656
657       %Z     On output, produces  the  current  time  zone's  name,  possibly
658              translated  to  the  given locale. On input, accepts a time zone
659              specifier (see TIME ZONES below) that will be used to  determine
660              the  time zone. This option should, in general, be used on input
661              only when parsing RFC822 dates.  Other  uses  are  fraught  with
662              ambiguity;  for  instance,  the string BST may represent British
663              Summer Time or Brazilian Standard Time. It is  recommended  that
664              date/time  strings  for  use by computers use numeric time zones
665              instead.
666
667       %%     On output, produces a literal “%” character. On input, matches a
668              literal “%” character.
669
670       %+     Synonymous with “%a %b %e %H:%M:%S %Z %Y”.
671

TIME ZONES

673       When  the clock command is processing a local time, it has several pos‐
674       sible sources for the time zone to use.  In order of  preference,  they
675       are:
676
677       [1]    A  time  zone specified inside a string being parsed and matched
678              by a %z or %Z format group.
679
680       [2]    A time zone specified with the -timezone  option  to  the  clock
681              command (or, equivalently, by -gmt 1).
682
683       [3]    A time zone specified in an environment variable TCL_TZ.
684
685       [4]    A time zone specified in an environment variable TZ.
686
687       [5]    The local time zone from the Control Panel on Windows systems.
688
689       [6]    The  C  library's idea of the local time zone, as defined by the
690              mktime and localtime functions.
691
692       In case [1] only, the string is tested to see  if  it  is  one  of  the
693       strings:
694
695               gmt     ut      utc     bst     wet     wat     at
696               nft     nst     ndt     ast     adt     est     edt
697               cst     cdt     mst     mdt     pst     pdt     yst
698               ydt     hst     hdt     cat     ahst    nt      idlw
699               cet     cest    met     mewt    mest    swt     sst
700               eet     eest    bt      it      zp4     zp5     ist
701               zp6     wast    wadt    jt      cct     jst     cast
702               cadt    east    eadt    gst     nzt     nzst    nzdt
703               idle
704
705       If  it  is a string in the above list, it designates a known time zone,
706       and is interpreted as such.
707
708       For time zones in case [1] that do not match any of the above  strings,
709       and always for cases [2]-[6], the following rules apply.
710
711       If  the time zone begins with a colon, it is one of a standardized list
712       of names  like  :America/New_York  that  give  the  rules  for  various
713       locales.   A  complete  list of the location names is too lengthy to be
714       listed here.  On most Tcl installations, the definitions of  the  loca‐
715       tions   are   to   be   found   in   named   files   in  the  directory
716/no_backup/tools/lib/tcl8.5/clock/tzdata”.   On  some  Unix   systems,
717       these  files are omitted, and the definitions are instead obtained from
718       system files  in  “/usr/share/zoneinfo”,  “/usr/share/lib/zoneinfo”  or
719/usr/local/etc/zoneinfo”.   As  a  special  case,  the name :localtime
720       refers to the local time zone as defined by the C library.
721
722       A time zone string consisting of a plus or minus sign followed by  four
723       or  six  decimal  digits is interpreted as an offset in hours, minutes,
724       and seconds (if six digits  are  present)  from  UTC.   The  plus  sign
725       denotes a sign east of Greenwich; the minus sign one west of Greenwich.
726
727       A  time  zone  string  conforming  to the Posix specification of the TZ
728       environment variable will be  recognized.   The  specification  may  be
729       found                        at                        http://www.open
730       group.org/onlinepubs/009695399/basedefs/xbd_chap08.html.
731
732       If the Posix time zone string contains a DST  (Daylight  Savings  Time)
733       part,  but doesn't contain a rule stating when DST starts or ends, then
734       default rules are used. For Timezones with an offset between 0 and +12,
735       the  current  European/Russian rules are used, otherwise the current US
736       rules are used. In Europe (offset +0 to +2) the switch to summertime is
737       done each last Sunday in March at 1:00 GMT, and the switch back is each
738       last Sunday in October at 2:00 GMT. In Russia (offset +3 to  +12),  the
739       switch  dates  are  the  same, only the switch to summertime is at 2:00
740       local time, and the switch back is at  3:00  local  time  in  all  time
741       zones.  The  US  switch to summertime takes place each second Sunday in
742       March at 2:00 local time, and the switch back is each first  Sunday  in
743       November at 3:00 local time. These default rules mean that in all Euro‐
744       pean, Russian and US (or compatible) time zones, DST calculations  will
745       be  correct for dates in 2007 and later, unless in the future the rules
746       change again.
747
748       Any other time zone string  is  processed  by  prefixing  a  colon  and
749       attempting to use it as a location name, as above.
750

LOCALIZATION

752       Developers wishing to localize the date and time formatting and parsing
753       are referred to http://tip.tcl.tk/173 for a specification.
754

FREE FORM SCAN

756       If the clock scan command is invoked without a -format option, then  it
757       requests  a free-form scan.  This form of scan is deprecated.  The rea‐
758       son for the deprecation is that there are too many  ambiguities.  (Does
759       the  string “2000” represent a year, a time of day, or a quantity?)  No
760       set of rules for interpreting free-form dates and times has been  found
761       to give unsurprising results in all cases.
762
763       If  free-form  scan  is  used,  only  the  -base  and  -gmt options are
764       accepted.  The -timezone and -locale options will result in an error if
765       -format is not supplied.
766
767       For  the  benefit of users who need to understand legacy code that uses
768       free-form scan, the documentation for how free-form scan  interprets  a
769       string is included here:
770
771       If  only  a  time  is  specified,  the current date is assumed.  If the
772       inputString does not contain a time zone mnemonic, the local time  zone
773       is  assumed,  unless the -gmt argument is true, in which case the clock
774       value is calculated assuming that the specified  time  is  relative  to
775       Greenwich  Mean  Time.   -gmt,  if specified, affects only the computed
776       time value; it does not impact the interpretation of -base.
777
778       If the -base flag is specified, the next  argument  should  contain  an
779       integer  clock  value.   Only  the  date in this value is used, not the
780       time.  This is useful for determining the time on  a  specific  day  or
781       doing other date-relative conversions.
782
783       The inputString argument consists of zero or more specifications of the
784       following form:
785
786       time   A time of day, which is of  the  form:  hh?:mm?:ss??  ?meridian?
787              ?zone?   or hhmm ?meridian? ?zone?  If no meridian is specified,
788              hh is interpreted on a 24-hour clock.
789
790       date   A specific month and day with  optional  year.   The  acceptable
791              formats  are “mm/dd?/yy?”, “monthname dd?, yy?”, “day, dd month‐
792              name ?yy?”, “dd  monthname  yy”,  “?CC?yymmdd”,  and  “dd-month‐
793              name-?CC?yy”.   The  default  year  is the current year.  If the
794              year is less than 100, we treat the years 00-68 as 2000-2068 and
795              the  years  69-99 as 1969-1999.  Not all platforms can represent
796              the years 38-70, so an error may result if these years are used.
797
798       ISO 8601 point-in-time
799              An ISO 8601 point-in-time specification, such  as  “CCyymmddThh‐
800              mmss,” where T is the literal “T”, “CCyymmdd hhmmss”, or “CCyym‐
801              mddThh:mm:ss”.  Note that only these three formats are accepted.
802              The  command  does  not  accept  the full range of point-in-time
803              specifications specified in ISO8601.  Other formats can be  rec‐
804              ognized  by  giving an explicit -format option to the clock scan
805              command.
806
807       relative time
808              A specification relative to the current  time.   The  format  is
809              number  unit. Acceptable units are year, fortnight, month, week,
810              day, hour, minute (or min), and second (or sec).  The  unit  can
811              be specified as a singular or plural, as in 3 weeks.  These mod‐
812              ifiers may also be specified: tomorrow, yesterday,  today,  now,
813              last, this, next, ago.
814
815       The actual date is calculated according to the following steps.
816
817       First, any absolute date and/or time is processed and converted.  Using
818       that time as the base, day-of-week  specifications  are  added.   Next,
819       relative  specifications  are used.  If a date or day is specified, and
820       no absolute or relative time is given, midnight is  used.   Finally,  a
821       correction  is  applied so that the correct hour of the day is produced
822       after allowing for daylight savings time differences  and  the  correct
823       date is given when going from the end of a long month to a short month.
824

SEE ALSO

826       msgcat(n)
827

KEYWORDS

829       clock, date, time
830
832       Copyright  (c)  2004  Kevin  B.  Kenny  <kennykb@acm.org>.  All  rights
833       reserved.
834
835
836
837Tcl                                   8.5                             clock(n)
Impressum