1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
[manpage_begin ntp_time n 1.2.1]
[see_also ntp]
[keywords NTP]
[keywords {rfc 868}]
[keywords {rfc 2030}]
[keywords SNTP]
[keywords time]
[copyright {2002, Pat Thoyts <patthoyts@users.sourceforge.net>}]
[moddesc {Network Time Facilities}]
[titledesc {Tcl Time Service Client}]
[category Networking]
[require Tcl 8.0]
[require time [opt 1.2.1]]
[description]
[para]
This package implements a client for the RFC 868 TIME protocol
([uri http://www.rfc-editor.org/rfc/rfc868.txt]) and also a minimal
client for the RFC 2030 Simple Network Time Protocol
([uri 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.
[section COMMANDS]
[list_begin definitions]
[call [cmd ::time::gettime] [opt [arg "options"]] [arg timeserver] [opt [arg "port"]]]
Get the time from [arg timeserver]. You may specify any of the options
listed for the [cmd 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 [cmd cleanup] to
release all resources. The default port is [const 37].
[call [cmd ::time::getsntp] [opt [arg "options"]] [arg timeserver] [opt [arg "port"]]]
Get the time from an SNTP server. This accepts exactly the same
arguments as [cmd ::time::gettime] except that the default port is
[const 123]. The result is a token as per [cmd ::time::gettime] and
should be handled in the same way.
[para]
Note that it is unlikely that any SNTP server will reply using tcp so
you will require the [package tcludp] or the [package ceptcl]
package. If a suitable package can be loaded then the udp protocol
will be used by default.
[call [cmd ::time::configure] [opt [arg "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.
[list_begin definitions]
[def "[cmd -protocol] [arg number]"]
Set the default network protocol. This defaults to udp if the tcludp
package is available. Otherwise it will use tcp.
[def "[cmd -port] [arg number]"]
Set the default port to use. RFC 868 uses port [const 37], RFC 2030 uses
port [const 123].
[def "[cmd -timeout] [arg number]"]
Set the default timeout value in milliseconds. The default is 10 seconds.
[def "[cmd -command] [arg number]"]
Set a command procedure to be run when a reply is received. The
procedure is called with the time token appended to the argument list.
[def "[cmd -loglevel] [arg number]"]
Set the logging level. The default is 'warning'.
[list_end]
[call [cmd ::time::cget] [arg name]]
Get the current value for the named configuration option.
[call [cmd ::time::unixtime] [arg 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.
[call [cmd ::time::status] [arg token]]
Returns the status flag. For a successfully completed query this will be
[emph ok]. May be [emph error] or [emph timeout] or [emph eof].
See also [cmd ::time::error]
[call [cmd ::time::error] [arg token]]
Returns the error message provided for requests whose status is [emph error].
If there is no error message then an empty string is returned.
[call [cmd ::time::reset] [arg token] [arg [opt reason]]]
Reset or cancel the query optionally specfying the reason to record
for the [cmd error] command.
[call [cmd ::time::wait] [arg token]]
Wait for a query to complete and return the status upon completion.
[call [cmd ::time::cleanup] [arg token]]
Remove all state variables associated with the request.
[list_end]
[example {
% set tok [::time::gettime ntp2a.mcc.ac.uk]
% set t [::time::unixtime $tok]
% ::time::cleanup $tok
}]
[example {
% set tok [::time::getsntp pool.ntp.org]
% set t [::time::unixtime $tok]
% ::time::cleanup $tok
}]
[example {
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
}]
[section AUTHORS]
Pat Thoyts
[vset CATEGORY ntp]
[include ../common-text/feedback.inc]
[manpage_end]
|
