LinuxReviws.org --get your your Linux knowledge
> Linux Reviews > Manual Pages (man) >

clock

Determine processor time


  1. clock.3.man
  2. clock.8.man
  3. clock.9.man


1. clock.3.man

Manpage of CLOCK

CLOCK

Section: Linux Programmer's Manual (3)
Updated: 2008-08-28
Index Return to Main Contents
 

NAME

clock - Determine processor time  

SYNOPSIS

#include <time.h>

clock_t clock(void);
 

DESCRIPTION

The clock() function returns an approximation of processor time used by the program.  

RETURN VALUE

The value returned is the CPU time used so far as a clock_t; to get the number of seconds used, divide by CLOCKS_PER_SEC. If the processor time used is not available or its value cannot be represented, the function returns the value (clock_t) -1.  

CONFORMING TO

C89, C99, POSIX.1-2001. POSIX requires that CLOCKS_PER_SEC equals 1000000 independent of the actual resolution.  

NOTES

The C standard allows for arbitrary values at the start of the program; subtract the value returned from a call to clock() at the start of the program to get maximum portability.

Note that the time can wrap around. On a 32-bit system where CLOCKS_PER_SEC equals 1000000 this function will return the same value approximately every 72 minutes.

On several other implementations, the value returned by clock() also includes the times of any children whose status has been collected via wait(2) (or another wait-type call). Linux does not include the times of waited-for children in the value returned by clock(). The times(2) function, which explicitly returns (separate) information about the caller and its children, may be preferable.  

SEE ALSO

clock_gettime(2), getrusage(2), times(2)  

COLOPHON

This page is part of release 3.32 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.


 

Index

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
CONFORMING TO
NOTES
SEE ALSO
COLOPHON

This document was created by man2html using the manual pages.
Time: 17:30:32 GMT, October 23, 2013

2. clock.8.man

Manpage of HWCLOCK

HWCLOCK

Section: Maintenance Commands (8)
Updated: 06 August 2008
Index Return to Main Contents
 

NAME

hwclock - query and set the hardware clock (RTC)  

SYNOPSIS

hwclock [functions] [options]

 

DESCRIPTION

hwclock is a tool for accessing the Hardware Clock. You can display the current time, set the Hardware Clock to a specified time, set the Hardware Clock to the System Time, and set the System Time from the Hardware Clock.

You can also run hwclock periodically to insert or remove time from the Hardware Clock to compensate for systematic drift (where the clock consistently gains or loses time at a certain rate if left to run).

 

FUNCTIONS

You need exactly one of the following options to tell hwclock what function to perform:

-r, --show
Read the Hardware Clock and print the time on Standard Output. The time shown is always in local time, even if you keep your Hardware Clock in Coordinated Universal Time. See the --utc option.

--set
Set the Hardware Clock to the time given by the --date option.
-s, --hctosys
Set the System Time from the Hardware Clock.

Also set the kernel's timezone value to the local timezone as indicated by the TZ environment variable and/or /usr/share/zoneinfo, as tzset(3) would interpret them. The obsolete tz_dsttime field of the kernel's timezone value is set to DST_NONE. (For details on what this field used to mean, see settimeofday(2).)

This is a good option to use in one of the system startup scripts.

-w, --systohc
Set the Hardware Clock to the current System Time.
--systz
Reset the System Time based on the current timezone.

Also set the kernel's timezone value to the local timezone as indicated by the TZ environment variable and/or /usr/share/zoneinfo, as tzset(3) would interpret them. The obsolete tz_dsttime field of the kernel's timezone value is set to DST_NONE. (For details on what this field used to mean, see settimeofday(2).)

This is an alternate option to --hctosys that does not read the hardware clock, and may be used in system startup scripts for recent 2.6 kernels where you know the System Time contains the Hardware Clock time.

--adjust
Add or subtract time from the Hardware Clock to account for systematic drift since the last time the clock was set or adjusted. See discussion below.
--getepoch
Print the kernel's Hardware Clock epoch value to standard output. This is the number of years into AD to which a zero year value in the Hardware Clock refers. For example, if you are using the convention that the year counter in your Hardware Clock contains the number of full years since 1952, then the kernel's Hardware Counter epoch value must be 1952.

This epoch value is used whenever hwclock reads or sets the Hardware Clock.

--setepoch
Set the kernel's Hardware Clock epoch value to the value specified by the --epoch option. See the --getepoch option for details.
-v, --version
Print the version of hwclock on Standard Output.
--date=date_string
You need this option if you specify the --set option. Otherwise, it is ignored. This specifies the time to which to set the Hardware Clock. The value of this option is an argument to the date(1) program. For example,

hwclock --set --date=9/22/96 16:45:05

