Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

clock (1t)

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

clock(1t)                    Tcl Built-In Commands                   clock(1t)



______________________________________________________________________________

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 manipu-
       late values that represent times.  The command supports several subcom-
       mands 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 pre-
              ferred 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  pre-
              ferred 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 pro-
              grams.  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 pro-
              duces 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 min-
              utes 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  conjunc-
              tion  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  com-
              mand  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  con-
              sists  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 Grego-
              rian calendar) is to be done in the locale identified by locale-
              Name.   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 -time-
              zone 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  Con-
                     trol 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 abso-
       lute  time  means  that it will add fixed amounts of time in time zones
       that observe summer time (Daylight Saving Time).  For example, the fol-
       lowing  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  Day-
       light  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 con-
       version 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  con-
       verts  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 eval-
       uated 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  microsec-
       onds  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 guar-
       anteed to be tied to any fixed epoch; it is simply intended to  be  the
       most  precise  interval timer available, and is intended only for rela-
       tive timing studies such as benchmarks.

FORMATTING TIMES
       The clock format command produces times for display to a user or  writ-
       ing  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 con-
       sists 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  for-
       matted.   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  permis-
       sible format groups, and their interpretation, are described under FOR-
       MAT 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 Con-
       trol 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 sec-
       onds 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  con-
       tain  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 specify-
              ing 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 right-
              most 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 posi-
              tion  in  the  string is used.  The year is determined by inter-
              preting 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 specify-
              ing 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 Gre-
              gorian 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  num-
              ber.

       %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  num-
              ber.

       %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 Janu-
              ary 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  counter-
              parts  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 representa-
              tion on a 12-hour clock. On input, accepts whatever %r produces.

       %R     On output, the time in 24-hour notation (%H:%M). For  a  version
              including  the seconds, see %T below. 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->Mon-
              day, 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 state-
              ments  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 num-
              ber, 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  representa-
              tion.  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 repre-
              sentation. 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 pos-
       sible 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  loca-
       tions   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.open-
       group.org/onlinepubs/009695399/basedefs/xbd_chap08.html.

       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 Euro-
       pean, 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.

       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 rea-
       son 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 month-
              name ?yy?", "dd  monthname  yy",  "?CC?yymmdd",  and  "dd-month-
              name-?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  "CCyymmddThh-
              mmss," where T is the literal "T", "CCyymmdd hhmmss", or "CCyym-
              mddThh: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  rec-
              ognized  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 mod-
              ifiers 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.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | runtime/tcl-8    |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+
SEE ALSO
       msgcat(n)

KEYWORDS
       clock, date, time

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



NOTES
       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  http://prdownloads.sourceforge.net/tcl/tcl-
       core8.6.7-src.tar.gz

       Further information about this software can be found on the open source
       community website at https://www.tcl.tk/.



Tcl                                   8.5                            clock(1t)