ntp_time(3tcl)						      Network Time Facilities						    ntp_time(3tcl)

__________________________________________________________________________________________________________________________________________________

NAME

       ntp_time - Tcl Time Service Client

SYNOPSIS

       package require Tcl  8.0

       package require time  ?1.2.1?

       ::time::gettime ?options? timeserver ?port?

       ::time::getsntp ?options? timeserver ?port?

       ::time::configure ?options?

       ::time::cget name

       ::time::unixtime token

       ::time::status token

       ::time::error token

       ::time::reset token ?reason?

       ::time::wait token

       ::time::cleanup token

_________________________________________________________________

DESCRIPTION

       This package implements a client for the RFC 868 TIME protocol (http://www.rfc-editor.org/rfc/rfc868.txt) and also a minimal client for the
       RFC 2030 Simple Network Time Protocol (http://www.rfc-editor.org/rfc/rfc2030.txt).  RFC 868 returns the time in	seconds  since	1  January
       1900 to either tcp or udp clients. RFC 2030 also gives this time but also provides a fractional part which is not used in this client.

COMMANDS

       ::time::gettime ?options? timeserver ?port?
	      Get the time from timeserver. You may specify any of the options listed for the configure command here. This command returns a token
	      which must then be used with the remaining commands in this package. Once you have finished, you should use cleanup to  release  all
	      resources. The default port is 37.

       ::time::getsntp ?options? timeserver ?port?
	      Get  the	time  from an SNTP server. This accepts exactly the same arguments as ::time::gettime except that the default port is 123.
	      The result is a token as per ::time::gettime and should be handled in the same way.

	      Note that it is unlikely that any SNTP server will reply using tcp so you will require the tcludp or the ceptcl package. If a  suit-
	      able package can be loaded then the udp protocol will be used by default.

       ::time::configure ?options?
	      Called  with  no arguments this command returns all the current configuration options and values. Otherwise it should be called with
	      pairs of option name and value.

	      -protocol number
		     Set the default network protocol. This defaults to udp if the tcludp package is available. Otherwise it will use tcp.

	      -port number
		     Set the default port to use. RFC 868 uses port 37, RFC 2030 uses port 123.

	      -timeout number
		     Set the default timeout value in milliseconds. The default is 10 seconds.

	      -command number
		     Set a command procedure to be run when a reply is received. The procedure is called with the time token appended to the argu-
		     ment list.

	      -loglevel number
		     Set the logging level. The default is 'warning'.

       ::time::cget name
	      Get the current value for the named configuration option.

       ::time::unixtime token
	      Format  the  returned  time  for	the unix epoch. RFC 868 time defines time 0 as 1 Jan 1900, while unix time defines time 0 as 1 Jan
	      1970. This command converts the reply to unix time.

       ::time::status token
	      Returns the status flag. For a successfully completed query this will be ok. May be error or timeout or eof.  See also ::time::error

       ::time::error token
	      Returns the error message provided for requests whose status is error.  If there is  no  error  message  then  an  empty	string	is
	      returned.

       ::time::reset token ?reason?
	      Reset or cancel the query optionally specfying the reason to record for the error command.

       ::time::wait token
	      Wait for a query to complete and return the status upon completion.

       ::time::cleanup token
	      Remove all state variables associated with the request.

	      % set tok [::time::gettime ntp2a.mcc.ac.uk]
	      % set t [::time::unixtime $tok]
	      % ::time::cleanup $tok

	      % set tok [::time::getsntp pool.ntp.org]
	      % set t [::time::unixtime $tok]
	      % ::time::cleanup $tok

	      proc on_time {token} {
		 if {[time::status $token] eq "ok"} {
		    puts [clock format [time::unixtime $token]]
		 } else {
		    puts [time::error $token]
		 }
		 time::cleanup $token
	      }
	      time::getsntp -command on_time pool.ntp.org

AUTHORS

       Pat Thoyts

BUGS, IDEAS, FEEDBACK
       This  document,	and the package it describes, will undoubtedly contain bugs and other problems.  Please report such in the category ntp of
       the Tcllib SF Trackers [http://sourceforge.net/tracker/?group_id=12883].  Please also report any ideas for enhancements you  may  have  for
       either package and/or documentation.

SEE ALSO

       ntp

KEYWORDS

       NTP, SNTP, rfc 2030, rfc 868, time

CATEGORY

       Networking

COPYRIGHT

       Copyright (c) 2002, Pat Thoyts <patthoyts@users.sourceforge.net>

ntp								       1.2.1							    ntp_time(3tcl)