The argument is in local time, even if you keep your Hardware Clock in Coordinated Universal time. See the --utc option.

--epoch=year
Specifies the year which is the beginning of the Hardware Clock's epoch. I.e. the number of years into AD to which a zero value in the Hardware Clock's year counter refers. It is used together with the --setepoch option to set the kernel's idea of the epoch of the Hardware Clock, or otherwise to specify the epoch for use with direct ISA access.

For example, on a Digital Unix machine:

hwclock --setepoch --epoch=1952

--predict
Predict what the RTC will read at time given by the --date option based on the adjtime file. This is useful for example if you need to set an RTC wakeup time to distant future and want to account for the RTC drift.

 

OPTIONS

The following options apply to most functions.

-u, --utc
--localtime
Indicates that the Hardware Clock is kept in Coordinated Universal Time or local time, respectively. It is your choice whether to keep your clock in UTC or local time, but nothing in the clock tells which you've chosen. So this option is how you give that information to hwclock.

If you specify the wrong one of these options (or specify neither and take a wrong default), both setting and querying of the Hardware Clock will be messed up.

If you specify neither --utc nor --localtime , the default is whichever was specified the last time hwclock was used to set the clock (i.e. hwclock was successfully run with the --set, --systohc, or --adjust options), as recorded in the adjtime file. If the adjtime file doesn't exist, the default is local time.

--noadjfile
disables the facilities provided by /etc/adjtime. hwclock will not read nor write to that file with this option. Either --utc or --localtime must be specified when using this option.

--adjfile=filename
overrides the default /etc/adjtime.

-f, --rtc=filename
overrides the default /dev file name, which is /dev/rtc on many platforms but may be /dev/rtc0, /dev/rtc1, and so on.

--directisa
is meaningful only on an ISA machine or an Alpha (which implements enough of ISA to be, roughly speaking, an ISA machine for hwclock's purposes). For other machines, it has no effect. This option tells hwclock to use explicit I/O instructions to access the Hardware Clock. Without this option, hwclock will try to use the /dev/rtc device (which it assumes to be driven by the rtc device driver). If it is unable to open the device (for read), it will use the explicit I/O instructions anyway.

The rtc device driver was new in Linux Release 2.

--badyear
Indicates that the Hardware Clock is incapable of storing years outside the range 1994-1999. There is a problem in some BIOSes (almost all Award BIOSes made between 4/26/94 and 5/31/95) wherein they are unable to deal with years after 1999. If one attempts to set the year-of-century value to something less than 94 (or 95 in some cases), the value that actually gets set is 94 (or 95). Thus, if you have one of these machines, hwclock cannot set the year after 1999 and cannot use the value of the clock as the true time in the normal way.

To compensate for this (without your getting a BIOS update, which would definitely be preferable), always use --badyear if you have one of these machines. When hwclock knows it's working with a brain-damaged clock, it ignores the year part of the Hardware Clock value and instead tries to guess the year based on the last calibrated date in the adjtime file, by assuming that that date is within the past year. For this to work, you had better do a hwclock --set or hwclock --systohc at least once a year!

Though hwclock ignores the year value when it reads the Hardware Clock, it sets the year value when it sets the clock. It sets it to 1995, 1996, 1997, or 1998, whichever one has the same position in the leap year cycle as the true year. That way, the Hardware Clock inserts leap days where they belong. Again, if you let the Hardware Clock run for more than a year without setting it, this scheme could be defeated and you could end up losing a day.

hwclock warns you that you probably need --badyear whenever it finds your Hardware Clock set to 1994 or 1995.

--srm
This option is equivalent to --epoch=1900 and is used to specify the most common epoch on Alphas with SRM console.
--arc
This option is equivalent to --epoch=1980 and is used to specify the most common epoch on Alphas with ARC console (but Ruffians have epoch 1900).
--jensen
--funky-toy
These two options specify what kind of Alpha machine you have. They are invalid if you don't have an Alpha and are usually unnecessary if you do, because hwclock should be able to determine by itself what it's running on, at least when /proc is mounted. (If you find you need one of these options to make hwclock work, contact the maintainer to see if the program can be improved to detect your system automatically. Output of `hwclock --debug' and `cat /proc/cpuinfo' may be of interest.)

--jensen means you are running on a Jensen model.

--funky-toy means that on your machine, one has to use the UF bit instead of the UIP bit in the Hardware Clock to detect a time transition. "Toy" in the option name refers to the Time Of Year facility of the machine.

--test
Do everything except actually updating the Hardware Clock or anything else. This is useful, especially in conjunction with --debug, in learning about hwclock.
--debug
Display a lot of information about what hwclock is doing internally. Some of its function is complex and this output can help you understand how the program works.

 

NOTES

 

Clocks in a Linux System

There are two main clocks in a Linux system:

The Hardware Clock: This is a clock that runs independently of any control program running in the CPU and even when the machine is powered off.

On an ISA system, this clock is specified as part of the ISA standard. The control program can read or set this clock to a whole second, but the control program can also detect the edges of the 1 second clock ticks, so the clock actually has virtually infinite precision.

This clock is commonly called the hardware clock, the real time clock, the RTC, the BIOS clock, and the CMOS clock. Hardware Clock, in its capitalized form, was coined for use by hwclock because all of the other names are inappropriate to the point of being misleading.

So for example, some non-ISA systems have a few real time clocks with only one of them having its own power domain. A very low power external I2C or SPI clock chip might be used with a backup battery as the hardware clock to initialize a more functional integrated real-time clock which is used for most other purposes.

The System Time: This is the time kept by a clock inside the Linux kernel and driven by a timer interrupt. (On an ISA machine, the timer interrupt is part of the ISA standard). It has meaning only while Linux is running on the machine. The System Time is the number of seconds since 00:00:00 January 1, 1970 UTC (or more succinctly, the number of seconds since 1969). The System Time is not an integer, though. It has virtually infinite precision.

The System Time is the time that matters. The Hardware Clock's basic purpose in a Linux system is to keep time when Linux is not running. You initialize the System Time to the time from the Hardware Clock when Linux starts up, and then never use the Hardware Clock again. Note that in DOS, for which ISA was designed, the Hardware Clock is the only real time clock.

It is important that the System Time not have any discontinuities such as would happen if you used the date(1L) program to set it while the system is running. You can, however, do whatever you want to the Hardware Clock while the system is running, and the next time Linux starts up, it will do so with the adjusted time from the Hardware Clock. You can also use the program adjtimex(8) to smoothly adjust the System Time while the system runs.

A Linux kernel maintains a concept of a local timezone for the system. But don't be misled -- almost nobody cares what timezone the kernel thinks it is in. Instead, programs that care about the timezone (perhaps because they want to display a local time for you) almost always use a more traditional method of determining the timezone: They use the TZ environment variable and/or the /usr/share/zoneinfo directory, as explained in the man page for tzset(3). However, some programs and fringe parts of the Linux kernel such as filesystems use the kernel timezone value. An example is the vfat filesystem. If the kernel timezone value is wrong, the vfat filesystem will report and set the wrong timestamps on files.

hwclock sets the kernel timezone to the value indicated by TZ and/or /usr/share/zoneinfo when you set the System Time using the --hctosys option.

The timezone value actually consists of two parts: 1) a field tz_minuteswest indicating how many minutes local time (not adjusted for DST) lags behind UTC, and 2) a field tz_dsttime indicating the type of Daylight Savings Time (DST) convention that is in effect in the locality at the present time. This second field is not used under Linux and is always zero. (See also settimeofday(2).)

 

