doc/GetTime.3 - main - niceSOFT/tcl

doc/GetTime.3
85 строк3 KB
jan.nijtmans
Complete deprecation of Tcl_SetTimeProc/Tcl_QueryTimeProc
19 янв 2026, 01:26
19 янв 2026, 01:26716f83c
'\"
'\" Copyright (c) 2001 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.
'\"
.TH Tcl_GetTime 3 8.4 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_GetMonotonicTime, Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
long long
\fBTcl_GetMonotonicTime\fR()
.sp
\fBTcl_GetTime\fR(\fItimePtr\fR)
.sp
\fBTcl_SetTimeProc\fR(\fIgetProc, scaleProc, clientData\fR)
.sp
\fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR)
.fi
.SH ARGUMENTS
.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 void *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 void **clientDataPtr out
Pointer to place the currently registered pass-through value into.
.BE
.SH DESCRIPTION
.PP
The \fBTcl_GetMonotonicTime\fR function returns the current monotonic time.
The unit is micro-seconds.
Only time differences are defined.
The timer value 0 may be the epoc but may also be the start-up of the system.
.PP
The value is contiguous but may jump due to timer virtualization or sleep mode.
.PP
The precision is system dependent and not guaranteed to be micro-second precise.
.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 {
    long 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
number of seconds that have elapsed since the \fIepoch:\fR the epoch
is the point in time of 00:00 UTC, 1 January 1970.  This number does
\fInot\fR count leap seconds; an interval of one day advances it by
86400 seconds regardless of whether a leap second has been inserted.
.PP
The \fIusec\fR member of the structure is filled in with the number of
microseconds that have elapsed since the start of the second
designated by \fIsec\fR.
.PP
This command uses the system wall clock and is not contiguous by definition.
It may have large jumps in short time, specially if the system is awaked from
sleep mode.
.SS "VIRTUALIZED TIME"
.PP
The \fBTcl_SetTimeProc\fR and \fBTcl_QueryTimeProc\fR are not supported since TCL 9.1.
They call a \fBTcl_Panic\fR.
.SH "SEE ALSO"
clock(n), timer(n)
.SH KEYWORDS
date, time