diff options
Diffstat (limited to 'doc/GetTime.3')
| -rw-r--r-- | doc/GetTime.3 | 78 |
1 files changed, 67 insertions, 11 deletions
diff --git a/doc/GetTime.3 b/doc/GetTime.3 index 7941379..6b885ee 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -1,36 +1,52 @@ '\" -'\" Copyright (c) 2001 by Kevin B. Kenny. +'\" Copyright (c) 2001 by Kevin B. Kenny <kennykb@acm.org>. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros .TH Tcl_GetTime 3 8.4 Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME -Tcl_GetTime \- get date and time +Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time .SH SYNOPSIS .nf \fB#include <tcl.h>\fR .sp \fBTcl_GetTime\fR(\fItimePtr\fR) +.sp +\fBTcl_SetTimeProc\fR(\fIgetProc, scaleProc, clientData\fR) +.sp +\fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR) .SH ARGUMENTS -.AS "Tcl_Time *" timePtr out -.AP "Tcl_Time *" timePtr out +.AS Tcl_GetTimeProc *getProc in +.AP Tcl_Time *timePtr out Points to memory in which to store the date and time information. +.AP Tcl_GetTimeProc getProc in +Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS. +.AP Tcl_ScaleTimeProc scaleProc in +Pointer to handler function for the conversion of time delays in the +virtual domain to real-time. +.AP ClientData clientData in +Value passed through to the two handler functions. +.AP Tcl_GetTimeProc *getProcPtr out +Pointer to place the currently registered get handler function into. +.AP Tcl_ScaleTimeProc *scaleProcPtr out +Pointer to place the currently registered scale handler function into. +.AP ClientData *clientDataPtr out +Pointer to place the currently registered pass-through value into. .BE .SH DESCRIPTION .PP The \fBTcl_GetTime\fR function retrieves the current time as a \fITcl_Time\fR structure in memory the caller provides. This structure has the following definition: +.PP .CS typedef struct Tcl_Time { - long sec; - long usec; -} Tcl_Time; + long \fIsec\fR; + long \fIusec\fR; +} \fBTcl_Time\fR; .CE .PP On return, the \fIsec\fR member of the structure is filled in with the @@ -47,7 +63,47 @@ 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 \fIusec\fR field is derived from a performance counter and is highly precise.) +.SS "VIRTUALIZED TIME" +.PP +The \fBTcl_SetTimeProc\fR function registers two related handler functions +with the core. The first handler function is a replacement for +\fBTcl_GetTime\fR, or rather the OS access made by +\fBTcl_GetTime\fR. The other handler function is used by the Tcl +notifier to convert wait/block times from the virtual domain into real +time. +.PP +The \fBTcl_QueryTimeProc\fR 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. +.PP +The signatures of the handler functions are as follows: +.PP +.CS +typedef void \fBTcl_GetTimeProc\fR( + Tcl_Time *\fItimebuf\fR, + ClientData \fIclientData\fR); +typedef void \fBTcl_ScaleTimeProc\fR( + Tcl_Time *\fItimebuf\fR, + ClientData \fIclientData\fR); +.CE +.PP +The \fItimebuf\fR fields contain the time to manipulate, and the +\fIclientData\fR fields contain a pointer supplied at the time the handler +functions were registered. +.PP +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. +.PP +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 behavior of the Tcl core +with regard to this situation, i.e. the existing behavior is retained. .SH "SEE ALSO" -clock +clock(n) .SH KEYWORDS date, time |