How hwclock Accesses the Hardware Clock

hwclock uses many different ways to get and set Hardware Clock values. The most normal way is to do I/O to the device special file /dev/rtc, which is presumed to be driven by the rtc device driver. However, this method is not always available. For one thing, the rtc driver is a relatively recent addition to Linux. Older systems don't have it. Also, though there are versions of the rtc driver that work on DEC Alphas, there appear to be plenty of Alphas on which the rtc driver does not work (a common symptom is hwclock hanging). Moreover, recent Linux systems have more generic support for RTCs, even systems that have more than one, so you might need to override the default by specifying /dev/rtc0 or /dev/rtc1 instead.

On older systems, the method of accessing the Hardware Clock depends on the system hardware.

On an ISA system, hwclock can directly access the "CMOS memory" registers that constitute the clock, by doing I/O to Ports 0x70 and 0x71. It does this with actual I/O instructions and consequently can only do it if running with superuser effective userid. (In the case of a Jensen Alpha, there is no way for hwclock to execute those I/O instructions, and so it uses instead the /dev/port device special file, which provides almost as low-level an interface to the I/O subsystem).

This is a really poor method of accessing the clock, for all the reasons that user space programs are generally not supposed to do direct I/O and disable interrupts. Hwclock provides it because it is the only method available on ISA and Alpha systems which don't have working rtc device drivers available.

On an m68k system, hwclock can access the clock via the console driver, via the device special file /dev/tty1.

hwclock tries to use /dev/rtc. If it is compiled for a kernel that doesn't have that function or it is unable to open /dev/rtc (or the alternative special file you've defined on the command line) hwclock will fall back to another method, if available. On an ISA or Alpha machine, you can force hwclock to use the direct manipulation of the CMOS registers without even trying /dev/rtc by specifying the --directisa option.

 

