ntp_time(n)

💖 ntp_time(n) — the Network Time Facilities glow-up 💖

okay bestie, sit down, grab your boba, because we're about to make your Tcl app chronologically correct ✨ This page lives in the Network Time Facilities manual, and it's literally just vibes about asking a server what time it is. Iconic behavior.

---

✨ NAME ✨

ntp_time — the Tcl Time Service Client. that's it, that's the name, she's a client, she gets time, she serves 💅

---

🎀 SYNOPSIS 🎀

package require Tcl 8.5 9

package require time ?1.2.2?

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

like… she said "here's my whole resume" and honestly? slay 🫶

---

🌸 DESCRIPTION 🌸

So this package is a client for the RFC 868 TIME protocol (http://www.rfc-editor.org/rfc/rfc868.txt) and also a lil minimal client for the RFC 2030 Simple Network Time Protocol (http://www.rfc-editor.org/rfc/rfc2030.txt). Two protocols, one package, main character energy fr fr 👑

RFC 868 gives you the time as seconds since 1 January 1900, and it'll hand that over to either tcp or udp clients. RFC 2030 also gives you that same time — but it also provides a fractional part, and no cap, this client does not use that fractional part. we said thanks but no thanks 🙈

---

💅 COMMANDS 💅

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

Get the time from timeserver. You can specify any of the options listed for the configure command right here, no gatekeeping.

This command returns a token, and you must use that token with the remaining commands in this package. Once you're done with it, you should use cleanup to release all resources — be a good citizen, bestie 🧹

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 the default port is 123. The result is a token just like ::time::gettime gives you, and you handle it the same way.

heads up: it is unlikely that any SNTP server will reply using tcp, so you're gonna need the tcludp or the ceptcl package. If a suitable package can be loaded, then the udp protocol gets used by default. ✨

::time::configure ?options?

Called with no arguments, this command returns all the current configuration options and values. Otherwise, call it with pairs of option name and value. very "tell me everything" / "okay here's the tea" energy.

• -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. one option, one answer, no small talk 💅

::time::unixtime token

Format the returned time for the unix epoch. Here's the drama: 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. it's giving translator, it's giving bilingual queen 🌈

::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. vibe check, basically 🦋

::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. (empty string = she has nothing to say and honestly, respect)

::time::reset token ?reason?

Reset or cancel the query, optionally specfying the reason to record for the error command. (yes, "specfying" — that's how the original spells it, and we don't correct our friends 😭)

::time::wait token

Wait for a query to complete and return the status upon completion. she will sit there until the answer arrives. patient. loyal. lowkey iconic.

::time::cleanup token

Remove all state variables associated with the request. bye babe, you're released 🎀

---

🍓 the examples, because you KNOW we need them 🍓

% 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

and the callback glow-up version:

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

not me writing a whole proc in the middle of the manual… and it ATE 🔥

---

👑 AUTHORS 👑

Pat Thoyts — the original author, the blueprint, we stan 💜

---

💀 BUGS, IDEAS, FEEDBACK 💀

Real talk, bestie: this document, and the package it describes, will undoubtedly contain bugs and other problems. Not a vibe, but it's the truth. Please report such in the category ntp of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. Please also report any ideas for enhancements you may have for either package and/or documentation — we want all the thoughts, all the notes, all the chaos 🫶

When proposing code changes, please provide unified diffs, i.e. the output 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. (yes, the left-most one. don't make me say it twice 💅)

---

🌈 SEE ALSO 🌈

• ntp

---

⭐ KEYWORDS ⭐

NTP, SNTP, rfc 2030, rfc 868, time

---

🧚 CATEGORY 🧚

Networking

---

🎀 COPYRIGHT 🎀

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

---

okay and finally, the lil sign-off 💖 this whole page is served up by tcllib, version 1.2.2, and it's ntp_time(n) — so go forth, ask the internet what time it is, and clean up your tokens afterwards. bye bestie, mwah 💅✨🦋