Provided by: tcl8.6-doc_8.6.13+dfsg-2_all bug

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 miniscule 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.)

       If  the  interpretation  of the groups yields an impossible time because a field is out of
       range, enough of that field's unit will be added to or subtracted from the time  to  bring
       it  in  range.  Thus,  if attempting to scan or format day 0 of the month, one day will be
       subtracted from day 1 of the month, yielding the last day of the previous month.

       If the interpretation of the groups yields an impossible time because  a  Daylight  Saving
       Time  change  skips  over  that  time, or an ambiguous time because a Daylight Saving Time
       change skips back so that the clock observes the  given  time  twice,  and  no  time  zone
       specifier (%z or %Z) is present in the format, the time is interpreted as if the clock had
       not changed.

FORMAT GROUPS

       The following format groups are recognized by the clock scan and clock format commands.

       %a     On output, produces 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, produces 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, produces 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, produces 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, produces 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, produces 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,  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→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
       https://pubs.opengroup.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 European, Russian and US (or compatible) time zones,
       DST calculations will be correct for dates in 2007 and later, unless  in  the  future  the
       rules change again.

       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
       https://tip.tcl-lang.org/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”,  “CCyymmddThh:mm:ss”,  or “CCyy-mm-ddThh:mm:ss.”
              Note that only these four 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(3tcl)

KEYWORDS

       clock, date, time

COPYRIGHT

       Copyright © 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.