The Adjust Function

The Hardware Clock is usually not very accurate. However, much of its inaccuracy is completely predictable - it gains or loses the same amount of time every day. This is called systematic drift. hwclock's "adjust" function lets you make systematic corrections to correct the systematic drift.

It works like this: hwclock keeps a file, /etc/adjtime, that keeps some historical information. This is called the adjtime file.

Suppose you start with no adjtime file. You issue a hwclock --set command to set the Hardware Clock to the true current time. Hwclock creates the adjtime file and records in it the current time as the last time the clock was calibrated. 5 days later, the clock has gained 10 seconds, so you issue another hwclock --set command to set it back 10 seconds. Hwclock updates the adjtime file to show the current time as the last time the clock was calibrated, and records 2 seconds per day as the systematic drift rate. 24 hours go by, and then you issue a hwclock --adjust command. Hwclock consults the adjtime file and sees that the clock gains 2 seconds per day when left alone and that it has been left alone for exactly one day. So it subtracts 2 seconds from the Hardware Clock. It then records the current time as the last time the clock was adjusted. Another 24 hours goes by and you issue another hwclock --adjust. Hwclock does the same thing: subtracts 2 seconds and updates the adjtime file with the current time as the last time the clock was adjusted.

Every time you calibrate (set) the clock (using --set or --systohc), hwclock recalculates the systematic drift rate based on how long it has been since the last calibration, how long it has been since the last adjustment, what drift rate was assumed in any intervening adjustments, and the amount by which the clock is presently off.

A small amount of error creeps in any time hwclock sets the clock, so it refrains from making an adjustment that would be less than 1 second. Later on, when you request an adjustment again, the accumulated drift will be more than a second and hwclock will do the adjustment then.

It is good to do a hwclock --adjust just before the hwclock --hctosys at system startup time, and maybe periodically while the system is running via cron.

The adjtime file, while named for its historical purpose of controlling adjustments only, actually contains other information for use by hwclock in remembering information from one invocation to the next.

The format of the adjtime file is, in ASCII:

Line 1: 3 numbers, separated by blanks: 1) systematic drift rate in seconds per day, floating point decimal; 2) Resulting number of seconds since 1969 UTC of most recent adjustment or calibration, decimal integer; 3) zero (for compatibility with clock(8)) as a decimal integer.

Line 2: 1 number: Resulting number of seconds since 1969 UTC of most recent calibration. Zero if there has been no calibration yet or it is known that any previous calibration is moot (for example, because the Hardware Clock has been found, since that calibration, not to contain a valid time). This is a decimal integer.

Line 3: "UTC" or "LOCAL". Tells whether the Hardware Clock is set to Coordinated Universal Time or local time. You can always override this value with options on the hwclock command line.

You can use an adjtime file that was previously used with the clock(8) program with hwclock.

 

Automatic Hardware Clock Synchronization By the Kernel

You should be aware of another way that the Hardware Clock is kept synchronized in some systems. The Linux kernel has a mode wherein it copies the System Time to the Hardware Clock every 11 minutes. This is a good mode to use when you are using something sophisticated like ntp to keep your System Time synchronized. (ntp is a way to keep your System Time synchronized either to a time server somewhere on the network or to a radio clock hooked up to your system. See RFC 1305).

