diff options
Diffstat (limited to 'doc/clock.n')
| -rw-r--r-- | doc/clock.n | 36 |
1 files changed, 31 insertions, 5 deletions
diff --git a/doc/clock.n b/doc/clock.n index 60042be..42dca80 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -2,8 +2,8 @@ '\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. '\" -.so man.macros .TH "clock" n 8.5 Tcl "Tcl Built-In Commands" +.so man.macros .BS .SH NAME clock \- Obtain and manipulate dates and times @@ -42,12 +42,12 @@ 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 \fI\-milliseconds\fR, then the command +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 \fI\-microseconds\fR, then the command +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. @@ -116,7 +116,7 @@ On \fBclock format\fR, the default format is %a %b %d %H:%M:%S %z %Y .CE .PP -On \fBclock scan\fR, the lack of a \fI\-format\fR option indicates that a +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 @@ -161,12 +161,14 @@ 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 @@ -275,6 +277,7 @@ years as they are when adding/subtracting days and weeks. 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, @@ -289,6 +292,7 @@ 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, @@ -327,6 +331,7 @@ 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 @@ -449,6 +454,7 @@ If this situation occurs, the first occurrence of the time is chosen. 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 @@ -738,6 +744,7 @@ character. 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: @@ -805,13 +812,32 @@ 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 @@ -878,7 +904,7 @@ or 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 \fI\-format\fR option to the \fBclock scan\fR command. +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 |