Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
Tcl_GetTime(3)		     Tcl Library Procedures		  Tcl_GetTime(3)

________________________________________________________________________________

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 in which to store
					    the date and time information.

     Tcl_GetTimeProc getProc (in)	    Pointer to handler function  replac-
					    ing Tcl_GetTime's access to the OS.

     Tcl_ScaleTimeProc scaleProc (in)	    Pointer  to handler function for the
					    conversion of  time  delays  in  the
					    virtual domain to real-time.

     ClientData clientData (in) 	    Value passed through to the two han-
					    dler functions.

     Tcl_GetTimeProc *getProcPtr (out)	    Pointer  to place the currently reg-
					    istered get handler function into.

     Tcl_ScaleTimeProc *scaleProcPtr (out)  Pointer to place the currently  reg-
					    istered scale handler function into.

     ClientData *clientDataPtr (out)	    Pointer  to place the currently reg-
					    istered pass-through value into.
________________________________________________________________________________

DESCRIPTION
     The Tcl_GetTime function retrieves the current time as a Tcl_Time structure
     in memory the caller provides.  This structure has  the  following  defini-
     tion:

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

     On  return, the sec member of the structure is filled in with the number of
     seconds that have elapsed since the epoch: the epoch is the point	in  time
     of 00:00 UTC, 1 January 1970.  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 usec member of the structure is filled in with the number of  microsec-
     onds  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 possi-
     ble, subject to the limitations of the computer system.  On  multiprocessor
     variants  of Windows, this number may be limited to the 10- or 20-ms granu-
     larity of the system clock.  (On single-processor Windows systems, the usec
     field is derived from a performance counter and is highly precise.)

   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 do-
     main into real time.

     The Tcl_QueryTimeProc function returns  the  currently  registered  handler
     functions. If no external handlers were set then this will return the stan-
     dard handlers accessing and processing the native time of the OS. The argu-
     ments  to	the  function  are allowed to be NULL; and any argument which is
     NULL is ignored and not set.

     The signatures of the handler functions are as follows:

	    typedef void Tcl_GetTimeProc(
		    Tcl_Time *timebuf,
		    ClientData clientData);
	    typedef void Tcl_ScaleTimeProc(
		    Tcl_Time *timebuf,
		    ClientData 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.

     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 assum-
     ing a two-times slowdown is wrong and not allowed.

     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 re-
     tained.

SEE ALSO
     clock(n)

KEYWORDS
     date, time

Tcl				       8.4			  Tcl_GetTime(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_GetTime.tcl86&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help