This mode (we'll call it "11 minute mode") is off until something turns it on. The ntp daemon xntpd is one thing that turns it on. You can turn it off by running anything, including hwclock --hctosys, that sets the System Time the old fashioned way.

To see if it is on or off, use the command adjtimex --print and look at the value of "status". If the "64" bit of this number (expressed in binary) equal to 0, 11 minute mode is on. Otherwise, it is off.

If your system runs with 11 minute mode on, don't use hwclock --adjust or hwclock --hctosys. You'll just make a mess. It is acceptable to use a hwclock --hctosys at startup time to get a reasonable System Time until your system is able to set the System Time from the external source and start 11 minute mode.

 

ISA Hardware Clock Century value

There is some sort of standard that defines CMOS memory Byte 50 on an ISA machine as an indicator of what century it is. hwclock does not use or set that byte because there are some machines that don't define the byte that way, and it really isn't necessary anyway, since the year-of-century does a good job of implying which century it is.

If you have a bona fide use for a CMOS century byte, contact the hwclock maintainer; an option may be appropriate.

Note that this section is only relevant when you are using the "direct ISA" method of accessing the Hardware Clock. ACPI provides a standard way to access century values, when they are supported by the hardware.

 

ENVIRONMENT VARIABLES

TZ

 

FILES

/etc/adjtime /usr/share/zoneinfo/ (/usr/lib/zoneinfo on old systems) /dev/rtc /dev/rtc0 /dev/port /dev/tty1 /proc/cpuinfo

 

SEE ALSO

adjtimex(8), date(1), gettimeofday(2), settimeofday(2), crontab(1), tzset(3)

 

AUTHORS

Written by Bryan Henderson, September 1996 (bryanh@giraffe-data.com), based on work done on the clock program by Charles Hedrick, Rob Hooft, and Harald Koenig. See the source code for complete history and credits.

 

AVAILABILITY

The hwclock command is part of the util-linux package and is available from ftp://ftp.kernel.org/pub/linux/utils/util-linux/.


 

Index

NAME
SYNOPSIS
DESCRIPTION
FUNCTIONS
OPTIONS
NOTES
Clocks in a Linux System
How hwclock Accesses the Hardware Clock
The Adjust Function
Automatic Hardware Clock Synchronization By the Kernel
ISA Hardware Clock Century value
ENVIRONMENT VARIABLES
FILES
SEE ALSO
AUTHORS
AVAILABILITY

This document was created by man2html using the manual pages.
Time: 17:30:32 GMT, October 23, 2013

3. clock.9.man

Manpage of clock

clock

Section: Tcl Built-In Commands (n)
Updated: 8.5
Index Return to Main Contents



 

NAME

clock - Obtain and manipulate dates and times  

SYNOPSIS

package require Tcl 8.5

clock add timeVal ?count unit...? ?-option value?

clock clicks ?-option?

clock format timeVal ?-option value...?

clock microseconds

clock milliseconds

clock scan inputString ?-option value...?

clock seconds




 

DESCRIPTION

The clock 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.

clock add timeVal ?count unit...? ?-option value?
Adds a (possibly negative) offset to a time that is expressed as an integer number of seconds. See CLOCK ARITHMETIC for a full description.
clock clicks ?-option?
If no -option 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 HIGH RESOLUTION TIMERS for a full description.

If the -option argument is -milliseconds, then the command is synonymous with clock milliseconds (see below). This usage is obsolete, and clock milliseconds is to be considered the preferred way of obtaining a count of milliseconds.

If the -option argument is -microseconds, then the command is synonymous with clock microseconds (see below). This usage is obsolete, and clock microseconds is to be considered the preferred way of obtaining a count of microseconds.

clock format timeVal ?-option value...?
Formats a time that is expressed as an integer number of seconds into a format intended for consumption by users or external programs. See FORMATTING TIMES for a full description.
clock microseconds
Returns the current time as an integer number of microseconds. See HIGH RESOLUTION TIMERS for a full description.
clock milliseconds
Returns the current time as an integer number of milliseconds. See HIGH RESOLUTION TIMERS for a full description.
clock scan inputString ?-option value...?
Scans a time that is expressed as a character string and produces an integer number of seconds. See SCANNING TIMES for a full description.
clock seconds
Returns the current time as an integer number of seconds.
 

PARAMETERS

count
An integer representing a count of some unit of time. See CLOCK ARITHMETIC for the details.
timeVal
An integer value passed to the clock command that represents an absolute time as a number of seconds from the epoch time 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.
unit
One of the words, seconds, minutes, hours, days, weeks, months, or years, or any unique prefix of such a word. Used in conjunction with count to identify an interval of time, for example, 3 seconds or 1 year.
 

OPTIONS

-base time
Specifies that any relative times present in a clock scan command are to be given relative to time. time must be expressed as a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC.
-format format
Specifies the desired output format for clock format or the expected input format for clock scan. The format string consists of any number of characters other than the per-cent sign (``%'') interspersed with any number of format groups, which are two-character sequences beginning with the per-cent sign. The permissible format groups, and their interpretation, are described under FORMAT GROUPS.

On clock format, the default format is


%a %b %d %H:%M:%S %z %Y

On clock scan, the lack of a -format option indicates that a ``free format scan'' is requested; see FREE FORM SCAN for a description of what happens.

-gmt boolean
If boolean is true, specifies that a time specified to clock add, clock format or clock scan should be processed in UTC. If boolean 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 ``-timezone :UTC'' or any of the equivalent ways to specify it.
-locale 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 localeName. The locale name may be any of the locales acceptable to the msgcat package, or it may be the special name system, which represents the current locale of the process, or the null string, which represents Tcl's default locale.

The effect of locale on scanning and formatting is discussed in the descriptions of the individual format groups under FORMAT GROUPS. The effect of locale on clock arithmetic is discussed under CLOCK ARITHMETIC.

-timezone zoneName
Specifies that clock arithmetic, formatting, and scanning are to be done according to the rules for the time zone specified by zoneName. The permissible values, and their interpretation, are discussed under TIME ZONES. On subcommands that expect a -timezone argument, the default is to use the current time zone. The current time zone is determined, in order of preference, by:
[1]
the environment variable TCL_TZ.
[2]
the environment variable TZ.
[3]
on Windows systems, the time zone settings from the Control Panel.
If none of these is present, the C localtime and mktime 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.
 

CLOCK ARITHMETIC

The clock add 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 -timezone, -locale and -gmt options) are integers and keywords in alternation, where the keywords are chosen from seconds, minutes, hours, days, weeks, months, or years, or any unique prefix of such a word.

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 timeVal given to the clock add command. The result is interpreted as a nominal number of seconds from the Epoch.

