Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/tcl8.5.2/doc/clock.n @ 25

Last change on this file since 25 was 25, checked in by landauf, 16 years ago

added tcl to libs

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