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-edi-
tor.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
suitable 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 de-
fault is 10 seconds.
-command number
Set a command procedure to be run when a reply is re-
ceived. The procedure is called with the time token ap-
pended to the argument 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 de-
fines 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 re-
turned.
::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 comple-
tion.
::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 Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
report any ideas for enhancements you may have for either package
and/or documentation.
When proposing code changes, please provide unified diffs, i.e the out-
put of diff -u.
Note further that attachments are strongly preferred over inlined
patches. Attachments can be made by going to the Edit form of the
ticket immediately after its creation, and then using the left-most
button in the secondary navigation bar.
SEE ALSO
ntp
KEYWORDS
NTP, SNTP, rfc 2030, rfc 868, time
CATEGORY
Networking
COPYRIGHT
Copyright (c) 2002, Pat Thoyts <patthoyts@users.sourceforge.net>
tcllib 1.2.1 ntp_time(3tcl)