1mNAME0m
       clock - Obtain and manipulate time

1mSYNOPSIS0m
       1mclock 4m22moption24m ?4marg24m 4marg24m 4m...24m?


1mDESCRIPTION0m
       This  command  performs  one  of  several operations that may obtain or
       manipulate strings or values that represent some notion of  time.   The
       4moption24m  argument  determines what action is carried out by the command.
       The legal 4moptions24m (which may be abbreviated) are:

       1mclock clicks 22m?1m-milliseconds22m?
              Return a high-resolution time value as a system-dependent  inte-
              ger 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.  If 1m-milliseconds 22mis specified, then the
              value is guaranteed to  be  of  millisecond  granularity.   This
              value  should  only  be  used  for  the  relative measurement of
              elapsed time.

       1mclock format 4m22mclockValue24m ?1m-format 4m22mstring24m? ?1m-gmt 4m22mboolean24m?
              Converts an integer time value, typically returned by 1mclock sec-0m
              1monds22m, 1mclock scan22m, or the 1matime 22mor 1mmtime 22moptions of the 1mfile 22mcom-
              mand, to  human-readable  form.   If  the  1m-format  22margument  is
              present  the  next  argument  is a string that describes how the
              date and time are to be formatted.  Field descriptors consist of
              a 1m% 22mfollowed by a field descriptor character.  All other charac-
              ters are copied into the result.  Valid field descriptors are:

              1m%%     22mInsert a %.

              1m%a     22mAbbreviated weekday name (Mon, Tue, etc.).

              1m%A     22mFull weekday name (Monday, Tuesday, etc.).

              1m%b     22mAbbreviated month name (Jan, Feb, etc.).

              1m%B     22mFull month name.

              1m%c     22mLocale specific date and time.  The format for  date  and
                     time  in  the default "C" locale on Unix/Mac is "%a %b %d
                     %H:%M:%S %Y".  On Windows, this value is the locale  spe-
                     cific  long  date  and time, as specified in the Regional
                     Options control panel settings.

              1m%C     22mFirst two digits of the four-digit year (19 or 20).

              1m%d     22mDay of month (01 - 31).

              1m%D     22mDate as %m/%d/%y.

              1m%e     22mDay of month (1 - 31), no leading zeros.

              1m%g     22mThe ISO8601 year number corresponding to the ISO8601 week
                     (%V),  expressed as a two-digit year-of-the-century, with
                     leading zero if necessary.

              1m%G     22mThe ISO8601 year number corresponding to the ISO8601 week
                     (%V), expressed as a four-digit number.

              1m%h     22mAbbreviated month name.

              1m%H     22mHour in 24-hour format (00 - 23).

              1m%I     22mHour in 12-hour format (01 - 12).

              1m%j     22mDay of year (001 - 366).

              1m%k     22mHour in 24-hour format, without leading zeros (0 - 23).

              1m%l     22mHour in 12-hour format, without leading zeros (1 - 12).

              1m%m     22mMonth number (01 - 12).

              1m%M     22mMinute (00 - 59).

              1m%n     22mInsert a newline.

              1m%p     22mAM/PM indicator.

              1m%r     22mTime in a locale-specific "meridian" format.  The "merid-
                     ian" format in the default "C" locale is "%I:%M:%S %p".

              1m%R     22mTime as %H:%M.

              1m%s     22mCount of seconds since the epoch, expressed as a  decimal
                     integer.

              1m%S     22mSeconds (00 - 59).

              1m%t     22mInsert a tab.

              1m%T     22mTime as %H:%M:%S.

              1m%u     22mWeekday number (Monday = 1, Sunday = 7).

              1m%U     22mWeek  of  year  (00 - 52), Sunday is the first day of the
                     week.

              1m%V     22mWeek of year according to ISO-8601 rules.  Week  1  of  a
                     given year is the week containing 4 January.

              1m%w     22mWeekday number (Sunday = 0, Saturday = 6).

              1m%W     22mWeek  of  year  (00 - 52), Monday is the first day of the
                     week.

              1m%x     22mLocale specific date format.  The format for  a  date  in
                     the  default  "C"  locale for Unix/Mac is "%m/%d/%y".  On
                     Windows, this value is the  locale  specific  short  date
                     format,  as  specified  in  the  Regional Options control
                     panel settings.

              1m%X     22mLocale specific 24-hour time format.  The  format  for  a
                     24-hour  time  in  the default "C" locale for Unix/Mac is
                     "%H:%M:%S".  On Windows, this value is  the  locale  spe-
                     cific  time  format, as specified in the Regional Options
                     control panel settings.

              1m%y     22mYear without century (00 - 99).

              1m%Y     22mYear with century (e.g. 1990)

              1m%Z     22mTime zone name.

              If the 1m-format 22margument is not specified, the format string  1m"%a0m
              1m%b  %d %H:%M:%S %Z %Y" 22mis used.  If the 1m-gmt 22margument is present
              the next argument must be a boolean which if true specifies that
              the time will be formatted as Greenwich Mean Time. If false then
              the local timezone will be used  as  defined  by  the  operating
              environment.

       1mclock scan 4m22mdateString24m ?1m-base 4m22mclockVal24m? ?1m-gmt 4m22mboolean24m?
              Convert  4mdateString24m  to  an  integer clock value (see 1mclock sec-0m
              1monds22m).  This command can parse and convert virtually  any  stan-
              dard  date  and/or  time string, which can include standard time
              zone mnemonics.  If only a time is specified, the  current  date
              is  assumed.   If  the  string  does  not  contain  a  time zone
              mnemonic, the local time zone is assumed, unless the 1m-gmt  22margu-
              ment is true, in which case the clock value is calculated assum-
              ing that the specified time is relative to Greenwich Mean  Time.
              1m-gmt22m,  if  specified,  affects  only the computed time value; it
              does not impact the interpretation of 1m-base22m.

              If the 1m-base 22mflag 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 spe-
              cific day or doing other date-relative conversions.

              The  4mdateString24m  consists  of zero or more specifications of the
              following form:

              4mtime24m   A time  of  day,  which  is  of  the  form:  4mhh24m?4m:mm24m?4m:ss24m??
                     ?4mmeridian24m?  ?4mzone24m?  or  4mhhmm24m  ?4mmeridian24m?   ?4mzone24m?.  If no
                     meridian is specified, 4mhh24m is  interpreted  on  a  24-hour
                     clock.

              4mdate24m   A specific month and day with optional year.  The accept-
                     able formats are 4mmm/dd24m?4m/yy24m?, 4mmonthname24m 4mdd24m ?, 4myy24m?, 4mdd24m 4mmon-0m
                     4mthname24m ?4myy24m?, 4mday,24m 4mdd24m 4mmonthname24m 4myy24m, 4m?CC?yymmdd24m, 4m?CC?yy-mm-0m
                     4mdd24m, 4mdd-monthname-?CC?yy24m.  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.

              4mISO24m 4m860124m 4mpoint-in-time0m
                     An ISO 8601 point-in-time specification, such as 4mCCyymmd-0m
                     4mdThhmmss24m,  where  T is the literal T, 4mCCyymmdd24m 4mhhmmss24m, or
                     4mCCyymmddThh:mm:ss24m.

              4mrelative24m 4mtime0m
                     A specification relative to the current time.  The format
                     is  4mnumber24m  4munit24m  acceptable  units  are 1myear22m, 1mfortnight22m,
                     1mmonth22m, 1mweek22m, 1mday22m, 1mhour22m, 1mminute 22m(or 1mmin22m), and  1msecond  22m(or
                     1msec22m).  The unit can be specified as a singular or plural,
                     as in 1m3 weeks22m.  These modifiers may  also  be  specified:
                     1mtomorrow22m, 1myesterday22m, 1mtoday22m, 1mnow22m, 1mlast22m, 1mthis22m, 1mnext22m, 1mago22m.

              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.

              Daylight  savings time correction is applied only when the rela-
              tive time is specified in units  of  days  or  more,  ie,  days,
              weeks, fortnights, months or years.  This means that when cross-
              ing the daylight savings time boundary, different  results  will
              be given for 1mclock scan "1 day" 22mand 1mclock scan "24 hours"22m:
                     % 1mclock scan 22m"1 day" -base [1mclock scan 22m1999-10-31]
                     941443200
                     % 1mclock scan 22m"24 hours" -base [1mclock scan 22m1999-10-31]
                     941439600

       1mclock seconds0m
              Return  the  current date and time as a system-dependent integer
              value.  The unit of the value is seconds, allowing it to be used
              for relative time calculations.  The value is usually defined as
              total elapsed time from an ``epoch''.  You shouldn't assume  the
              value of the epoch.


1mSEE ALSO0m
       date(1), time(n)


1mKEYWORDS0m
