diff options
Diffstat (limited to 'doc/clock.n')
| -rw-r--r-- | doc/clock.n | 77 |
1 files changed, 21 insertions, 56 deletions
diff --git a/doc/clock.n b/doc/clock.n index 8708029..0460a54 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 @@ -16,13 +16,13 @@ package require \fBTcl 8.5\fR .sp \fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? .sp -\fBclock microseconds\fR +\fBclock microseconds\fR .sp -\fBclock milliseconds\fR +\fBclock milliseconds\fR .sp \fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? .sp -\fBclock seconds\fR +\fBclock seconds\fR .sp .BE .SH "DESCRIPTION" @@ -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 \fB\-milliseconds\fR, then the command +If the \fI\-option\fR argument is \fI\-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 +If the \fI\-option\fR argument is \fI\-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. @@ -58,10 +58,10 @@ 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 +\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 +\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...? @@ -69,7 +69,7 @@ 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 +\fBclock seconds\fR Returns the current time as an integer number of seconds. .SS "PARAMETERS" .TP @@ -111,12 +111,11 @@ 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 +%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 +On \fBclock scan\fR, the lack of a \fI\-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,14 +160,12 @@ 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 @@ -198,7 +195,6 @@ 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 @@ -219,7 +215,6 @@ 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 @@ -235,7 +230,6 @@ 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 @@ -248,7 +242,6 @@ set x [\fBclock format\fR $a \e 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] @@ -277,7 +270,6 @@ 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, @@ -292,7 +284,6 @@ 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, @@ -331,7 +322,6 @@ 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 @@ -454,7 +444,6 @@ 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 @@ -525,7 +514,7 @@ 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 +whether \fB%Y\fR refers to years before or after Year 1 of the Common Era. .TP \fB%Ex\fR @@ -637,8 +626,9 @@ 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, produces a locale-dependent time of day representation on a -24-hour clock. On input, accepts whatever \fB%R\fR produces. +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 @@ -683,8 +673,8 @@ ISO8601 week number. \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, +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 @@ -744,7 +734,6 @@ 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: @@ -764,9 +753,8 @@ The local time zone from the Control Panel on Windows systems. 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 +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 @@ -778,11 +766,10 @@ of the strings: 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, +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 @@ -812,32 +799,13 @@ 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 @@ -904,11 +872,11 @@ 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 \fB\-format\fR option to the \fBclock scan\fR command. +giving an explicit \fI\-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, +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. @@ -932,6 +900,3 @@ msgcat(n) clock, date, time .SH "COPYRIGHT" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. -'\" Local Variables: -'\" mode: nroff -'\" End: |