Surprising results may be obtained when crossing a point at which a leap second is inserted or removed; the clock add 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.

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 x to 04:00:00 because the clock has changed in the interval in question.


set s [clock scan {2004-10-30 05:00:00} \
           -format {%Y-%m-%d %H:%M:%S} \
           -timezone :America/New_York]
set a [clock add $s 24 hours -timezone :America/New_York]
set x [clock format $a \
           -format {%H:%M:%S} -timezone :America/New_York]

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.

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 same local time on the day in question. For instance, the following code sets the value of x to 05:00:00.


set s [clock scan {2004-10-30 05:00:00} \
           -format {%Y-%m-%d %H:%M:%S} \
           -timezone :America/New_York]
set a [clock add $s 1 day -timezone :America/New_York]
set x [clock format $a \
           -format {%H:%M:%S} -timezone :America/New_York]

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 x to 03:30:00.


set s [clock scan {2004-04-03 02:30:00} \
           -format {%Y-%m-%d %H:%M:%S} \
           -timezone :America/New_York]
set a [clock add $s 1 day -timezone :America/New_York]
set x [clock format $a \
           -format {%H:%M:%S} -timezone :America/New_York]

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 z to 1752-09-14.


set x [clock scan 1752-09-02 -format %Y-%m-%d -locale en_US]
set y [clock add $x 1 day -locale en_US]
set z [clock format $y -format %Y-%m-%d -locale en_US]

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.

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.

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.

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.

If multiple count unit pairs are present on the command, they are evaluated consecutively, from left to right.  

HIGH RESOLUTION TIMERS

Most of the subcommands supported by the clock command deal with times represented as a count of seconds from the epoch time, and this is the representation that clock seconds returns. There are three exceptions, which are all intended for use where higher-resolution times are required. clock milliseconds returns the count of milliseconds from the epoch time, and clock microseconds returns the count of microseconds from the epoch time. In addition, there is a clock clicks command that returns a platform-dependent high-resolution timer. Unlike clock seconds and clock milliseconds, the value of clock clicks 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.  

FORMATTING TIMES

The clock format 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 clock seconds, clock scan, clock add, file atime or file mtime.

If a -format 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 (``%'') interspersed with any number of format groups, which are two-character sequences beginning with the per-cent sign. The permissible format groups, and their interpretation, are described under FORMAT GROUPS.

If a -timezone 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 ``-timezone :UTC'', the obsolete usage ``-gmt true'' may be used. See TIME ZONES for the permissible variants for the time zone.

If a -locale 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 msgcat package. Note that the default, if -locale is not specified, is the root locale {} rather than the current locale. The current locale may be obtained by using -locale current. In addition, some platforms support a system 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 system locale. On platforms that do not define a user selection of date and time formats separate from LC_TIME, -locale system is synonymous with -locale current.  

SCANNING TIMES

The clock scan 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 -format option that is followed by a string describing the expected format of the input. (See FREE FORM SCAN for the effect of clock scan without such an argument.) The string consists of any number of characters other than the per-cent sign (``%''), interspersed with any number of format groups, which are two-character sequences beginning with the per-cent sign. The permissible format groups, and their interpretation, are described under FORMAT GROUPS.

If a -timezone 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 -timezone :UTC, the obsolete usage -gmt true may be used. See TIME ZONES for the permissible variants for the time zone.

If a -locale 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 msgcat package. Note that the default, if -locale is not specified, is the root locale {} rather than the current locale. The current locale may be obtained by using -locale current. In addition, some platforms support a system 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 system locale. On platforms that do not define a user selection of date and time formats separate from LC_TIME, -locale system is synonymous with -locale current.

If a -base option is present, the following argument is a time (expressed in seconds from the epoch time) that is used as a base time for interpreting relative times. If no -base option is present, the base time is the current time.

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.

Before scanning begins, the format string is preprocessed to replace %c, %Ec, %x, %Ex, %X. %Ex, %r, %R, %T, %D, %EY and %+ format groups with counterparts that are appropriate to the current locale and contain none of the above groups. For instance, %D will (in the en_US locale) be replaced with %m/%d/%Y.

