scsh-conservatory
/
sunet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Most of Mike's corrections.

This commit is contained in:
mainzelm 2003-02-07 17:21:23 +00:00
parent 44322977fc
commit a4f7e6f337
1 changed files with 56 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
doc/latex/dns.tex
View File

@ -70,8 +70,8 @@ the library. The supertype of these conditions is \exi{dns-error}.
\end{desc} \end{desc}
\section{High-level Interface} \section{High-level Interface}
\def\ipaddr{\textnormal{IP-address\xspace}} \def\ipaddr{IP-address\xspace}
\def\fqdn{\textnormal{FQDN}\xspace} \def\fqdn{FQDN\xspace}
The library uses an internal store to cache data obtained from DNS The library uses an internal store to cache data obtained from DNS
servers. All procedures take a boolean flag \var{use-cache?} that servers. All procedures take a boolean flag \var{use-cache?} that
@ -87,9 +87,9 @@ The library is further capable of parsing the contents of
\texttt{/etc/resolv.conf} (see Section~\ref{sec:dns-rc}). The \texttt{/etc/resolv.conf} (see Section~\ref{sec:dns-rc}). The
nameservers listed there are the default value for the optional nameservers listed there are the default value for the optional
argument \var{nameserver list} which many procedures of the library argument \var{nameserver list} which many procedures of the library
possess. \var{nameserver} is either a \ipaddr or a dotted IP string. accept. \var{Nameserver} is either a \ipaddr or a dotted IP string.
\defun{dns-lookup-ip}{\fqdn [nameserver list][use-cache?]}{\fqdn} \defun{dns-lookup-name}{\fqdn [nameserver list][use-cache?]}{\ipaddr}
\begin{desc} \begin{desc}
Given the FQDN of a host, \ex{dns-lookup-ip} returns the IP address. Given the FQDN of a host, \ex{dns-lookup-ip} returns the IP address.
The optional argument specifes the name servers to query, it defaults The optional argument specifes the name servers to query, it defaults
@ -137,7 +137,7 @@ possess. \var{nameserver} is either a \ipaddr or a dotted IP string.
\ex{host-fqdn} returns the fully qualified domain name (FQDN) for \ex{host-fqdn} returns the fully qualified domain name (FQDN) for
its argument which can be either a unqualified host name or a socket its argument which can be either a unqualified host name or a socket
address. The procedure \ex{system-fqdn} returns the FQDN of the address. The procedure \ex{system-fqdn} returns the FQDN of the
current host. These procedures use a list of domain names obtained local host. These procedures use a list of domain names obtained
from \texttt{/etc/resolv.conf} to the generate FQDNs and try to from \texttt{/etc/resolv.conf} to the generate FQDNs and try to
resolve these FQDNs.\oops{optional arguments not implemented yet} resolve these FQDNs.\oops{optional arguments not implemented yet}
\end{desc} \end{desc}
@ -157,16 +157,25 @@ generating the \var{dns-message}.
list][use-cache?]}{dns-message} list][use-cache?]}{dns-message}
\begin{desc} \begin{desc}
Most general way to submit a DNS query. The message is sent to the Most general way to submit a DNS query. The message is sent to the
name servers via \var{protocol} which can be either \ex{'tcp} or name servers via \var{protocol} which can be either
{'udp}. After receiving the reply, \ex{dns-get-information} applies \ex{(network-procotcol tcp)} or {(network-protocol udp)}, both
the predicate \var{answer-okay?} to the message. If it returns members of of the enumerated type \ex{network-protocol}. After
\sharpf and the answer is not authoritative additional name servers receiving the reply, \ex{dns-get-information} applies the predicate
sent with the reply are checked until an authoritative answer is \var{answer-okay?} to the message. If it returns \sharpf{} and the
found. If the predicate returns \sharpf but the answer is answer is not authoritative additional name servers sent with the
authoritative a \var{bad-address} condition is signalled. reply are checked until an authoritative answer is found. If the
\oops{order of parameters differs in implementation} predicate returns \sharpf{} but the answer is authoritative a
\var{bad-address} condition is signalled. \oops{order of parameters
differs in implementation}
\end{desc} \end{desc}
\dfn{network-protocol}{protocol-name}{network-protocol}{syntax}
\defunx{network-protocol?}{thing}{\boolean}
\begin{desc}
Constructor and predicate for the enumerated type
\ex{network-protocol} with the possible protocol names \ex{tcp} and
\ex{udp}.
\end{desc}
\defun{dns-lookup}{\fqdn{}/\ipaddr type [nameserver list][use-cache?]}{dns-message} \defun{dns-lookup}{\fqdn{}/\ipaddr type [nameserver list][use-cache?]}{dns-message}
\begin{desc} \begin{desc}
Convenient shortcut to submit a DNS query. The return value Convenient shortcut to submit a DNS query. The return value
@ -177,7 +186,7 @@ generating the \var{dns-message}.
\defunx{dns-message-query}{dns-message}{message} \defunx{dns-message-query}{dns-message}{message}
\defunx{dns-message-reply}{dns-message}{message} \defunx{dns-message-reply}{dns-message}{message}
\defunx{dns-message-cache?}{dns-message}{\boolean} \defunx{dns-message-cache?}{dns-message}{\boolean}
\defunx{dns-message-protocol}{dns-message}{'udp or 'tcp} \defunx{dns-message-protocol}{dns-message}{protocol}
\defunx{dns-message-tried-nameservers}{dns-message}{} \defunx{dns-message-tried-nameservers}{dns-message}{}
\begin{desc} \begin{desc}
A \var{dns-message} records the query sent to the server and the A \var{dns-message} records the query sent to the server and the
@ -195,16 +204,16 @@ generating the \var{dns-message}.
\defun{message?}{thing}{\boolean}{} \defun{message?}{thing}{\boolean}{}
\defunx{message-header}{message}{header} \defunx{message-header}{message}{header}
\defunx{message-questions}{message}{question list} \defunx{message-questions}{message}{question list}
\defunx{message-answers}{message}{rr list} \defunx{message-answers}{message}{resource-record list}
\defunx{message-nameservers}{message}{rr list} \defunx{message-nameservers}{message}{resource-record list}
\defunx{message-additionals}{message}{rr list} \defunx{message-additionals}{message}{resource-record list}
\defunx{message-source}{message}{char list} \defunx{message-source}{message}{char list}
\begin{desc} \begin{desc}
A \ex{message} represents the data sent to the DNS server or A \ex{message} represents the data sent to the DNS server or
received from the DNS server. The DNS protocol uses the same message received from the DNS server. The DNS protocol uses the same message
format for queries and replies. In queries only the header and the format for queries and replies. In queries only the header and the
questions is present, a reply may contain answers, name servers and questions is present, a reply may contain answers, name servers and
and additional informations as resource records. \ex{message-source} and additional informations as resource records. \ex{Message-source}
returns the actual data sent over the network. returns the actual data sent over the network.
\end{desc} \end{desc}
@ -263,7 +272,7 @@ enumerated types:
\defunx{message-class-name}{message-class}{symbol} \defunx{message-class-name}{message-class}{symbol}
\defunx{message-class-number}{message-class}{number} \defunx{message-class-number}{message-class}{number}
\begin{desc} \begin{desc}
\ex{message-class} constructs a member of the enumeration, \ex{message-class} constructs a member of the enumerated type,
\ex{message-class?} is the type predicate, \ex{message-class-name} \ex{message-class?} is the type predicate, \ex{message-class-name}
returns the symbol and \ex{message-class-number} the number used for returns the symbol and \ex{message-class-number} the number used for
the class in the DNS protocol. the class in the DNS protocol.
@ -313,62 +322,62 @@ The possible names for the classes are:
\label{tab:message-types} \label{tab:message-types}
\end{table} \end{table}
\defun{rr?}{thing}{\boolean} \defun{resource-record?}{thing}{\boolean}
\defunx{rr-name}{rr}{\str} \defunx{resource-record-name}{rr}{\str}
\defunx{rr-type}{rr}{message-type} \defunx{resource-record-type}{rr}{message-type}
\defunx{rr-class}{rr}{message-class} \defunx{resource-record-class}{rr}{message-class}
\defunx{rr-ttl}{rr}{number} \defunx{resource-record-ttl}{rr}{number}
\defunx{rr-data}{rr}{rr-data-X} \defunx{resource-record-data}{rr}{resource-record-data-X}
\begin{desc} \begin{desc}
A resource record as returned from the DNS server. The actual data A resource record as returned from the DNS server. The actual data
of the record is stored in the \texttt{rr-data} field. of the record is stored in the \texttt{resource-record-data} field.
\end{desc} \end{desc}
\defun{rr-data-a?}{thing}{\boolean} \defun{resource-record-data-a?}{thing}{\boolean}
\defunx{rr-data-a-ip}{rr-data-a}{\ipaddr} \defunx{resource-record-data-a-ip}{resource-record-data-a}{\ipaddr}
\begin{desc} \begin{desc}
An address resource record which holds an internet address. An address resource record which holds an internet address.
\end{desc} \end{desc}
\defun{rr-data-ns?}{thing}{\boolean} \defun{resource-record-data-ns?}{thing}{\boolean}
\defunx{rr-data-ns-name}{rr-data-ns}{\fqdn} \defunx{resource-record-data-ns-name}{resource-record-data-ns}{\fqdn}
\begin{desc} \begin{desc}
A name server resource record containing the FQDN of the name server. A name server resource record containing the FQDN of the name server.
\end{desc} \end{desc}
\defun{rr-data-cname?}{thing}{\boolean} \defun{resource-record-data-cname?}{thing}{\boolean}
\defunx{rr-data-cname}{rr-data-cname}{\fqdn} \defunx{resource-record-data-cname}{resource-record-data-cname}{\fqdn}
\begin{desc} \begin{desc}
A canonical name resource record which contains the canonical or A canonical name resource record which contains the canonical or
primary name of the owner. primary name of the owner.
\end{desc} \end{desc}
\defun{rr-data-mx?}{thing}{\boolean} \defun{resource-record-data-mx?}{thing}{\boolean}
\defunx{rr-data-mx-preference}{rr-data-mx}{number} \defunx{resource-record-data-mx-preference}{resource-record-data-mx}{number}
\defunx{rr-data-mx-exchanger}{rr-data-mx}{\fqdn} \defunx{resource-record-data-mx-exchanger}{resource-record-data-mx}{\fqdn}
\begin{desc} \begin{desc}
A mail exchange resource record with the preference and the FQDN of A mail exchange resource record with the preference and the FQDN of
a host willing to act as a mail exchange. a host willing to act as a mail exchange.
\end{desc} \end{desc}
\defun{rr-data-ptr?}{thing}{\boolean} \defun{resource-record-data-ptr?}{thing}{\boolean}
\defunx{rr-data-ptr-name}{rr-data-ptr}{\str} \defunx{resource-record-data-ptr-name}{resource-record-data-ptr}{\str}
\begin{desc} \begin{desc}
A pointer resource record which points to some other domain name. A pointer resource record which points to some other domain name.
\end{desc} \end{desc}
\defun{rr-data-soa?}{thing}{\boolean} \defun{resource-record-data-soa?}{thing}{\boolean}
\defunx{rr-data-soa-mname}{rr-data-soa}{\fqdn} \defunx{resource-record-data-soa-mname}{resource-record-data-soa}{\fqdn}
\defunx{rr-data-soa-rname}{rr-data-soa}{\fqdn} \defunx{resource-record-data-soa-rname}{resource-record-data-soa}{\fqdn}
\defunx{rr-data-soa-serial}{rr-data-soa}{number} \defunx{resource-record-data-soa-serial}{resource-record-data-soa}{number}
\defunx{rr-data-soa-refresh}{rr-data-soa}{number} \defunx{resource-record-data-soa-refresh}{resource-record-data-soa}{number}
\defunx{rr-data-soa-retry}{rr-data-soa}{number} \defunx{resource-record-data-soa-retry}{resource-record-data-soa}{number}
\defunx{rr-data-soa-expire}{rr-data-soa}{number} \defunx{resource-record-data-soa-expire}{resource-record-data-soa}{number}
\defunx{rr-data-soa-minimum}{rr-data-soa}{number} \defunx{resource-record-data-soa-minimum}{resource-record-data-soa}{number}
\begin{desc} \begin{desc}
A zone of authority resource record. A start of a zone of authority resource record.
\end{desc} \end{desc}
The protocol specifies other possible values for the \texttt{rr-data} The protocol specifies other possible values for the \texttt{resource-record-data}
field but we where no able to find test cases for them. field but we where no able to find test cases for them.