1<HTML><HEAD><TITLE>Tcl Built-In Commands - clock manual page</TITLE></HEAD><BODY> 2<DL> 3<DD><A HREF="clock.htm#M2" NAME="L135">NAME</A> 4<DL><DD>clock - Obtain and manipulate time</DL> 5<DD><A HREF="clock.htm#M3" NAME="L136">SYNOPSIS</A> 6<DL> 7<DD><B>clock </B><I>option</I> ?<I>arg arg ...</I>? 8</DL> 9<DD><A HREF="clock.htm#M4" NAME="L137">DESCRIPTION</A> 10<DL> 11<DD><A HREF="clock.htm#M5" NAME="L138"><B>clock clicks</B> ?<B>-milliseconds</B>?</A> 12<DD><A HREF="clock.htm#M6" NAME="L139"><B>clock format </B><I>clockValue</I> ?<B>-format </B><I>string</I>? ?<B>-gmt </B><I>boolean</I>?</A> 13<DL> 14<DD><A HREF="clock.htm#M7" NAME="L140"><B>%%</B></A> 15<DD><A HREF="clock.htm#M8" NAME="L141"><B>%a</B></A> 16<DD><A HREF="clock.htm#M9" NAME="L142"><B>%A</B></A> 17<DD><A HREF="clock.htm#M10" NAME="L143"><B>%b</B></A> 18<DD><A HREF="clock.htm#M11" NAME="L144"><B>%B</B></A> 19<DD><A HREF="clock.htm#M12" NAME="L145"><B>%c</B></A> 20<DD><A HREF="clock.htm#M13" NAME="L146"><B>%C</B></A> 21<DD><A HREF="clock.htm#M14" NAME="L147"><B>%d</B></A> 22<DD><A HREF="clock.htm#M15" NAME="L148"><B>%D</B></A> 23<DD><A HREF="clock.htm#M16" NAME="L149"><B>%e</B></A> 24<DD><A HREF="clock.htm#M17" NAME="L150"><B>%g</B></A> 25<DD><A HREF="clock.htm#M18" NAME="L151"><B>%G</B></A> 26<DD><A HREF="clock.htm#M19" NAME="L152"><B>%h</B></A> 27<DD><A HREF="clock.htm#M20" NAME="L153"><B>%H</B></A> 28<DD><A HREF="clock.htm#M21" NAME="L154"><B>%I</B></A> 29<DD><A HREF="clock.htm#M22" NAME="L155"><B>%j</B></A> 30<DD><A HREF="clock.htm#M23" NAME="L156"><B>%k</B></A> 31<DD><A HREF="clock.htm#M24" NAME="L157"><B>%l</B></A> 32<DD><A HREF="clock.htm#M25" NAME="L158"><B>%m</B></A> 33<DD><A HREF="clock.htm#M26" NAME="L159"><B>%M</B></A> 34<DD><A HREF="clock.htm#M27" NAME="L160"><B>%n</B></A> 35<DD><A HREF="clock.htm#M28" NAME="L161"><B>%p</B></A> 36<DD><A HREF="clock.htm#M29" NAME="L162"><B>%r</B></A> 37<DD><A HREF="clock.htm#M30" NAME="L163"><B>%R</B></A> 38<DD><A HREF="clock.htm#M31" NAME="L164"><B>%s</B></A> 39<DD><A HREF="clock.htm#M32" NAME="L165"><B>%S</B></A> 40<DD><A HREF="clock.htm#M33" NAME="L166"><B>%t</B></A> 41<DD><A HREF="clock.htm#M34" NAME="L167"><B>%T</B></A> 42<DD><A HREF="clock.htm#M35" NAME="L168"><B>%u</B></A> 43<DD><A HREF="clock.htm#M36" NAME="L169"><B>%U</B></A> 44<DD><A HREF="clock.htm#M37" NAME="L170"><B>%V</B></A> 45<DD><A HREF="clock.htm#M38" NAME="L171"><B>%w</B></A> 46<DD><A HREF="clock.htm#M39" NAME="L172"><B>%W</B></A> 47<DD><A HREF="clock.htm#M40" NAME="L173"><B>%x</B></A> 48<DD><A HREF="clock.htm#M41" NAME="L174"><B>%X</B></A> 49<DD><A HREF="clock.htm#M42" NAME="L175"><B>%y</B></A> 50<DD><A HREF="clock.htm#M43" NAME="L176"><B>%Y</B></A> 51<DD><A HREF="clock.htm#M44" NAME="L177"><B>%Z</B></A> 52</DL> 53<DD><A HREF="clock.htm#M45" NAME="L178"><B>clock scan </B><I>dateString</I> ?<B>-base </B><I>clockVal</I>? ?<B>-gmt </B><I>boolean</I>?</A> 54<DL> 55<DD><A HREF="clock.htm#M46" NAME="L179"><I>time</I></A> 56<DD><A HREF="clock.htm#M47" NAME="L180"><I>date</I></A> 57<DD><A HREF="clock.htm#M48" NAME="L181"><I>ISO 8601 point-in-time</I></A> 58<DD><A HREF="clock.htm#M49" NAME="L182"><I>relative time</I></A> 59</DL> 60<DD><A HREF="clock.htm#M50" NAME="L183"><B>clock seconds</B></A> 61</DL> 62<DD><A HREF="clock.htm#M51" NAME="L184">SEE ALSO</A> 63<DD><A HREF="clock.htm#M52" NAME="L185">KEYWORDS</A> 64</DL><HR> 65<H3><A NAME="M2">NAME</A></H3> 66clock - Obtain and manipulate time 67<H3><A NAME="M3">SYNOPSIS</A></H3> 68<B>clock </B><I>option</I> ?<I>arg arg ...</I>?<BR> 69<H3><A NAME="M4">DESCRIPTION</A></H3> 70This command performs one of several operations that may obtain 71or manipulate strings or values that represent some notion of 72time. The <I>option</I> argument determines what action is carried 73out by the command. The legal <I>options</I> (which may be 74abbreviated) are: 75<P> 76<DL> 77<DT><A NAME="M5"><B>clock clicks</B> ?<B>-milliseconds</B>?</A><DD> 78Return a high-resolution time value as a system-dependent integer 79value. The unit of the value is system-dependent but should be the 80highest resolution clock available on the system such as a CPU cycle 81counter. If <B>-milliseconds</B> is specified, then the value is 82guaranteed to be of millisecond granularity. 83This value should only be used for the relative measurement 84of elapsed time. 85<P><DT><A NAME="M6"><B>clock format </B><I>clockValue</I> ?<B>-format </B><I>string</I>? ?<B>-gmt </B><I>boolean</I>?</A><DD> 86Converts an integer time value, typically returned by 87<B>clock seconds</B>, <B>clock scan</B>, or the <B>atime</B> or <B>mtime</B> 88options of the <B><A HREF="../TclCmd/file.htm">file</A></B> command, to human-readable 89form. If the <B>-format</B> argument is present the next argument is a 90string that describes how the date and time are to be formatted. 91Field descriptors consist of a <B>%</B> followed by a field 92descriptor character. All other characters are copied into the result. 93Valid field descriptors are: 94<P> 95<DL> 96<DT><A NAME="M7"><B>%%</B></A><DD> 97Insert a %. 98<P><DT><A NAME="M8"><B>%a</B></A><DD> 99Abbreviated weekday name (Mon, Tue, etc.). 100<P><DT><A NAME="M9"><B>%A</B></A><DD> 101Full weekday name (Monday, Tuesday, etc.). 102<P><DT><A NAME="M10"><B>%b</B></A><DD> 103Abbreviated month name (Jan, Feb, etc.). 104<P><DT><A NAME="M11"><B>%B</B></A><DD> 105Full month name. 106<P><DT><A NAME="M12"><B>%c</B></A><DD> 107Locale specific date and time. The format for date and time 108in the default "C" locale on Unix/Mac is "%a %b %d %H:%M:%S %Y". 109On Windows, this value is the locale specific long date and time, as 110specified in the Regional Options control panel settings. 111<P><DT><A NAME="M13"><B>%C</B></A><DD> 112First two digits of the four-digit year (19 or 20). 113<P><DT><A NAME="M14"><B>%d</B></A><DD> 114Day of month (01 - 31). 115<P><DT><A NAME="M15"><B>%D</B></A><DD> 116Date as %m/%d/%y. 117<P><DT><A NAME="M16"><B>%e</B></A><DD> 118Day of month (1 - 31), no leading zeros. 119<P><DT><A NAME="M17"><B>%g</B></A><DD> 120The ISO8601 year number corresponding to the ISO8601 week (%V), expressed 121as a two-digit year-of-the-century, with leading zero if necessary. 122<P><DT><A NAME="M18"><B>%G</B></A><DD> 123The ISO8601 year number corresponding to the ISO8601 week (%V), expressed 124as a four-digit number. 125<P><DT><A NAME="M19"><B>%h</B></A><DD> 126Abbreviated month name. 127<P><DT><A NAME="M20"><B>%H</B></A><DD> 128Hour in 24-hour format (00 - 23). 129<P><DT><A NAME="M21"><B>%I</B></A><DD> 130Hour in 12-hour format (01 - 12). 131<P><DT><A NAME="M22"><B>%j</B></A><DD> 132Day of year (001 - 366). 133<P><DT><A NAME="M23"><B>%k</B></A><DD> 134Hour in 24-hour format, without leading zeros (0 - 23). 135<P><DT><A NAME="M24"><B>%l</B></A><DD> 136Hour in 12-hour format, without leading zeros (1 - 12). 137<P><DT><A NAME="M25"><B>%m</B></A><DD> 138Month number (01 - 12). 139<P><DT><A NAME="M26"><B>%M</B></A><DD> 140Minute (00 - 59). 141<P><DT><A NAME="M27"><B>%n</B></A><DD> 142Insert a newline. 143<P><DT><A NAME="M28"><B>%p</B></A><DD> 144AM/PM indicator. 145<P><DT><A NAME="M29"><B>%r</B></A><DD> 146Time in a locale-specific "meridian" format. The "meridian" 147format in the default "C" locale is "%I:%M:%S %p". 148<P><DT><A NAME="M30"><B>%R</B></A><DD> 149Time as %H:%M. 150<P><DT><A NAME="M31"><B>%s</B></A><DD> 151Count of seconds since the epoch, expressed as a decimal integer. 152<P><DT><A NAME="M32"><B>%S</B></A><DD> 153Seconds (00 - 59). 154<P><DT><A NAME="M33"><B>%t</B></A><DD> 155Insert a tab. 156<P><DT><A NAME="M34"><B>%T</B></A><DD> 157Time as %H:%M:%S. 158<P><DT><A NAME="M35"><B>%u</B></A><DD> 159Weekday number (Monday = 1, Sunday = 7). 160<P><DT><A NAME="M36"><B>%U</B></A><DD> 161Week of year (00 - 52), Sunday is the first day of the week. 162<P><DT><A NAME="M37"><B>%V</B></A><DD> 163Week of year according to ISO-8601 rules. Week 1 of a given 164year is the week containing 4 January. 165<P><DT><A NAME="M38"><B>%w</B></A><DD> 166Weekday number (Sunday = 0, Saturday = 6). 167<P><DT><A NAME="M39"><B>%W</B></A><DD> 168Week of year (00 - 52), Monday is the first day of the week. 169<P><DT><A NAME="M40"><B>%x</B></A><DD> 170Locale specific date format. The format for a date in the default "C" 171locale for Unix/Mac is "%m/%d/%y". 172On Windows, this value is the locale specific short date format, as 173specified in the Regional Options control panel settings. 174<P><DT><A NAME="M41"><B>%X</B></A><DD> 175Locale specific 24-hour time format. The format for a 17624-hour time in the default "C" locale for Unix/Mac is "%H:%M:%S". 177On Windows, this value is the locale specific time format, as 178specified in the Regional Options control panel settings. 179<P><DT><A NAME="M42"><B>%y</B></A><DD> 180Year without century (00 - 99). 181<P><DT><A NAME="M43"><B>%Y</B></A><DD> 182Year with century (e.g. 1990) 183<P><DT><A NAME="M44"><B>%Z</B></A><DD> 184Time zone name. 185<P></DL> 186<P>If the <B>-format</B> argument is not specified, the format string 187<B>"%a %b %d %H:%M:%S %Z %Y"</B> is used. If the <B>-gmt</B> argument 188is present the next argument must be a boolean which if true specifies 189that the time will be formatted as Greenwich Mean Time. If false 190then the local timezone will be used as defined by the operating 191environment. 192<P><DT><A NAME="M45"><B>clock scan </B><I>dateString</I> ?<B>-base </B><I>clockVal</I>? ?<B>-gmt </B><I>boolean</I>?</A><DD> 193Convert <I>dateString</I> to an integer clock value (see <B>clock seconds</B>). 194This command can parse and convert virtually any standard date and/or time 195string, which can include standard time zone mnemonics. If only a time is 196specified, the current date is assumed. If the string does not contain a 197time zone mnemonic, the local time zone is assumed, unless the <B>-gmt</B> 198argument is true, in which case the clock value is calculated assuming 199that the specified time is relative to Greenwich Mean Time. 200<B>-gmt</B>, if specified, affects only the computed time value; it does not 201impact the interpretation of <B>-base</B>. 202<P> 203If the <B>-base</B> flag is specified, the next argument should contain 204an integer clock value. Only the date in this value is used, not the 205time. This is useful for determining the time on a specific day or 206doing other date-relative conversions. 207<P> 208The <I>dateString</I> consists of zero or more specifications of the 209following form: 210<P> 211<DL> 212<DT><A NAME="M46"><I>time</I></A><DD> 213A time of day, which is of the form: <I>hh</I>?<I>:mm</I>?<I>:ss</I>?? 214?<I>meridian</I>? ?<I>zone</I>? or <I>hhmm </I>?<I>meridian</I>? 215?<I>zone</I>?. If no meridian is specified, <I>hh</I> is interpreted on 216a 24-hour clock. 217<P><DT><A NAME="M47"><I>date</I></A><DD> 218A specific month and day with optional year. The 219acceptable formats are <I>mm/dd</I>?<I>/yy</I>?, <I>monthname dd</I> 220?, <I>yy</I>?, <I>dd monthname </I>?<I>yy</I>?, <I>day, dd monthname 221yy</I>, <I>?CC?yymmdd</I>, <I>?CC?yy-mm-dd</I>, <I>dd-monthname-?CC?yy</I>. 222The default year is the current year. If the year is less 223than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 224as 1969-1999. Not all platforms can represent the years 38-70, so 225an error may result if these years are used. 226<P><DT><A NAME="M48"><I>ISO 8601 point-in-time</I></A><DD> 227An ISO 8601 point-in-time specification, such as <I>CCyymmddThhmmss</I>, where 228T is the literal T, <I>CCyymmdd hhmmss</I>, or 229<I>CCyymmddThh:mm:ss</I>. Note that only these three formats are accepted. 230The command does <I>not</I> accept the full range of point-in-time 231specifications specified in ISO8601. Other formats can be recognized by 232using commands such as <B><A HREF="../TclCmd/regexp.htm">regexp</A></B> to extract their fields and reorganize 233them into a form accepted by the <B>clock scan</B> command. 234<P><DT><A NAME="M49"><I>relative time</I></A><DD> 235A specification relative to the current time. The format is <I>number 236unit</I> acceptable units are <B>year</B>, <B>fortnight</B>, <B>month</B>, <B>week</B>, <B>day</B>, 237<B>hour</B>, <B>minute</B> (or <B>min</B>), and <B>second</B> (or <B>sec</B>). The 238unit can be specified as a singular or plural, as in <B>3 weeks</B>. 239These modifiers may also be specified: 240<B>tomorrow</B>, <B>yesterday</B>, <B>today</B>, <B>now</B>, 241<B>last</B>, <B>this</B>, <B>next</B>, <B>ago</B>. 242<P></DL> 243<P> 244<DL><DD> 245The actual date is calculated according to the following steps. 246First, any absolute date and/or time is processed and converted. 247Using that time as the base, day-of-week specifications are added. 248Next, relative specifications are used. If a date or day is 249specified, and no absolute or relative time is given, midnight is 250used. Finally, a correction is applied so that the correct hour of 251the day is produced after allowing for daylight savings time 252differences and the correct date is given when going from the end 253of a long month to a short month. 254<P> 255Daylight savings time correction is applied only when the relative time 256is specified in units of days or more, ie, days, weeks, fortnights, months or 257years. This means that when crossing the daylight savings time boundary, 258different results will be given for <B>clock scan "1 day"</B> and 259<B>clock scan "24 hours"</B>: 260<PRE>% <B>clock scan</B> "1 day" -base [<B>clock scan</B> 1999-10-31] 261941443200 262% <B>clock scan</B> "24 hours" -base [<B>clock scan</B> 1999-10-31] 263941439600</PRE> 264</DL> 265<P><DT><A NAME="M50"><B>clock seconds</B></A><DD> 266Return the current date and time as a system-dependent integer value. The 267unit of the value is seconds, allowing it to be used for relative time 268calculations. The value is usually defined as total elapsed time from 269an ``epoch''. You shouldn't assume the value of the epoch. 270 271<P></DL> 272<H3><A NAME="M51">SEE ALSO</A></H3> 273<B>date</B>, <B><A HREF="../TclCmd/time.htm">time</A></B> 274<H3><A NAME="M52">KEYWORDS</A></H3> 275<A href="../Keywords/C.htm#clock">clock</A>, <A href="../Keywords/D.htm#date">date</A>, <A href="../Keywords/T.htm#time">time</A> 276<HR><PRE> 277<A HREF="../copyright.htm">Copyright</A> © 1992-1995 Karl Lehenbauer and Mark Diekhans. 278<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Sun Microsystems, Inc. 279<A HREF="../copyright.htm">Copyright</A> © 1998-1999 Scriptics Corporation 280<A HREF="../copyright.htm">Copyright</A> © 2002 ActiveState Corporation 281<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE> 282</BODY></HTML> 283