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
21                                              store the date and time informa‐
22                                              tion.
23
24       Tcl_GetTimeProc getProc (in)           Pointer  to handler function re‐
25                                              placing Tcl_GetTime's access  to
26                                              the OS.
27
28       Tcl_ScaleTimeProc scaleProc (in)       Pointer  to handler function for
29                                              the conversion of time delays in
30                                              the virtual domain to real-time.
31
32       ClientData clientData (in)             Value  passed through to the two
33                                              handler functions.
34
35       Tcl_GetTimeProc *getProcPtr (out)      Pointer to place  the  currently
36                                              registered  get handler function
37                                              into.
38
39       Tcl_ScaleTimeProc *scaleProcPtr (out)  Pointer to place  the  currently
40                                              registered  scale  handler func‐
41                                              tion into.
42
43       ClientData *clientDataPtr (out)        Pointer to place  the  currently
44                                              registered   pass-through  value
45                                              into.
46______________________________________________________________________________
47

DESCRIPTION

49       The Tcl_GetTime function retrieves  the  current  time  as  a  Tcl_Time
50       structure  in  memory the caller provides.  This structure has the fol‐
51       lowing definition:
52
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  mi‐
65       croseconds  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   VIRTUALIZED TIME
74       The  Tcl_SetTimeProc  function  registers two related handler functions
75       with the core. The first handler function is a replacement for Tcl_Get‐
76       Time,  or  rather  the OS access made by Tcl_GetTime. The other handler
77       function is used by the Tcl notifier to convert wait/block  times  from
78       the virtual domain into real time.
79
80       The Tcl_QueryTimeProc function returns the currently registered handler
81       functions. If no external handlers were set then this will  return  the
82       standard  handlers  accessing and processing the native time of the OS.
83       The arguments to the function are allowed to be NULL; and any  argument
84       which is NULL is ignored and not set.
85
86       The signatures of the handler functions are as follows:
87
88              typedef void Tcl_GetTimeProc(
89                      Tcl_Time *timebuf,
90                      ClientData clientData);
91              typedef void Tcl_ScaleTimeProc(
92                      Tcl_Time *timebuf,
93                      ClientData clientData);
94
95       The  timebuf  fields contain the time to manipulate, and the clientData
96       fields contain a pointer supplied at the  time  the  handler  functions
97       were registered.
98
99       Any  handler  pair specified has to return data which is consistent be‐
100       tween them. In other words, setting one handler of the  pair  to  some‐
101       thing  assuming  a 10-times slowdown, and the other handler of the pair
102       to something assuming a two-times slowdown is wrong and not allowed.
103
104       The set handler functions are allowed to run the delivered  time  back‐
105       wards,  however  this should be avoided. We have to allow it as the na‐
106       tive time can run backwards as the user can fiddle with the system time
107       one  way or other. Note that the insertion of the hooks will not change
108       the behavior of the Tcl core with regard to this  situation,  i.e.  the
109       existing behavior is retained.
110

SEE ALSO

112       clock(n)
113

KEYWORDS

115       date, time
116
117
118
119Tcl                                   8.4                       Tcl_GetTime(3)
Impressum