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
25                                              replacing  Tcl_GetTime's  access
26                                              to 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
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   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
100       between 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
106       native time can run backwards as the user can fiddle  with  the  system
107       time  one  way  or other. Note that the insertion of the hooks will not
108       change the behavior of the Tcl core with regard to this situation, i.e.
109       the 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