Tcl_GetTime(3tcl)

💖 Tcl_GetTime — get date and time 💖

okay bestie, so this is a page from the Tcl Library Procedures manual, and it's literally all about grabbing the current date and time, plus the whole ✨virtual time✨ situation. It's Tcl_GetTime(3tcl), she's iconic, let's get into it 🫶

---

🌸 NAME 🌸

Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc — get date and time

---

✨ SYNOPSIS ✨

#include <tcl.h>

Tcl_GetTime(timePtr)

Tcl_SetTimeProc(getProc, scaleProc, clientData)

Tcl_QueryTimeProc(getProcPtr, scaleProcPtr, clientDataPtr)

---

🎀 ARGUMENTS 🎀

• Tcl_Time *timePtr (out) — points to memory where we're gonna stash the date and time info. you bring the memory, she fills it 💅
• Tcl_GetTimeProc getProc (in) — pointer to a handler function that replaces Tcl_GetTime's access to the OS. yes bestie, you can swap out how time is gotten.
• Tcl_ScaleTimeProc scaleProc (in) — pointer to a handler function for converting time delays in the virtual domain into real-time.
• void *clientData (in) — a value that gets passed straight through to the two handler functions. just vibes, carried along.
• Tcl_GetTimeProc *getProcPtr (out) — pointer to a place where the currently registered get handler function goes.
• Tcl_ScaleTimeProc *scaleProcPtr (out) — pointer to a place where the currently registered scale handler function goes.
• void **clientDataPtr (out) — pointer to a place where the currently registered pass-through value goes.

---

🦋 DESCRIPTION 🦋

So Tcl_GetTime retrieves the current time as a Tcl_Time structure, and it puts it in memory that the caller provides. the structure is giving:

typedef struct {
    long long sec;
    long usec;
} Tcl_Time;

On return, the sec member gets filled in with the number of seconds that have elapsed since the epoch — and the epoch is that point in time of 00:00 UTC, 1 January 1970. periodt. and no, this number does not count leap seconds; an interval of one day advances it by 86400 seconds regardless of whether a leap second has been inserted. the math stays mathing 🌈

The usec member gets filled in with the number of microseconds that have elapsed since the start of the second designated by sec. The Tcl library makes every effort to keep this number as precise as possible, subject to the limitations of the 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 usec field is derived from a performance counter and is highly precise — slay, honestly 💅)

🧚 VIRTUALIZED TIME 🧚

The Tcl_SetTimeProc function registers two related handler functions with the core. The first handler function is a replacement for Tcl_GetTime, or rather the OS access made by Tcl_GetTime. The other handler function is used by the Tcl notifier to convert wait/block times from the virtual domain into real time. it's giving time but make it custom ✨

The Tcl_QueryTimeProc 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. so if you don't care about one of them, just pass NULL and move on bestie 🙈

The signatures of the handler functions are as follows:

typedef void Tcl_GetTimeProc(
        Tcl_Time *timebuf,
        void *clientData);
typedef void Tcl_ScaleTimeProc(
        Tcl_Time *timebuf,
        void *clientData);

The timebuf fields contain the time to manipulate, and the clientData fields contain a pointer supplied at the time the handler functions were registered. 🎀

⚠️ okay this part matters: 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. the two of them have to be on the same page, no mismatched energy fr fr 💀

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. so like… it's allowed but don't be weird about it 😭

---

👑 SEE ALSO 👑

• clock(3tcl)

---

💜 KEYWORDS 💜

date, time

---

and that's the whole page bestie, no notes 💖 This was the Tcl library procedures manual, version 8.4, so thank you for coming to my TED talk, stay precise, stay consistent, and don't run time backwards unless you absolutely have to 🎀✨🦋