| 1 | '\" |
|---|
| 2 | '\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>. |
|---|
| 3 | '\" |
|---|
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
|---|
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
|---|
| 6 | '\" |
|---|
| 7 | '\" RCS: @(#) $Id$ |
|---|
| 8 | '\" |
|---|
| 9 | .so man.macros |
|---|
| 10 | .TH Tcl_GetTime 3 8.4 Tcl "Tcl Library Procedures" |
|---|
| 11 | .BS |
|---|
| 12 | .SH NAME |
|---|
| 13 | Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time |
|---|
| 14 | .SH SYNOPSIS |
|---|
| 15 | .nf |
|---|
| 16 | \fB#include <tcl.h>\fR |
|---|
| 17 | .sp |
|---|
| 18 | \fBTcl_GetTime\fR(\fItimePtr\fR) |
|---|
| 19 | .sp |
|---|
| 20 | \fBTcl_SetTimeProc\fR(\fIgetProc, scaleProc, clientData\fR) |
|---|
| 21 | .sp |
|---|
| 22 | \fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR) |
|---|
| 23 | .SH ARGUMENTS |
|---|
| 24 | .AS "Tcl_Time *" timePtr out |
|---|
| 25 | .AP "Tcl_Time *" timePtr out |
|---|
| 26 | Points to memory in which to store the date and time information. |
|---|
| 27 | .AS "Tcl_GetTimeProc *" getProc in |
|---|
| 28 | .AP "Tcl_GetTimeProc *" getProc in |
|---|
| 29 | Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS. |
|---|
| 30 | .AS "Tcl_ScaleTimeProc *" scaleProc in |
|---|
| 31 | .AP "Tcl_ScaleTimeProc *" scaleProc in |
|---|
| 32 | Pointer to handler function for the conversion of time delays in the |
|---|
| 33 | virtual domain to real-time. |
|---|
| 34 | .AS "ClientData *" clientData in |
|---|
| 35 | .AP "ClientData *" clientData in |
|---|
| 36 | Value passed through to the two handler functions. |
|---|
| 37 | .AS "Tcl_GetTimeProc **" getProcPtr inout |
|---|
| 38 | .AP "Tcl_GetTimeProc **" getProcPtr inout |
|---|
| 39 | Pointer to place the currently registered get handler function into. |
|---|
| 40 | .AS "Tcl_ScaleTimeProc **" scaleProcPtr inout |
|---|
| 41 | .AP "Tcl_ScaleTimeProc **" scaleProcPtr inout |
|---|
| 42 | Pointer to place the currently registered scale handler function into. |
|---|
| 43 | .AS "ClientData **" clientDataPtr inout |
|---|
| 44 | .AP "ClientData **" clientDataPtr inout |
|---|
| 45 | Pointer to place the currently registered pass-through value into. |
|---|
| 46 | .BE |
|---|
| 47 | .SH DESCRIPTION |
|---|
| 48 | .PP |
|---|
| 49 | The \fBTcl_GetTime\fR function retrieves the current time as a |
|---|
| 50 | \fITcl_Time\fR structure in memory the caller provides. This |
|---|
| 51 | structure has the following definition: |
|---|
| 52 | .CS |
|---|
| 53 | typedef struct Tcl_Time { |
|---|
| 54 | long sec; |
|---|
| 55 | long usec; |
|---|
| 56 | } Tcl_Time; |
|---|
| 57 | .CE |
|---|
| 58 | .PP |
|---|
| 59 | On return, the \fIsec\fR member of the structure is filled in with the |
|---|
| 60 | number of seconds that have elapsed since the \fIepoch:\fR the epoch |
|---|
| 61 | is the point in time of 00:00 UTC, 1 January 1970. This number does |
|---|
| 62 | \fInot\fR count leap seconds \- an interval of one day advances it by |
|---|
| 63 | 86400 seconds regardless of whether a leap second has been inserted. |
|---|
| 64 | .PP |
|---|
| 65 | The \fIusec\fR member of the structure is filled in with the number of |
|---|
| 66 | microseconds that have elapsed since the start of the second |
|---|
| 67 | designated by \fIsec\fR. The Tcl library makes every effort to keep |
|---|
| 68 | this number as precise as possible, subject to the limitations of the |
|---|
| 69 | computer system. On multiprocessor variants of Windows, this number |
|---|
| 70 | may be limited to the 10- or 20-ms granularity of the system clock. |
|---|
| 71 | (On single-processor Windows systems, the \fIusec\fR field is derived |
|---|
| 72 | from a performance counter and is highly precise.) |
|---|
| 73 | .PP |
|---|
| 74 | The \fBTcl_SetTime\fR function registers two related handler functions |
|---|
| 75 | with the core. The first handler function is a replacement for |
|---|
| 76 | \fBTcl_GetTime\fR, or rather the OS access made by |
|---|
| 77 | \fBTcl_GetTime\fR. The other handler function is used by the Tcl |
|---|
| 78 | notifier to convert wait/block times from the virtual domain into real |
|---|
| 79 | time. |
|---|
| 80 | .PP |
|---|
| 81 | The \fBTcl_QueryTime\fR function returns the currently registered |
|---|
| 82 | handler functions. If no external handlers were set then this will |
|---|
| 83 | return the standard handlers accessing and processing the native time |
|---|
| 84 | of the OS. The arguments to the function are allowed to be NULL; and |
|---|
| 85 | any argument which is NULL is ignored and not set. |
|---|
| 86 | .PP |
|---|
| 87 | Any handler pair specified has to return data which is consistent |
|---|
| 88 | between them. In other words, setting one handler of the pair to |
|---|
| 89 | something assuming a 10-times slowdown, and the other handler of the |
|---|
| 90 | pair to something assuming a two-times slowdown is wrong and not |
|---|
| 91 | allowed. |
|---|
| 92 | .PP |
|---|
| 93 | The set handler functions are allowed to run the delivered time |
|---|
| 94 | backwards, however this should be avoided. We have to allow it as the |
|---|
| 95 | native time can run backwards as the user can fiddle with the system |
|---|
| 96 | time one way or other. Note that the insertion of the hooks will not |
|---|
| 97 | change the behaviour of the Tcl core with regard to this situation, |
|---|
| 98 | i.e. the existing behaviour is retained. |
|---|
| 99 | .SH "SEE ALSO" |
|---|
| 100 | clock |
|---|
| 101 | .SH KEYWORDS |
|---|
| 102 | date, time |
|---|
