diff --git a/doc/latex/nettime.tex b/doc/latex/nettime.tex index 4e890e2..6b57ede 100644 --- a/doc/latex/nettime.tex +++ b/doc/latex/nettime.tex @@ -1,57 +1,55 @@ -\chapter{Using Time and Daytime Protocol}\label{cha:ntp} -% -\begin{description} -\item[Used files:] nettime.scm nettime-obsolete.scm -\item[Name of the package:] nettime nettime-obsolete -\end{description} -% +\chapter{Time and Daytime}\label{cha:ntp} -\subsection{Overview} -Most Unix hosts provide a Daytime service which sends the current date -and time as a human-readable character string. The daytime service is -typically served on port 13 as both TCP and UDP. +Many Unix hosts provide a RFC~867 Daytime service which sends the +current date and time as a human-readable character string. The +daytime service is typically served on port 13 as both TCP and UDP. -The Time protocol provides a site-independent, machine readable date -and time. A ``time'' consists of the number of seconds since midnight on -1st January 1900. The Time service is typically served on port 37 as -TCP and UDP. The idea is that you can confirm your system's idea of -the time by polling several independent sites on the network. +The RFC~868 Time protocol provides a site-independent, machine +readable date and time. The Time service is typically served +on port 37 as TCP and UDP. The idea is that you can confirm your +system's idea of the time by polling several independent sites on the +network. -\subsection{Procedures} +\section{Daytime} -\begin{defundesc}{net-time}{host tcp/udp}{integer} - Asks \semvar{host} about the current time. \semvar{tcp/udp} is - either \ex{socket\=type/\ob{}stream} or - \ex{socket\=type/\ob{}datagram}, that indicate TCP or UDP - connection, respectively (depends on the server). The number of - second since 1970 is returned, since the time protocol returns the - number of seconds since 1900, whereas Unix time is since 1970. The - difference between both answers is 2208988800. -\end{defundesc} +The \ex{rfc867} structure contains an interface to Daytime protocol. -\begin{defundesc}{net-daytime}{host tcp/udp}{string} - Asks \semvar{host} about the current daytime. \semvar{tcp/udp} is - the same as in \ex{net:time}, indicating to use TCP or UDP. The - host's answer is returned (e.g., ``Thursday, April 4, 2''). -\end{defundesc} +\defun{rfc867-daytime/tcp}{host}{string} +\defunx{rfc867-daytime/udp}{host [timeout-or-\sharpf]}{string-or-\sharpf} +\begin{desc} + These procedures asks \var{host} about the current daytime and + return the host's answer (e.g., ``Thursday, April 4, + 2''). + + \ex{Rfc867-daytime/tcp} uses the TCP variant of the protocol. + \ex{Rfc867-daytime/udp} uses UDP and sends a single request to the + server. It allows the specification of an optional timeout; if not + specified or \sharpf{}, \ex{Rfc867-daytime/udp} will wait + indefinitely for an answer. If the answer from the server doesn't + arrive within the specified time, \ex{rfc867-daytime/udp} returns + \sharpf. +\end{desc} -\subsubsection*{Obsolete procedures} +\section{Time} -Names in further versions of \ex{nettime} contained a colon (`\ex{:}') -after the prefix `\ex{net-}'. This is now changed to a hyphen -('\ex{-}'), accordingly to SUnet's philosophy. If you need the old -names, use the \ex{nettime\=obsolete}-package that maps the old names -to the new ones. +The \ex{rfc868} structure contains an interface to the Time protocol. + +\defun{rfc868-time/tcp}{host}{string} +\defunx{rfc868-time/udp}{host [timeout-or-\sharpf]}{string-or-\sharpf} +\begin{desc} + These procedures asks \var{host} about the current time and return + the host's answer. This is the number of second since 1970, just as + with scsh's \texttt{time} procedure. + + \ex{rfc868-time/tcp} uses the TCP variant of the protocol. + \ex{rfc868-time/udp} uses UDP and sends a single request to the + server. It allows the specification of an optional timeout; if not + specified or \sharpf{}, \ex{rfc868-time/udp} will wait + indefinitely for an answer. If the answer from the server doesn't + arrive within the specified time, \ex{rfc868-time/udp} returns + \sharpf. +\end{desc} -\subsection{Related work} -\begin{itemize} -\item \ex{Time.pm} is a Perl module by Graham Barr -\item RFC~868 describes the Time protocol -\item RFC~867 describes the Daytime protocol in all its glory -\item For a genuinely useful protocol look at the Network Time - Protocol defined in RFC~1305, which allows for the synchronization - of clocks on networked computers. -\end{itemize} %%% Local Variables: %%% mode: latex