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

FreeBSD Manual Pages


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


       Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc - get date and time

       #include	<tcl.h>


       Tcl_SetTimeProc(getProc,	scaleProc, clientData)

       Tcl_QueryTimeProc(getProcPtr, scaleProcPtr, clientDataPtr)

       Tcl_Time	*timePtr (out)		      Points  to  memory  in  which to
					      store the	date and time informa-

       Tcl_GetTimeProc getProc (in)	      Pointer  to handler function re-
					      placing 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
					      handler functions.

       Tcl_GetTimeProc *getProcPtr (out)      Pointer to place	the  currently
					      registered  get handler function

       Tcl_ScaleTimeProc *scaleProcPtr (out)  Pointer to place	the  currently
					      registered  scale	 handler func-
					      tion into.

       ClientData *clientDataPtr (out)	      Pointer to place	the  currently
					      registered   pass-through	 value

       The Tcl_GetTime function	retrieves  the	current	 time  as  a  Tcl_Time
       structure  in  memory the caller	provides.  This	structure has the fol-
       lowing definition:

	      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 regard-
       less of whether a leap second has been inserted.

       The usec	member of the structure	is filled in with the  number  of  mi-
       croseconds  that	 have elapsed since the	start of the second designated
       by sec.	The Tcl	library	makes every effort to keep this	number as pre-
       cise  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.)

       The  Tcl_SetTimeProc  function  registers two related handler functions
       with the	core. The first	handler	function is a replacement for Tcl_Get-
       Time,  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.

       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.

       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 be-
       tween them. In other words, setting one handler of the  pair  to	 some-
       thing  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 set handler functions are allowed to	run the	delivered  time	 back-
       wards,  however	this should be avoided.	We have	to allow it as the na-
       tive 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.


       date, time

Tcl				      8.4			Tcl_GetTime(3)


Want to link to this manual page? Use this URL:

home | help