Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
clock(n)		     Tcl Built-In Commands		      clock(n)

______________________________________________________________________________

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 ex-
	      pected 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 per-
	      missible 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  de-
	      scription	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 ig-
       nores 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 Ju-
       lian-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  re-
       quired.	 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  sec-
       onds  and  clock	milliseconds, the value	of clock clicks	is not guaran-
       teed 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 ex-
       pressed 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  ob-
       tained  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 in-
       terpreted.  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  de-
       fault,  if  -locale is not specified, is	the root locale	{} rather than
       the current locale.  The	current	locale may be obtained by  using  -lo-
       cale 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  (ex-
       pressed 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 lo-
       cale) 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  Ju-
	      lian 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 in-
	      clusive.

       [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 de-
	      termines	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 ei-
	      ther 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 lo-
       cal 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 nu-
	      merals.  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 lo-
	      cale'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, ac-
	      cepts 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  in-
	      put, 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, ac-
	      cepts such a two-digit year number, possibly with	leading	white-
	      space.

       %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, ac-
	      cepts 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  in-
	      terprets 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 lo-
	      cale, 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 lo-
	      cale, 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  in-
	      teger  and inserts it into the output string.  On	input, accepts
	      a	decimal	integer	and uses is as the time	value without any fur-
	      ther  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 de-
	      termine 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,  ac-
	      cepts  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  am-
	      biguity; for instance, the string	BST may	represent British Sum-
	      mer 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  lo-
       cales.	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  de-
       notes a sign east of Greenwich; the minus sign one west of Greenwich.

       A  time zone string conforming to the Posix specification of the	TZ en-
       vironment variable will be recognized.  The specification may be	 found
       at					  http://www.opengroup.org/on-
       linepubs/009695399/basedefs/xbd_chap08.html.

       Any other time zone string is processed by prefixing a  colon  and  at-
       tempting	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 ac-
       cepted.	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 in-
       putString 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 in-
       teger  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.

SEE ALSO
       msgcat(n)

KEYWORDS
       clock, date, time

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

Tcl				      8.5			      clock(n)

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

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=clock.tcl85&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help