


ntp_time(n)          Network Time Facilities          ntp_time(n)


______________________________________________________________________________

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.



ntp                           1.2.1                             1





ntp_time(n)          Network Time Facilities          ntp_time(n)


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





ntp                           1.2.1                             2





ntp_time(n)          Network Time Facilities          ntp_time(n)


       ::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  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                             3


