NAME

       Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc - get date and time

SYNOPSIS

       #include <tcl.h>

       Tcl_GetTime(timePtr)

       Tcl_SetTimeProc(getProc, scaleProc, clientData)

       Tcl_QueryTimeProc(getProcPtr, scaleProcPtr, clientDataPtr)

ARGUMENTS

       Tcl_Time * timePtr (out)         Points to memory in which to store the date and time information.

       Tcl_GetTimeProc * getProc (in)          Pointer to handler function replacing Tcl_GetTime's access to the
                                               OS.

       Tcl_ScaleTimeProc * scaleProc (in)          Pointer to handler function for the conversion of time delays
                                                   in the virtual domain to real-time.

       ClientData * clientData (in)          Value passed through to the two handler functions.

       Tcl_GetTimeProc ** getProcPtr (inout)       Pointer   to  place  the  currently  registered  get  handler
                                                   function into.

       Tcl_ScaleTimeProc ** scaleProcPtr (inout)       Pointer to place the currently registered  scale  handler
                                                       function into.

       ClientData ** clientDataPtr (inout)       Pointer  to  place  the currently registered pass-through value
                                                 into.
________________________________________________________________________________________________________________

DESCRIPTION

       The Tcl_GetTime function retrieves the current  time  as  a  Tcl_Time  structure  in  memory  the  caller
       provides.  This structure has the following definition:
              typedef struct Tcl_Time {
                  long sec;
                  long usec;
              } Tcl_Time;

       On  return,  the  sec  member  of the structure is filled in with the number of seconds that have elapsed
       since the epoch: the epoch is the point in time of 00:00 UTC, 1 January 1970.  This number does not count
       leap  seconds  -  an interval of one day advances it by 86400 seconds regardless of whether a leap second
       has been inserted.

       The usec member of the structure is filled in with the number of microseconds that have elapsed since the
       start of the second designated by sec.  The Tcl library makes every effort to keep this number as precise
       as possible, subject to the limitations of the computer system.  On multiprocessor variants  of  Windows,
       this  number  may  be  limited to the 10- or 20-ms granularity of the system clock.  (On single-processor
       Windows systems, the usec field is derived from a performance counter and is highly precise.)

       The Tcl_SetTime function registers two related  handler  functions  with  the  core.  The  first  handler
       function is a replacement for Tcl_GetTime, or rather the OS access made by Tcl_GetTime. The other handler
       function is used by the Tcl notifier to convert wait/block times from the virtual domain into real time.

       The Tcl_QueryTime function returns the currently registered handler functions. If  no  external  handlers
       were  set then this will return the standard handlers accessing and processing the native time of the OS.
       The arguments to the function are allowed to be NULL; and any argument which is NULL is ignored  and  not
       set.

       Any  handler  pair specified has to return data which is consistent between them. In other words, setting
       one handler of the pair to something assuming a 10-times slowdown, and the other handler of the  pair  to
       something assuming a two-times slowdown is wrong and not allowed.

       The  set  handler  functions  are  allowed  to  run  the delivered time backwards, however this should be
       avoided. We have to allow it as the native time can run backwards as the user can fiddle with the  system
       time one way or other. Note that the insertion of the hooks will not change the behaviour of the Tcl core
       with regard to this situation, i.e. the existing behaviour is retained.

SEE ALSO

       clock

KEYWORDS

       date, time