summaryrefslogtreecommitdiffstats
path: root/doc/clock.n
blob: 53db33eddd811b40ee7311fe1b9a956a5df7013f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
'\"
'\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
.TH "clock" n 8.5 Tcl "Tcl Built-In Commands"
.so man.macros
.BS
.SH NAME
clock \- Obtain and manipulate dates and times
.SH "SYNOPSIS"
package require \fBTcl 8.5\fR
.sp
\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
.sp
\fBclock clicks\fR ?\fI\-option\fR?
.sp
\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
.sp
\fBclock microseconds\fR
.sp
\fBclock milliseconds\fR
.sp
\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
.sp
\fBclock seconds\fR
.sp
.BE
.SH "DESCRIPTION"
.PP
The \fBclock\fR command performs several operations that obtain and
manipulate values that represent times.  The command supports several
subcommands that determine what action is carried out by the command.
.TP
\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
Adds a (possibly negative) offset to a time that is expressed as an
integer number of seconds.  See \fBCLOCK ARITHMETIC\fR for a full description.
.TP
\fBclock clicks\fR ?\fI\-option\fR?
If no \fI\-option\fR argument is supplied, returns a high-resolution
time value as a system-dependent integer value.  The unit of the value
is system-dependent but should be the highest resolution clock available
on the system such as a CPU cycle counter.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.RS
.PP
If the \fI\-option\fR argument is \fB\-milliseconds\fR, then the command
is synonymous with \fBclock milliseconds\fR (see below).  This
usage is obsolete, and \fBclock milliseconds\fR is to be
considered the preferred way of obtaining a count of milliseconds.
.PP
If the \fI\-option\fR argument is \fB\-microseconds\fR, then the command
is synonymous with \fBclock microseconds\fR (see below).  This
usage is obsolete, and \fBclock microseconds\fR is to be
considered the preferred way of obtaining a count of microseconds.
.RE
.TP
\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
Formats a time that is expressed as an integer number of seconds into a format
intended for consumption by users or external programs.
See \fBFORMATTING TIMES\fR for a full description.
.TP
\fBclock microseconds\fR
Returns the current time as an integer number of microseconds.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.TP
\fBclock milliseconds\fR
Returns the current time as an integer number of milliseconds.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.TP
\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
Scans a time that is expressed as a character string and produces an
integer number of seconds.
See \fBSCANNING TIMES\fR for a full description.
.TP
\fBclock seconds\fR
Returns the current time as an integer number of seconds.
.SS "PARAMETERS"
.TP
\fIcount\fR
An integer representing a count of some unit of time.  See
\fBCLOCK ARITHMETIC\fR for the details.
.TP
\fItimeVal\fR
An integer value passed to the \fBclock\fR command that represents an
absolute time as a number of seconds from the \fIepoch time\fR of
1 January 1970, 00:00 UTC.  Note that the count of seconds does not
include any leap seconds; seconds are counted as if each UTC day has
exactly 86400 seconds.  Tcl responds to leap seconds by speeding or
slowing its clock by a tiny fraction for some minutes until it is
back in sync with UTC; its data model does not represent minutes that
have 59 or 61 seconds.
.TP
\fIunit\fR
One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
\fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR.
Used in conjunction with \fIcount\fR to identify an interval of time,
for example, \fI3 seconds\fR or \fI1 year\fR.
.SS "OPTIONS"
.TP
\fB\-base\fR time
Specifies that any relative times present in a \fBclock scan\fR command
are to be given relative to \fItime\fR.  \fItime\fR must be expressed as
a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC.
.TP
\fB\-format\fR format
Specifies the desired output format for \fBclock format\fR or the
expected input format for \fBclock scan\fR.  The \fIformat\fR string consists
of any number of characters other than the per-cent sign
.PQ \fB%\fR
interspersed with any number of \fIformat groups\fR, which are two-character
sequences beginning with the per-cent sign.  The permissible format groups,
and their interpretation, are described under \fBFORMAT GROUPS\fR.
.RS
.PP
On \fBclock format\fR, the default format is
.PP
.CS
%a %b %d %H:%M:%S %Z %Y
.CE
.PP
On \fBclock scan\fR, the lack of a \fB\-format\fR option indicates that a
.QW "free format scan"
is requested; see \fBFREE FORM SCAN\fR for a description of what happens.
.RE
.TP
\fB\-gmt\fR boolean
If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR,
\fBclock format\fR or \fBclock scan\fR should be processed in
UTC.  If \fIboolean\fR is false, the processing defaults to the local time
zone.  This usage is obsolete; the correct current usage is to
specify the UTC time zone with
.QW "\fB\-timezone\fR \fI:UTC\fR"
or any of the equivalent ways to specify it.
.TP
\fB\-locale\fR localeName
Specifies that locale-dependent scanning and formatting (and date arithmetic
for dates preceding the adoption of the Gregorian calendar) is to be done in
the locale identified by \fIlocaleName\fR.  The locale name may be any of
the locales acceptable to the \fBmsgcat\fR package, or it may be the special
name \fIsystem\fR, which represents the current locale of the process, or
the null string, which represents Tcl's default locale.
.RS
.PP
The effect of locale on scanning and formatting is discussed in the
descriptions of the individual format groups under \fBFORMAT GROUPS\fR.
The effect of locale on clock arithmetic is discussed under
\fBCLOCK ARITHMETIC\fR.
.RE
.TP
\fB\-timezone\fR zoneName
Specifies that clock arithmetic, formatting, and scanning are to be done
according to the rules for the time zone specified by \fIzoneName\fR.
The permissible values, and their interpretation, are discussed under
\fBTIME ZONES\fR.
On subcommands that expect a \fB\-timezone\fR argument, the default
is to use the \fIcurrent time zone\fR.  The current time zone is
determined, in order of preference, by:
.RS
.IP [1]
the environment variable \fBTCL_TZ\fR.
.IP [2]
the environment variable \fBTZ\fR.
.IP [3]
on Windows systems, the time zone settings from the Control Panel.
.RE
.PP
If none of these is present, the C \fBlocaltime\fR and \fBmktime\fR
functions are used to attempt to convert times between local and
Greenwich.  On 32-bit systems, this approach is likely to have bugs,
particularly for times that lie outside the window (approximately the
years 1902 to 2037) that can be represented in a 32-bit integer.
.SH "CLOCK ARITHMETIC"
.PP
The \fBclock add\fR command performs clock arithmetic on a value
(expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC)
given as its first argument.  The remaining arguments (other than the
possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options)
are integers and keywords in alternation, where the keywords are chosen
from \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
\fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR.
.PP
Addition of seconds, minutes and hours is fairly straightforward;
the given time increment (times sixty for minutes, or 3600 for hours)
is simply added to the \fItimeVal\fR given
to the \fBclock add\fR command.  The result is interpreted as
a nominal number of seconds from the Epoch.
.PP
Surprising results
may be obtained when crossing a point at which a leap second is
inserted or removed; the \fBclock add\fR command simply ignores
leap seconds and therefore assumes that times come in sequence,
23:59:58, 23:59:59, 00:00:00.  (This assumption is handled by
the fact that Tcl's model of time reacts to leap seconds by speeding
or slowing the clock by a minuscule amount until Tcl's time
is back in step with the world.
.PP
The fact that adding and subtracting hours is defined in terms of
absolute time means that it will add fixed amounts of time in time zones
that observe summer time (Daylight Saving Time).  For example,
the following code sets the value of \fBx\fR to \fB04:00:00\fR because
the clock has changed in the interval in question.
.PP
.CS
set s [\fBclock scan\fR {2004-10-30 05:00:00} \e
           -format {%Y-%m-%d %H:%M:%S} \e
           -timezone :America/New_York]
set a [\fBclock add\fR $s 24 hours -timezone :America/New_York]
set x [\fBclock format\fR $a \e
           -format {%H:%M:%S} -timezone :America/New_York]
.CE
.PP
Adding and subtracting days and weeks is accomplished by converting
the given time to a calendar day and time of day in the appropriate
time zone and locale.  The requisite number of days (weeks are converted
to days by multiplying by seven) is added to the calendar day, and
the date and time are then converted back to a count of seconds from
the epoch time.  The \fBweekdays\fR keyword is similar to \fBdays\fR,
with the only difference that weekends are skipped.
.PP
Adding and subtracting a given number of days across the point that
the time changes at the start or end of summer time (Daylight Saving Time)
results in the \fIsame local time\fR on the day in question.  For
instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR.
.PP
.CS
set s [\fBclock scan\fR {2004-10-30 05:00:00} \e
           -format {%Y-%m-%d %H:%M:%S} \e
           -timezone :America/New_York]
set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
set x [\fBclock format\fR $a \e
           -format {%H:%M:%S} -timezone :America/New_York]
.CE
.PP
In cases of ambiguity, where the same local time happens twice
on the same day, the earlier time is used.  In cases where the conversion
yields an impossible time (for instance, 02:30 during the Spring
Daylight Saving Time change using US rules), the time is converted
as if the clock had not changed.  Thus, the following code
will set the value of \fBx\fR to \fB03:30:00\fR.
.PP
.CS
set s [\fBclock scan\fR {2004-04-03 02:30:00} \e
           -format {%Y-%m-%d %H:%M:%S} \e
           -timezone :America/New_York]
set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
set x [\fBclock format\fR $a \e
           -format {%H:%M:%S} -timezone :America/New_York]
.CE
.PP
Adding a given number of days or weeks works correctly across the conversion
between the Julian and Gregorian calendars; the omitted days are skipped.
The following code sets \fBz\fR to \fB1752-09-14\fR.
.PP
.CS
set x [\fBclock scan\fR 1752-09-02 -format %Y-%m-%d -locale en_US]
set y [\fBclock add\fR $x 1 day -locale en_US]
set z [\fBclock format\fR $y -format %Y-%m-%d -locale en_US]
.CE
.PP
In the bizarre case that adding the given number of days yields a date
that does not exist because it falls within the dropped days of the
Julian-to-Gregorian conversion, the date is converted as if it was
on the Julian calendar.
.PP
Adding a number of months, or a number of years, is similar; it
converts the given time to a calendar date and time of day.  It then
adds the requisite number of months or years, and reconverts the resulting
date and time of day to an absolute time.
.PP
If the resulting date is impossible because the month has too few days
(for example, when adding 1 month to 31 January), the last day of the
month is substituted.  Thus, adding 1 month to 31 January will result in
28 February in a common year or 29 February in a leap year.
.PP
The rules for handling anomalies relating to summer time and to the
Gregorian calendar are the same when adding/subtracting months and
years as they are when adding/subtracting days and weeks.
.PP
If multiple \fIcount unit\fR pairs are present on the command, they
are evaluated consecutively, from left to right.
.SH "HIGH RESOLUTION TIMERS"
.PP
Most of the subcommands supported by the \fBclock\fR command deal with
times represented as a count of seconds from the epoch time, and this is the
representation that \fBclock seconds\fR returns.  There are three exceptions,
which are all intended for use where higher-resolution times are required.
\fBclock milliseconds\fR returns the count of milliseconds from the
epoch time, and \fBclock microseconds\fR returns the count of microseconds
from the epoch time. In addition, there is a \fBclock clicks\fR command
that returns a platform-dependent high-resolution timer.  Unlike
\fBclock seconds\fR and \fBclock milliseconds\fR, the value
of \fBclock clicks\fR is not guaranteed to be tied to any fixed
epoch; it is simply intended to be the most precise interval timer
available, and is intended only for relative timing studies such as
benchmarks.
.SH "FORMATTING TIMES"
.PP
The \fBclock format\fR command produces times for display to a user
or writing to an external medium.  The command accepts times that are
expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC,
as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR,
\fBfile atime\fR or \fBfile mtime\fR.
.PP
If a \fB\-format\fR option is present, the following argument is
a string that specifies how the date and time are to be formatted.
The string consists
of any number of characters other than the per-cent sign
.PQ \fB%\fR
interspersed with any number of \fIformat groups\fR, which are two-character
sequences beginning with the per-cent sign.  The permissible format groups,
and their interpretation, are described under \fBFORMAT GROUPS\fR.
.PP
If a \fB\-timezone\fR option is present, the following
argument is a string that specifies the time zone in which the date and time
are to be formatted.  As an alternative to
.QW "\fB\-timezone\fR \fI:UTC\fR" ,
the obsolete usage
.QW "\fB\-gmt\fR \fItrue\fR"
may be used.  See
\fBTIME ZONES\fR for the permissible variants for the time zone.
.PP
If a \fB\-locale\fR option is present, the following argument is
a string that specifies the locale in which the time is to be formatted,
in the same format that is used for the \fBmsgcat\fR package.  Note
that the default, if \fB\-locale\fR is not specified, is the root locale
\fB{}\fR rather than the current locale.  The current locale may
be obtained by using \fB\-locale\fR \fBcurrent\fR.
In addition, some platforms support a \fBsystem\fR locale that
reflects the user's current choices.  For instance, on Windows, the
format that the user has selected from dates and times in the Control
Panel can be obtained by using the \fBsystem\fR locale.  On
platforms that do not define a user selection of date and time formats
separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is
synonymous with \fB\-locale\fR \fBcurrent\fR.
.SH "SCANNING TIMES"
.PP
The \fBclock scan\fR command accepts times that are formatted as
strings and converts them to counts of seconds from the epoch time
of 1 January 1970, 00:00 UTC.  It normally takes a \fB\-format\fR
option that is followed by a string describing
the expected format of the input.  (See
\fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR
without such an argument.)  The string consists of any number of
characters other than the per-cent sign
.PQ \fB%\fR "" ,
interspersed with any number of \fIformat groups\fR, which are two-character
sequences beginning with the per-cent sign.  The permissible format groups,
and their interpretation, are described under \fBFORMAT GROUPS\fR.
.PP
If a \fB\-timezone\fR option is present, the following
argument is a string that specifies the time zone in which the date and time
are to be interpreted.  As an alternative to \fB\-timezone\fR \fI:UTC\fR,
the obsolete usage \fB\-gmt\fR \fItrue\fR may be used.  See
\fBTIME ZONES\fR for the permissible variants for the time zone.
.PP
If a \fB\-locale\fR option is present, the following argument is
a string that specifies the locale in which the time is to be interpreted,
in the same format that is used for the \fBmsgcat\fR package.  Note
that the default, if \fB\-locale\fR is not specified, is the root locale
\fB{}\fR rather than the current locale.  The current locale may
be obtained by using \fB\-locale\fR \fBcurrent\fR.
In addition, some platforms support a \fBsystem\fR locale that
reflects the user's current choices.  For instance, on Windows, the
format that the user has selected from dates and times in the Control
Panel can be obtained by using the \fBsystem\fR locale.  On
platforms that do not define a user selection of date and time formats
separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is
synonymous with \fB\-locale\fR \fBcurrent\fR.
.PP
If a \fB\-base\fR option is present, the following argument is
a time (expressed in seconds from the epoch time) that is used as
a \fIbase time\fR for interpreting relative times.  If no
\fB\-base\fR option is present, the base time is the current time.
.PP
Scanning of times in fixed format works by determining three things:
the date, the time of day, and the time zone.  These three are then
combined into a point in time, which is returned as the number of seconds
from the epoch.
.PP
Before scanning begins, the format string is preprocessed
to replace \fB%c\fR, \fB%Ec\fR, \fB%x\fR, \fB%Ex\fR,
\fB%X\fR. \fB%Ex\fR, \fB%r\fR, \fB%R\fR, \fB%T\fR,
\fB%D\fR, \fB%EY\fR and \fB%+\fR format groups with counterparts
that are appropriate to the current locale and contain none of the
above groups.  For instance, \fB%D\fR will (in the \fBen_US\fR locale)
be replaced with \fB%m/%d/%Y\fR.
.PP
The date is determined according to the fields that are present in the
preprocessed format string.  In order of preference:
.IP [1]
If the string contains a \fB%s\fR format group, representing
seconds from the epoch, that group is used to determine the date.
.IP [2]
If the string contains a \fB%J\fR format group, representing
the Julian Day Number, that group is used to determine the date.
.IP [3]
If the string contains a complete set of format groups specifying
century, year, month, and day of month; century, year, and day of year;
or ISO8601 fiscal year, week of year, and day of week; those groups are
combined and used to determine the date.  If more than one complete
set is present, the one at the rightmost position in the string is
used.
.IP [4]
If the string lacks a century but contains a set of format
groups specifying year of century, month and day of month; year of
century and day of year; or two-digit ISO8601 fiscal year, week of year,
and day of week; those groups are
combined and used to determine the date.  If more than one complete
set is present, the one at the rightmost position in the string is
used.  The year is presumed to lie in the range 1938 to 2037 inclusive.
.IP [5]
If the string entirely lacks any specification for the year
(or contains the year only on the locale's alternative calendar)
and contains a set of format groups specifying month and day of month,
day of year, or week of year and day of week, those groups are
combined and used to determine the date.  If more than one complete
set is present, the one at the rightmost position in the string is
used.  The year is determined by interpreting the base time in the given
time zone.
.IP [6]
If the string contains none of the above sets, but has a day
of the month or day of the week, the day of the month or day of the week
are used to determine the date by interpreting the base time in the
given time zone and returning the given day of the current week or month.
(The week runs from Monday to Sunday, ISO8601-fashion.)  If both day
of month and day of week are present, the day of the month takes
priority.
.IP [7]
If none of the above rules results in a usable date, the date
of the base time in the given time zone is used.
.PP
The time is also determined according to the fields that are present in the
preprocessed format string.  In order of preference:
.IP [1]
If the string contains a \fB%s\fR format group, representing
seconds from the epoch, that group determines the time of day.
.IP [2]
If the string contains either an hour on the 24-hour clock
or an hour on the 12-hour clock plus an AM/PM indicator, that hour determines
the hour of the day.  If the string further contains a group specifying
the minute of the hour, that group combines with the hour.  If the string
further contains a group specifying the second of the minute, that group
combines with the hour and minute.
.IP [3]
If the string contains neither a \fB%s\fR format group nor
a group specifying the hour of the day, then midnight (\fB00:00\fR, the start
of the given date) is used.
The time zone is determined by either the \fB\-timezone\fR or \fB\-gmt\fR
options, or by using the current time zone.
.PP
If a format string lacks a \fB%z\fR or \fB%Z\fR format group,
it is possible for the time to be ambiguous because it appears twice
in the same day, once without and once with Daylight Saving Time.
If this situation occurs, the first occurrence of the time is chosen.
(For this reason, it is wise to have the input string contain the
time zone when converting local times.  This caveat does not apply to
UTC times.)
.SH "FORMAT GROUPS"
.PP
The following format groups are recognized by the \fBclock scan\fR and
\fBclock format\fR commands.
.TP
\fB%a\fR
On output, receives an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day
of the week in the given locale.  On input, matches the name of the day
of the week in the given locale (in either abbreviated or full form, or
any unique prefix of either form).
.TP
\fB%A\fR
On output, receives the full name (\fIe.g.,\fR \fBMonday\fR) of the day
of the week in the given locale.  On input, matches the name of the day
of the week in the given locale (in either abbreviated or full form, or
any unique prefix of either form).
.TP
\fB%b\fR
On output, receives an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name
of the month in the given locale.  On input, matches the name of the month
in the given locale (in either abbreviated or full form, or
any unique prefix of either form).
.TP
\fB%B\fR
On output, receives the full name (\fIe.g.,\fR \fBJanuary\fR)
of the month in the given locale.  On input, matches the name of the month
in the given locale (in either abbreviated or full form, or
any unique prefix of either form).
.TP
\fB%c\fR
On output, receives a localized representation of date and time of day;
the localized representation is expected to use the Gregorian calendar.
On input, matches whatever \fB%c\fR produces.
.TP
\fB%C\fR
On output, receives the number of the century in Indo-Arabic numerals.
On input, matches one or two digits, possibly with leading whitespace,
that are expected to be the number of the century.
.TP
\fB%d\fR
On output, produces the number of the day of the month, as two decimal
digits.  On input, matches one or two digits, possibly with leading
whitespace, that are expected to be the number of the day of the month.
.TP
\fB%D\fR
This format group is synonymous with \fB%m/%d/%Y\fR.  It should be
used only in exchanging data within the \fBen_US\fR locale, since
other locales typically do not use this order for the fields of the date.
.TP
\fB%e\fR
On output, produces the number of the day of the month, as one or
two decimal digits (with a leading blank for one-digit dates).
On input, matches one or two digits, possibly with leading
whitespace, that are expected to be the number of the day of the month.
.TP
\fB%Ec\fR
On output, produces a locale-dependent representation of the date and
time of day in the locale's alternative calendar.  On input, matches
whatever \fB%Ec\fR produces.  The locale's alternative calendar need not
be the Gregorian calendar.
.TP
\fB%EC\fR
On output, produces a locale-dependent name of an era in the locale's
alternative calendar.  On input, matches the name of the era or any
unique prefix.
.TP
\fB%EE\fR
On output, produces the string \fBB.C.E.\fR or \fBC.E.\fR, or a
string of the same meaning in the locale, to indicate whether \fB%Y\fR refers
to years before or after Year 1 of the Common Era.  On input, accepts
the string \fBB.C.E.\fR, \fBB.C.\fR, \fBC.E.\fR, \fBA.D.\fR, or the
abbreviation appropriate to the current locale, and uses it to fix
whether \fB%Y\fR refers to years before or after Year 1 of the
Common Era.
.TP
\fB%Ex\fR
On output, produces a locale-dependent representation of the date
in the locale's alternative calendar.  On input, matches
whatever \fB%Ex\fR produces.  The locale's alternative calendar need not
be the Gregorian calendar.
.TP
\fB%EX\fR
On output, produces a locale-dependent representation of the
time of day in the locale's alternative numerals.  On input, matches
whatever \fB%EX\fR produces.
.TP
\fB%Ey\fR
On output, produces a locale-dependent number of the year of the era
in the locale's alternative calendar and numerals.  On input, matches
such a number.
.TP
\fB%EY\fR
On output, produces a representation of the year in the locale's
alternative calendar and numerals.  On input, matches what \fB%EY\fR
produces.  Often synonymous with \fB%EC%Ey\fR.
.TP
\fB%g\fR
On output, produces a two-digit year number suitable for use with
the week-based ISO8601 calendar; that is, the year number corresponds
to the week number produced by \fB%V\fR.  On input, accepts such
a two-digit year number, possibly with leading whitespace.
.TP
\fB%G\fR
On output, produces a four-digit year number suitable for use with
the week-based ISO8601 calendar; that is, the year number corresponds
to the week number produced by \fB%V\fR.  On input, accepts such
a four-digit year number, possibly with leading whitespace.
.TP
\fB%h\fR
This format group is synonymous with \fB%b\fR.
.TP
\fB%H\fR
On output, produces a two-digit number giving the hour of the day
(00-23) on a 24-hour clock.  On input, accepts such a number.
.TP
\fB%I\fR
On output, produces a two-digit number giving the hour of the day
(12-11) on a 12-hour clock.  On input, accepts such a number.
.TP
\fB%j\fR
On output, produces a three-digit number giving the day of the year
(001-366).  On input, accepts such a number.
.TP
\fB%J\fR
On output, produces a string of digits giving the Julian Day Number.
On input, accepts a string of digits and interprets it as a Julian Day Number.
The Julian Day Number is a count of the number of calendar days
that have elapsed since 1 January, 4713 BCE of the proleptic
Julian calendar.  The epoch time of 1 January 1970 corresponds
to Julian Day Number 2440588.
.TP
\fB%k\fR
On output, produces a one- or two-digit number giving the hour of the day
(0-23) on a 24-hour clock.  On input, accepts such a number.
.TP
\fB%l\fR
On output, produces a one- or two-digit number giving the hour of the day
(12-11) on a 12-hour clock.  On input, accepts such a number.
.TP
\fB%m\fR
On output, produces the number of the month (01-12) with exactly two
digits.  On input, accepts two digits and interprets them as the number
of the month.
.TP
\fB%M\fR
On output, produces the number of the minute of the hour (00-59)
with exactly two digits.  On input, accepts two digits and interprets them
as the number of the minute of the hour.
.TP
\fB%N\fR
On output, produces the number of the month (1-12) with one or two digits,
and a leading blank for one-digit dates.
On input, accepts one or two digits, possibly with leading whitespace,
and interprets them as the number of the month.
.TP
\fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR
All of these format groups are synonymous with their counterparts
without the
.QW \fBO\fR ,
except that the string is produced and parsed in the
locale-dependent alternative numerals.
.TP
\fB%p\fR
On output, produces an indicator for the part of the day, \fBAM\fR
or \fBPM\fR, appropriate to the given locale.  If the script of the
given locale supports multiple letterforms, lowercase is preferred.
On input, matches the representation \fBAM\fR or \fBPM\fR in
the given locale, in either case.
.TP
\fB%P\fR
On output, produces an indicator for the part of the day, \fBam\fR
or \fBpm\fR, appropriate to the given locale.  If the script of the
given locale supports multiple letterforms, uppercase is preferred.
On input, matches the representation \fBAM\fR or \fBPM\fR in
the given locale, in either case.
.TP
\fB%Q\fR
This format group is reserved for internal use within the Tcl library.
.TP
\fB%r\fR
On output, produces a locale-dependent time of day representation on a
12-hour clock. On input, accepts whatever \fB%r\fR produces.
.TP
\fB%R\fR
On output, the time in 24-hour notation (%H:%M). For a version
including the seconds, see \fB%T\fR below. On input, accepts whatever
\fB%R\fR produces.
.TP
\fB%s\fR
On output, simply formats the \fItimeVal\fR argument as a decimal
integer and inserts it into the output string.  On input, accepts
a decimal integer and uses is as the time value without any further
processing. Since \fB%s\fR uniquely determines a point in time, it
overrides all other input formats.
.TP
\fB%S\fR
On output, produces a two-digit number of the second of the minute
(00-59). On input, accepts two digits and uses them as the second of the
minute.
.TP
\fB%t\fR
On output, produces a TAB character. On input, matches a TAB character.
.TP
\fB%T\fR
Synonymous with \fB%H:%M:%S\fR.
.TP
\fB%u\fR
On output, produces the number of the day of the week
(\fB1\fR\(->Monday, \fB7\fR\(->Sunday). On input, accepts a single digit and
interprets it as the day of the week. Sunday may be either \fB0\fR or
\fB7\fR.
.TP
\fB%U\fR
On output, produces the ordinal number of the week of the year
(00-53). The first Sunday of the year is the first day of week 01. On
input accepts two digits which are otherwise ignored. This format
group is never used in determining an input date.  This interpretation
of the week of the year was once common in US banking but is now
largely obsolete.  See \fB%V\fR for the ISO8601 week number.
.TP
\fB%V\fR
On output, produces the number of the ISO8601 week as a two digit
number (01-53). Week 01 is the week containing January 4; or the first
week of the year containing at least 4 days; or the week containing
the first Thursday of the year (the three statements are
equivalent). Each week begins on a Monday. On input, accepts the
ISO8601 week number.
.TP
\fB%w\fR
On output, produces the ordinal number of the day of the week
(Sunday==0; Saturday==6).  On input, accepts a single digit and
interprets it as the day of the week; Sunday may be represented as
either 0 or 7.  Note that \fB%w\fR is not the ISO8601 weekday number,
which is produced and accepted by \fB%u\fR.
.TP
\fB%W\fR
On output, produces a week number (00-53) within the year; week 01
begins on the first Monday of the year. On input, accepts two digits,
which are otherwise ignored. This format group is never used in
determining an input date.  It is not the ISO8601 week number; that
week is produced and accepted by \fB%V\fR.
.TP
\fB%x\fR
On output, produces the date in a locale-dependent representation. On
input, accepts whatever \fB%x\fR produces and is used to determine
calendar date.
.TP
\fB%X\fR
On output, produces the time of day in a locale-dependent
representation. On input, accepts whatever \fB%X\fR produces and is used
to determine time of day.
.TP
\fB%y\fR
On output, produces the two-digit year of the century. On input,
accepts two digits, and is used to determine calendar date. The
date is presumed to lie between 1938 and 2037 inclusive. Note
that \fB%y\fR does not yield a year appropriate for use with the ISO8601
week number \fB%V\fR; programs should use \fB%g\fR for that purpose.
.TP
\fB%Y\fR
On output, produces the four-digit calendar year. On input,
accepts four digits and may be used to determine calendar date. Note
that \fB%Y\fR does not yield a year appropriate for use with the ISO8601
week number \fB%V\fR; programs should use \fB%G\fR for that purpose.
.TP
\fB%z\fR
On output, produces the current time zone, expressed in hours and
minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a
time zone specifier (see \fBTIME ZONES\fR below) that will be used to
determine the time zone.
.TP
\fB%Z\fR
On output, produces the current time zone's name, possibly
translated to the given locale. On input, accepts a time zone
specifier (see \fBTIME ZONES\fR below) that will be used to determine the
time zone. This option should, in general, be used on input only when
parsing RFC822 dates. Other uses are fraught with ambiguity; for
instance, the string \fBBST\fR may represent British Summer Time or
Brazilian Standard Time. It is recommended that date/time strings for
use by computers use numeric time zones instead.
.TP
\fB%%\fR
On output, produces a literal
.QW \fB%\fR
character. On input, matches a literal
.QW \fB%\fR
character.
.TP
\fB%+\fR
Synonymous with
.QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" .
.SH "TIME ZONES"
.PP
When the \fBclock\fR command is processing a local time, it has several
possible sources for the time zone to use.  In order of preference, they
are:
.IP [1]
A time zone specified inside a string being parsed and matched by a \fB%z\fR
or \fB%Z\fR format group.
.IP [2]
A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR
command (or, equivalently, by \fB\-gmt\fR \fB1\fR).
.IP [3]
A time zone specified in an environment variable \fBTCL_TZ\fR.
.IP [4]
A time zone specified in an environment variable \fBTZ\fR.
.IP [5]
The local time zone from the Control Panel on Windows systems.
.IP [6]
The C library's idea of the local time zone, as defined by the
\fBmktime\fR and \fBlocaltime\fR functions.
.PP
In case [1] \fIonly,\fR the string is tested to see if it is one
of the strings:
.PP
.CS
 gmt     ut      utc     bst     wet     wat     at
 nft     nst     ndt     ast     adt     est     edt
 cst     cdt     mst     mdt     pst     pdt     yst
 ydt     hst     hdt     cat     ahst    nt      idlw
 cet     cest    met     mewt    mest    swt     sst
 eet     eest    bt      it      zp4     zp5     ist
 zp6     wast    wadt    jt      cct     jst     cast
 cadt    east    eadt    gst     nzt     nzst    nzdt
 idle
.CE
.PP
If it is a string in the above list, it designates a known
time zone, and is interpreted as such.
.PP
For time zones in case [1] that do not match any of the above strings,
and always for cases [2]-[6], the following rules apply.
.PP
If the time zone begins with a colon, it is one of a
standardized list of names like \fB:America/New_York\fR
that give the rules for various locales.  A complete list
of the location names is too lengthy to be listed here.
On most Tcl installations, the definitions of the locations
are to be found in named files in the directory
.QW "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR" .
On some Unix systems, these files are omitted, and the definitions are
instead obtained from system files in
.QW "\fI/usr/share/zoneinfo\fR" ,
.QW "\fI/usr/share/lib/zoneinfo\fR"
or
.QW "\fI/usr/local/etc/zoneinfo\fR" .
As a special case, the name \fB:localtime\fR refers to
the local time zone as defined by the C library.
.PP
A time zone string consisting of a plus or minus sign followed by
four or six decimal digits is interpreted as an offset in
hours, minutes, and seconds (if six digits are present) from
UTC.  The plus sign denotes a sign east of Greenwich;
the minus sign one west of Greenwich.
.PP
A time zone string conforming to the Posix specification of the \fBTZ\fR
environment variable will be recognized.  The specification
may be found at
\fIhttp://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR.
.PP
If the Posix time zone string contains a DST (Daylight Savings Time)
part, but doesn't contain a rule stating when DST starts or ends,
then default rules are used. For Timezones with an offset between 0
and +12, the current European/Russian rules are used, otherwise the
current US rules are used. In Europe (offset +0 to +2) the switch
to summertime is done each last Sunday in March at 1:00 GMT, and
the switch back is each last Sunday in October at 2:00 GMT. In
Russia (offset +3 to +12), the switch dates are the same, only
the switch to summertime is at 2:00 local time, and the switch
back is at 3:00 local time in all time zones. The US switch to
summertime takes place each second Sunday in March at 2:00 local
time, and the switch back is each first Sunday in November at
3:00 local time. These default rules mean that in all European,
Russian and US (or compatible) time zones, DST calculations will
be correct for dates in 2007 and later, unless in the future the
rules change again.
.PP
Any other time zone string is processed by prefixing a colon and attempting
to use it as a location name, as above.
.SH "LOCALIZATION"
.PP
Developers wishing to localize the date and time formatting and parsing
are referred to \fIhttp://tip.tcl.tk/173\fR for a
specification.
.SH "FREE FORM SCAN"
.PP
If the \fBclock scan\fR command is invoked without a \fB\-format\fR
option, then it requests a \fIfree-form scan.\fR  \fI
This form of scan is deprecated.\fR  The reason for the deprecation
is that there are too many ambiguities. (Does the string
.QW 2000
represent a year, a time of day, or a quantity?)  No set of rules
for interpreting free-form dates and times has been found to
give unsurprising results in all cases.
.PP
If free-form scan is used, only the \fB\-base\fR and \fB\-gmt\fR
options are accepted.  The \fB\-timezone\fR and \fB\-locale\fR
options will result in an error if \fB\-format\fR is not supplied.
.PP
For the benefit of users who need to understand legacy code that
uses free-form scan, the documentation for how free-form scan
interprets a string is included here:
.PP
If only a time is
specified, the current date is assumed.  If the \fIinputString\fR
does not contain a
time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR
argument is true, in which case the clock value is calculated assuming
that the specified time is relative to Greenwich Mean Time.
\fB\-gmt\fR, if specified, affects only the computed time value; it does not
impact the interpretation of \fB\-base\fR.
.PP
If the \fB\-base\fR flag is specified, the next argument should contain
an integer clock value.  Only the date in this value is used, not the
time.  This is useful for determining the time on a specific day or
doing other date-relative conversions.
.PP
The \fIinputString\fR argument consists of zero or more specifications of the
following form:
.TP
\fItime\fR
A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR
or \fBhhmm ?meridian? ?zone?\fR
If no meridian is specified, \fBhh\fR is interpreted on
a 24-hour clock.
.TP
\fIdate\fR
A specific month and day with optional year.  The
acceptable formats are
.QW "\fBmm/dd\fR?\fB/yy\fR?" ,
.QW "\fBmonthname dd\fR?\fB, yy\fR?" ,
.QW "\fBday, dd monthname \fR?\fByy\fR?" ,
.QW "\fBdd monthname yy\fR" ,
.QW "?\fBCC\fR?\fByymmdd\fR" ,
and
.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" .
The default year is the current year.  If the year is less
than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
as 1969-1999.  Not all platforms can represent the years 38-70, so
an error may result if these years are used.
.TP
\fIISO 8601 point-in-time\fR
An ISO 8601 point-in-time specification, such as
.QW \fICCyymmdd\fBT\fIhhmmss\fR,
where \fBT\fR is the literal
.QW T ,
.QW "\fICCyymmdd hhmmss\fR" ,
or
.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR .
Note that only these three formats are accepted.
The command does \fInot\fR accept the full range of point-in-time
specifications specified in ISO8601.  Other formats can be recognized by
giving an explicit \fB\-format\fR option to the \fBclock scan\fR command.
.TP
\fIrelative time\fR
A specification relative to the current time.  The format is \fBnumber
unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR,
\fBmonth\fR, \fBweek\fR, \fBday\fR,
\fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR).  The
unit can be specified as a singular or plural, as in \fB3 weeks\fR.
These modifiers may also be specified:
\fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR,
\fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR.
.PP
The actual date is calculated according to the following steps.
.PP
First, any absolute date and/or time is processed and converted.
Using that time as the base, day-of-week specifications are added.
Next, relative specifications are used.  If a date or day is
specified, and no absolute or relative time is given, midnight is
used.  Finally, a correction is applied so that the correct hour of
the day is produced after allowing for daylight savings time
differences and the correct date is given when going from the end
of a long month to a short month.
.SH "SEE ALSO"
msgcat(n)
.SH KEYWORDS
clock, date, time
.SH "COPYRIGHT"
Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\" Local Variables:
'\" mode: nroff
'\" End: