1Tcl_GetTime(3)              Tcl Library Procedures              Tcl_GetTime(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc - get date and time
9

SYNOPSIS

11       #include <tcl.h>
12
13       Tcl_GetTime(timePtr)
14
15       Tcl_SetTimeProc(getProc, scaleProc, clientData)
16
17       Tcl_QueryTimeProc(getProcPtr, scaleProcPtr, clientDataPtr)
18

ARGUMENTS

20       Tcl_Time * timePtr (out)         Points to memory in which to store the
21                                        date and time information.
22
23       Tcl_GetTimeProc * getProc (in)          Pointer  to  handler   function
24                                               replacing  Tcl_GetTime's access
25                                               to the OS.
26
27       Tcl_ScaleTimeProc * scaleProc (in)          Pointer to handler function
28                                                   for  the conversion of time
29                                                   delays   in   the   virtual
30                                                   domain to real-time.
31
32       ClientData * clientData (in)          Value  passed  through to the two
33                                             handler functions.
34
35       Tcl_GetTimeProc ** getProcPtr (inout)       Pointer to place  the  cur‐
36                                                   rently  registered get han‐
37                                                   dler function into.
38
39       Tcl_ScaleTimeProc ** scaleProcPtr (inout)       Pointer  to  place  the
40                                                       currently    registered
41                                                       scale handler  function
42                                                       into.
43
44       ClientData ** clientDataPtr (inout)       Pointer  to  place  the  cur‐
45                                                 rently    registered    pass-
46                                                 through value into.
47_________________________________________________________________
48

DESCRIPTION

50       The  Tcl_GetTime  function  retrieves  the  current  time as a Tcl_Time
51       structure in memory the caller provides.  This structure has  the  fol‐
52       lowing definition:
53              typedef struct Tcl_Time {
54                  long sec;
55                  long usec;
56              } Tcl_Time;
57
58       On return, the sec member of the structure is filled in with the number
59       of seconds that have elapsed since the epoch: the epoch is the point in
60       time  of  00:00  UTC,  1 January 1970.  This number does not count leap
61       seconds - an interval of one day advances it by 86400  seconds  regard‐
62       less of whether a leap second has been inserted.
63
64       The  usec  member  of  the  structure  is  filled in with the number of
65       microseconds that have elapsed since the start of the second designated
66       by sec.  The Tcl library makes every effort to keep this number as pre‐
67       cise as possible, subject to the limitations of  the  computer  system.
68       On  multiprocessor  variants  of Windows, this number may be limited to
69       the 10- or 20-ms granularity of the system clock.  (On single-processor
70       Windows  systems,  the usec field is derived from a performance counter
71       and is highly precise.)
72
73       The Tcl_SetTime function registers two related handler  functions  with
74       the  core. The first handler function is a replacement for Tcl_GetTime,
75       or rather the OS access made by Tcl_GetTime. The other handler function
76       is  used  by the Tcl notifier to convert wait/block times from the vir‐
77       tual domain into real time.
78
79       The Tcl_QueryTime function returns  the  currently  registered  handler
80       functions.  If  no external handlers were set then this will return the
81       standard handlers accessing and processing the native time of  the  OS.
82       The  arguments to the function are allowed to be NULL; and any argument
83       which is NULL is ignored and not set.
84
85       Any handler pair specified has  to  return  data  which  is  consistent
86       between  them. In other words, setting one handler of the pair to some‐
87       thing assuming a 10-times slowdown, and the other handler of  the  pair
88       to something assuming a two-times slowdown is wrong and not allowed.
89
90       The  set  handler functions are allowed to run the delivered time back‐
91       wards, however this should be avoided. We  have  to  allow  it  as  the
92       native  time  can  run backwards as the user can fiddle with the system
93       time one way or other. Note that the insertion of the  hooks  will  not
94       change  the  behaviour  of  the Tcl core with regard to this situation,
95       i.e. the existing behaviour is retained.
96

SEE ALSO

98       clock
99

KEYWORDS

101       date, time
102
103
104
105Tcl                                   8.4                       Tcl_GetTime(3)
Impressum