raw/mann/clock.n

   1 '\"
   2 '\" Copyright (c) 1992-1995 Karl Lehenbauer and Mark Diekhans.
   3 '\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1998-1999 Scriptics Corporation
   5 '\"
   6 '\" This documentation is derived from the time and date facilities of
   7 '\" TclX, by Mark Diekhans and Karl Lehenbauer.
   8 '\"
   9 '\" See the file "license.terms" for information on usage and redistribution
  10 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  11 '\"
  12 '\" RCS: @(#) $Id: clock.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
  13 '\"
  14 '\" The definitions below are for supplemental macros used in Tcl/Tk
  15 '\" manual entries.
  16 '\"
  17 '\" .AP type name in/out ?indent?
  18 '\"     Start paragraph describing an argument to a library procedure.
  19 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  20 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  21 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  22 '\"     needed;  use .AS below instead)
  23 '\"
  24 '\" .AS ?type? ?name?
  25 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  26 '\"     name are examples of largest possible arguments that will be passed
  27 '\"     to .AP later.  If args are omitted, default tab stops are used.
  28 '\"
  29 '\" .BS
  30 '\"     Start box enclosure.  From here until next .BE, everything will be
  31 '\"     enclosed in one large box.
  32 '\"
  33 '\" .BE
  34 '\"     End of box enclosure.
  35 '\"
  36 '\" .CS
  37 '\"     Begin code excerpt.
  38 '\"
  39 '\" .CE
  40 '\"     End code excerpt.
  41 '\"
  42 '\" .VS ?version? ?br?
  43 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  44 '\"     of man pages.  The first argument is ignored and used for recording
  45 '\"     the version when the .VS was added, so that the sidebars can be
  46 '\"     found and removed when they reach a certain age.  If another argument
  47 '\"     is present, then a line break is forced before starting the sidebar.
  48 '\"
  49 '\" .VE
  50 '\"     End of vertical sidebar.
  51 '\"
  52 '\" .DS
  53 '\"     Begin an indented unfilled display.
  54 '\"
  55 '\" .DE
  56 '\"     End of indented unfilled display.
  57 '\"
  58 '\" .SO
  59 '\"     Start of list of standard options for a Tk widget.  The
  60 '\"     options follow on successive lines, in four columns separated
  61 '\"     by tabs.
  62 '\"
  63 '\" .SE
  64 '\"     End of list of standard options for a Tk widget.
  65 '\"
  66 '\" .OP cmdName dbName dbClass
  67 '\"     Start of description of a specific option.  cmdName gives the
  68 '\"     option's name as specified in the class command, dbName gives
  69 '\"     the option's name in the option database, and dbClass gives
  70 '\"     the option's class in the option database.
  71 '\"
  72 '\" .UL arg1 arg2
  73 '\"     Print arg1 underlined, then print arg2 normally.
  74 '\"
  75 '\" RCS: @(#) $Id: clock.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
  76 '\"
  77 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 '\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1  \\fI\\$2\\fP    (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 '\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 '\"     # BS - start boxed text
 114 '\"     # ^y = starting y location
 115 '\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 '\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 '\"     # VS - start vertical sidebar
 146 '\"     # ^Y = starting y location
 147 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 '\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 '\"     # Special macro to handle page bottom:  finish off current
 170 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 '\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 '\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 '\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 '\"     # SO - start of list of standard options
 211 .de SO
 212 .SH "STANDARD OPTIONS"
 213 .LP
 214 .nf
 215 .ta 5.5c 11c
 216 .ft B
 217 ..
 218 '\"     # SE - end of list of standard options
 219 .de SE
 220 .fi
 221 .ft R
 222 .LP
 223 See the \\fBoptions\\fR manual entry for details on the standard options.
 224 ..
 225 '\"     # OP - start of full description for a single option
 226 .de OP
 227 .LP
 228 .nf
 229 .ta 4c
 230 Command-Line Name:      \\fB\\$1\\fR
 231 Database Name:  \\fB\\$2\\fR
 232 Database Class: \\fB\\$3\\fR
 233 .fi
 234 .IP
 235 ..
 236 '\"     # CS - begin code excerpt
 237 .de CS
 238 .RS
 239 .nf
 240 .ta .25i .5i .75i 1i
 241 ..
 242 '\"     # CE - end code excerpt
 243 .de CE
 244 .fi
 245 .RE
 246 ..
 247 .de UL
 248 \\$1\l'|0\(ul'\\$2
 249 ..
 250 .TH clock n 8.3 Tcl "Tcl Built-In Commands"
 251 .BS
 252 '\" Note:  do not modify the .SH NAME line immediately below!
 253 .SH NAME
 254 clock \- Obtain and manipulate time
 255 .SH SYNOPSIS
 256 \fBclock \fIoption\fR ?\fIarg arg ...\fR?
 257 .BE
 258
 259 .SH DESCRIPTION
 260 .PP
 261 This command performs one of several operations that may obtain
 262 or manipulate strings or values that represent some notion of
 263 time.  The \fIoption\fR argument determines what action is carried
 264 out by the command.  The legal \fIoptions\fR (which may be
 265 abbreviated) are:
 266 .TP
 267 .VS 8.3
 268 \fBclock clicks\fR ?\fB\-milliseconds\fR?
 269 Return a high-resolution time value as a system-dependent integer
 270 value.  The unit of the value is system-dependent but should be the
 271 highest resolution clock available on the system such as a CPU cycle
 272 counter. If \fB\-milliseconds\fR is specified, then the value is
 273 guaranteed to be of millisecond granularity.
 274 This value should only be used for the relative measurement
 275 of elapsed time.
 276 .VE 8.3
 277 .TP
 278 \fBclock format \fIclockValue\fR ?\fB\-format \fIstring\fR? ?\fB\-gmt \fIboolean\fR?
 279 Converts an integer time value, typically returned by
 280 \fBclock seconds\fR, \fBclock scan\fR, or the \fBatime\fR, \fBmtime\fR,
 281 or \fBctime\fR options of the \fBfile\fR command, to human-readable
 282 form.  If the \fB\-format\fR argument is present the next argument is a
 283 string that describes how the date and time are to be formatted.
 284 Field descriptors consist of a \fB%\fR followed by a field
 285 descriptor character.  All other characters are copied into the result.
 286 Valid field descriptors are:
 287 .RS
 288 .IP \fB%%\fR
 289 Insert a %.
 290 .IP \fB%a\fR
 291 Abbreviated weekday name (Mon, Tue, etc.).
 292 .IP \fB%A\fR
 293 Full weekday name (Monday, Tuesday, etc.).
 294 .IP \fB%b\fR
 295 Abbreviated month name (Jan, Feb, etc.).
 296 .IP \fB%B\fR
 297 Full month name.
 298 .IP \fB%c\fR
 299 Locale specific date and time.
 300 .IP \fB%d\fR
 301 Day of month (01 - 31).
 302 .IP \fB%H\fR
 303 Hour in 24-hour format (00 - 23).
 304 .IP \fB%I\fR
 305 Hour in 12-hour format (00 - 12).
 306 .IP \fB%j\fR
 307 Day of year (001 - 366).
 308 .IP \fB%m\fR
 309 Month number (01 - 12).
 310 .IP \fB%M\fR
 311 Minute (00 - 59).
 312 .IP \fB%p\fR
 313 AM/PM indicator.
 314 .IP \fB%S\fR
 315 Seconds (00 - 59).
 316 .IP \fB%U\fR
 317 Week of year (00 - 52), Sunday is the first day of the week.
 318 .IP \fB%w\fR
 319 Weekday number (Sunday = 0).
 320 .IP \fB%W\fR
 321 Week of year (00 - 52), Monday is the first day of the week.
 322 .IP \fB%x\fR
 323 Locale specific date format.
 324 .IP \fB%X\fR
 325 Locale specific time format.
 326 .IP \fB%y\fR
 327 Year without century (00 - 99).
 328 .IP \fB%Y\fR
 329 Year with century (e.g. 1990)
 330 .IP \fB%Z\fR
 331 Time zone name.
 332 .RE
 333 .sp
 334 .RS
 335 In addition, the following field descriptors may be supported on some
 336 systems (e.g. Unix but not Windows):
 337 .IP \fB%D\fR
 338 Date as %m/%d/%y.
 339 .IP \fB%e\fR
 340 Day of month (1 - 31), no leading zeros.
 341 .IP \fB%h\fR
 342 Abbreviated month name.
 343 .IP \fB%n\fR
 344 Insert a newline.
 345 .IP \fB%r\fR
 346 Time as %I:%M:%S %p.
 347 .IP \fB%R\fR
 348 Time as %H:%M.
 349 .IP \fB%t\fR
 350 Insert a tab.
 351 .IP \fB%T\fR
 352 Time as %H:%M:%S.
 353 .RE
 354 .sp
 355 .RS
 356 If the \fB\-format\fR argument is not specified, the format string
 357 "\fB%a %b %d %H:%M:%S %Z %Y\fR" is used.  If the \fB\-gmt\fR argument
 358 is present the next argument must be a boolean which if true specifies
 359 that the time will be formatted as Greenwich Mean Time. If false
 360 then the local timezone will be used as defined by the operating
 361 environment.
 362 .RE
 363 .TP
 364 \fBclock scan \fIdateString\fR ?\fB\-base \fIclockVal\fR? ?\fB\-gmt \fIboolean\fR?
 365 Convert \fIdateString\fR to an integer clock value (see \fBclock seconds\fR).
 366 This command can parse and convert virtually any standard date and/or time
 367 string, which can include standard time zone mnemonics.  If only a time is
 368 specified, the current date is assumed.  If the string does not contain a
 369 time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR
 370 argument is true, in which case the clock value is calculated assuming
 371 that the specified time is relative to Greenwich Mean Time.
 372 \fB-gmt\fR, if specified, affects only the computed time value; it does not
 373 impact the interpretation of \fB-base\fR.
 374 .sp
 375 If the \fB\-base\fR flag is specified, the next argument should contain
 376 an integer clock value.  Only the date in this value is used, not the
 377 time.  This is useful for determining the time on a specific day or
 378 doing other date-relative conversions.
 379 .sp
 380 The \fIdateString\fR consists of zero or more specifications of the
 381 following form:
 382 .RS
 383 .TP
 384 \fItime\fR
 385 A time of day, which is of the form: \fIhh\fR?\fI:mm\fR?\fI:ss\fR??
 386 ?\fImeridian\fR? ?\fIzone\fR? or \fIhhmm \fR?\fImeridian\fR?
 387 ?\fIzone\fR?. If no meridian is specified, \fIhh\fR is interpreted on
 388 a 24-hour clock.
 389 .TP
 390 \fIdate\fR
 391 A specific month and day with optional year.  The
 392 acceptable formats are \fImm/dd\fR?\fI/yy\fR?, \fImonthname dd\fR
 393 ?, \fIyy\fR?, \fIdd monthname \fR?\fIyy\fR?, \fIday, dd monthname
 394 yy\fR, \fI?CC?yymmdd\fR, \fI?CC?yy-mm-dd\fR, \fIdd-monthname-?CC?yy\fR.
 395 The default year is the current year.  If the year is less
 396 .VS
 397 than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
 398 as 1969-1999.  Not all platforms can represent the years 38-70, so
 399 an error may result if these years are used.
 400 .VE
 401 .TP
 402 \fIISO 8601 point-in-time\fR
 403 An ISO 8601 point-in-time specification, such as \fICCyymmddThhmmss\fR, where
 404 T is the literal T, \fICCyymmdd hhmmss\fR, or
 405 \fICCyymmddThh:mm:ss\fR.
 406 .TP
 407 \fIrelative time\fR
 408 A specification relative to the current time.  The format is \fInumber
 409 unit\fR acceptable units are \fByear\fR, \fBfortnight\fR, \fBmonth\fR, \fBweek\fR, \fBday\fR,
 410 \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR).  The
 411 unit can be specified as a singular or plural, as in \fB3 weeks\fR.
 412 These modifiers may also be specified:
 413 \fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR,
 414 \fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR.
 415 .RE
 416 .sp
 417 .RS
 418 The actual date is calculated according to the following steps.
 419 First, any absolute date and/or time is processed and converted.
 420 Using that time as the base, day-of-week specifications are added.
 421 Next, relative specifications are used.  If a date or day is
 422 specified, and no absolute or relative time is given, midnight is
 423 used.  Finally, a correction is applied so that the correct hour of
 424 the day is produced after allowing for daylight savings time
 425 differences and the correct date is given when going from the end
 426 of a long month to a short month.
 427 .sp
 428 Daylight savings time correction is applied only when the relative time
 429 is specified in units of days or more, ie, days, weeks, fortnights, months or
 430 years.  This means that when crossing the daylight savings time boundary,
 431 different results will be given for \fBclock scan "1 day"\fR and
 432 \fBclock scan "24 hours"\fR:
 433 .CS
 434 .ta 6c
 435 \fB% clock scan "1 day" -base [clock scan 1999-10-31]
 436 941443200
 437 % clock scan "24 hours" -base [clock scan 1999-10-31]
 438 941439600\fR
 439 .CE
 440 .RE
 441 .TP
 442 \fBclock seconds\fR
 443 Return the current date and time as a system-dependent integer value.  The
 444 unit of the value is seconds, allowing it to be used for relative time
 445 calculations.  The value is usually defined as total elapsed time from
 446 an ``epoch''.  You shouldn't assume the value of the epoch.
 447
 448 .SH KEYWORDS
 449 clock, date, time