The date is determined according to the fields that are present in the preprocessed format string. In order of preference:

[1]
If the string contains a %s format group, representing seconds from the epoch, that group is used to determine the date.
[2]
If the string contains a %J format group, representing the Julian Day Number, that group is used to determine the date.
[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.
[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.
[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.
[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.
[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.

The time is also determined according to the fields that are present in the preprocessed format string. In order of preference:

[1]
If the string contains a %s format group, representing seconds from the epoch, that group determines the time of day.
[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.
[3]
If the string contains neither a %s format group nor a group specifying the hour of the day, then midnight (00:00, the start of the given date) is used. The time zone is determined by either the -timezone or -gmt options, or by using the current time zone.

If a format string lacks a %z or %Z 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.)  

FORMAT GROUPS

The following format groups are recognized by the clock scan and clock format commands.
%a
On output, receives an abbreviation (e.g., Mon) 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).
%A
On output, receives the full name (e.g., Monday) 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).
%b
On output, receives an abbreviation (e.g., Jan) 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).
%B
On output, receives the full name (e.g., January) 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).
%c
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 %c produces.
%C
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.
%d
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.
%D
This format group is synonymous with %m/%d/%Y. It should be used only in exchanging data within the en_US locale, since other locales typically do not use this order for the fields of the date.
%e
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.
%Ec
On output, produces a locale-dependent representation of the date and time of day in the locale's alternative calendar. On input, matches whatever %Ec produces. The locale's alternative calendar need not be the Gregorian calendar.
%EC
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.
%EE
On output, produces the string B.C.E. or C.E., or a string of the same meaning in the locale, to indicate whether %Y refers to years before or after Year 1 of the Common Era. On input, accepts the string B.C.E., B.C., C.E., A.D., or the abbreviation appropriate to the current locale, and uses it to fix whether %Y refers to years before or after Year 1 of the Common Era.
%Ex
On output, produces a locale-dependent representation of the date in the locale's alternative calendar. On input, matches whatever %Ex produces. The locale's alternative calendar need not be the Gregorian calendar.
%EX
On output, produces a locale-dependent representation of the time of day in the locale's alternative numerals. On input, matches whatever %EX produces.
%Ey
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.
%EY
On output, produces a representation of the year in the locale's alternative calendar and numerals. On input, matches what %EY produces. Often synonymous with %EC%Ey.
%g
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 %V. On input, accepts such a two-digit year number, possibly with leading whitespace.
%G
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 %V. On input, accepts such a four-digit year number, possibly with leading whitespace.
%h
This format group is synonymous with %b.
%H
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.
%I
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.
%j
On output, produces a three-digit number giving the day of the year (001-366). On input, accepts such a number.
%J
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.
%k
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.
%l
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.
%m
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.
%M
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.
%N
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.
%Od, %Oe, %OH, %OI, %Ok, %Ol, %Om, %OM, %OS, %Ou, %Ow, %Oy
All of these format groups are synonymous with their counterparts without the ``O'', except that the string is produced and parsed in the locale-dependent alternative numerals.
%p
On output, produces an indicator for the part of the day, AM or PM, appropriate to the given locale. If the script of the given locale supports multiple letterforms, lowercase is preferred. On input, matches the representation AM or PM in the given locale, in either case.
%P
On output, produces an indicator for the part of the day, am or pm, appropriate to the given locale. If the script of the given locale supports multiple letterforms, uppercase is preferred. On input, matches the representation AM or PM in the given locale, in either case.
%Q
This format group is reserved for internal use within the Tcl library.
%r
On output, produces a locale-dependent time of day representation on a 12-hour clock. On input, accepts whatever %r produces.
%R
On output, produces a locale-dependent time of day representation on a 24-hour clock. On input, accepts whatever %R produces.
%s
On output, simply formats the timeVal 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 %s uniquely determines a point in time, it overrides all other input formats.
%S
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.
%t
On output, produces a TAB character. On input, matches a TAB character.
%T
Synonymous with %H:%M:%S.
%u
On output, produces the number of the day of the week (1->Monday, 7->Sunday). On input, accepts a single digit and interprets it as the day of the week. Sunday may be either 0 or 7.
%U
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 %V for the ISO8601 week number.
%V
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.
%w
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 %w is not the ISO8601 weekday number, which is produced and accepted by %u.
%W
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 %V.
%x
On output, produces the date in a locale-dependent representation. On input, accepts whatever %x produces and is used to determine calendar date.
%X
On output, produces the time of day in a locale-dependent representation. On input, accepts whatever %X produces and is used to determine time of day.
%y
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 %y does not yield a year appropriate for use with the ISO8601 week number %V; programs should use %g for that purpose.
%Y
On output, produces the four-digit calendar year. On input, accepts four digits and may be used to determine calendar date. Note that %Y does not yield a year appropriate for use with the ISO8601 week number %V; programs should use %G for that purpose.
%z
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 TIME ZONES below) that will be used to determine the time zone.
%Z
On output, produces the current time zone's name, possibly translated to the given locale. On input, accepts a time zone specifier (see TIME ZONES 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 BST 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.
%%
On output, produces a literal ``%'' character. On input, matches a literal ``%'' character.
%+
Synonymous with ``%a %b %e %H:%M:%S %Z %Y''.
 

TIME ZONES

When the clock command is processing a local time, it has several possible sources for the time zone to use. In order of preference, they are:
[1]
A time zone specified inside a string being parsed and matched by a %z or %Z format group.
[2]
A time zone specified with the -timezone option to the clock command (or, equivalently, by -gmt 1).
[3]
A time zone specified in an environment variable TCL_TZ.
[4]
A time zone specified in an environment variable TZ.
[5]
The local time zone from the Control Panel on Windows systems.
[6]
The C library's idea of the local time zone, as defined by the mktime and localtime functions.

In case [1] only, the string is tested to see if it is one of the strings:


 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

If it is a string in the above list, it designates a known time zone, and is interpreted as such.

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.

If the time zone begins with a colon, it is one of a standardized list of names like :America/New_York 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 ``/no_backup/tools/lib/tcl8.5/clock/tzdata''. On some Unix systems, these files are omitted, and the definitions are instead obtained from system files in ``/usr/share/zoneinfo'', ``/usr/share/lib/zoneinfo'' or ``/usr/local/etc/zoneinfo''. As a special case, the name :localtime refers to the local time zone as defined by the C library.

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.

A time zone string conforming to the Posix specification of the TZ environment variable will be recognized. The specification may be found at http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap.

Any other time zone string is processed by prefixing a colon and attempting to use it as a location name, as above.  

LOCALIZATION

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

FREE FORM SCAN

If the clock scan command is invoked without a -format option, then it requests a free-form scan. This form of scan is deprecated. The reason for the deprecation is that there are too many ambiguities. (Does the string ``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.

If free-form scan is used, only the -base and -gmt options are accepted. The -timezone and -locale options will result in an error if -format is not supplied.

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:

If only a time is specified, the current date is assumed. If the inputString does not contain a time zone mnemonic, the local time zone is assumed, unless the -gmt argument is true, in which case the clock value is calculated assuming that the specified time is relative to Greenwich Mean Time. -gmt, if specified, affects only the computed time value; it does not impact the interpretation of -base.

If the -base 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.

The inputString argument consists of zero or more specifications of the following form:

time
A time of day, which is of the form: hh?:mm?:ss?? ?meridian? ?zone? or hhmm ?meridian? ?zone? If no meridian is specified, hh is interpreted on a 24-hour clock.
date
A specific month and day with optional year. The acceptable formats are ``mm/dd?/yy?'', ``monthname dd?, yy?'', ``day, dd monthname ?yy?'', ``dd monthname yy'', ``?CC?yymmdd'', and ``dd-monthname-?CC?yy''. 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.
ISO 8601 point-in-time
An ISO 8601 point-in-time specification, such as ``CCyymmddThhmmss,'' where T is the literal ``T'', ``CCyymmdd hhmmss'', or ``CCyymmddThh:mm:ss''. Note that only these three formats are accepted. The command does not accept the full range of point-in-time specifications specified in ISO8601. Other formats can be recognized by giving an explicit -format option to the clock scan command.
relative time
A specification relative to the current time. The format is number unit. Acceptable units are year, fortnight, month, week, day, hour, minute (or min), and second (or sec). The unit can be specified as a singular or plural, as in 3 weeks. These modifiers may also be specified: tomorrow, yesterday, today, now, last, this, next, ago.

The actual date is calculated according to the following steps.

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.  

SEE ALSO

msgcat(n)  

KEYWORDS

clock, date, time  

COPYRIGHT

Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.


 

Index

NAME
SYNOPSIS
DESCRIPTION
PARAMETERS
OPTIONS
CLOCK ARITHMETIC
HIGH RESOLUTION TIMERS
FORMATTING TIMES
SCANNING TIMES
FORMAT GROUPS
TIME ZONES
LOCALIZATION
FREE FORM SCAN
SEE ALSO
KEYWORDS
COPYRIGHT

This document was created by man2html using the manual pages.
Time: 17:30:32 GMT, October 23, 2013

ENGLISH - ENGLISH - cs - da - ENGLISH - ENGLISH - ENGLISH - ENGLISH - ja - nl - pl - ro - ENGLISH - zh_CN

Meet new people