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

More low-level procedures.

This commit is contained in:
mainzelm 2003-01-22 14:13:40 +00:00
parent 27f6c5a832
commit 08bf247510
1 changed files with 50 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
doc/latex/dns.tex
View File

@ -71,7 +71,7 @@ the library. The supertype of these conditions is \exi{dns-error}.
\section{High-level Interface}
\def\ipaddr{\textnormal{IP-address\xspace}}
\def\fqdn{\textnormal{FQDN\xspace}}
\def\fqdn{\textnormal{FQDN}\xspace}
The library uses an internal store to cache data obtained from DNS
servers. All procedures take a boolean flag \var{use-cache?} that
@ -87,7 +87,7 @@ The library is further capable of parsing the contents of
\texttt{/etc/resolv.conf} (see Section~\ref{sec:dns-rc}). The
nameservers listed there are the default value for the optional
argument \var{nameserver list} which many procedures of the library
possess.
possess. \var{nameserver} is either a \ipaddr or a dotted IP string.
\defun{dns-lookup-ip}{\fqdn [nameserver list][use-cache?]}{\fqdn}
\begin{desc}
@ -134,17 +134,42 @@ possess.
\defun{host-fqdn} {name/socket-address [nameserver list][use-cache?]}{\fqdn}
\defunx{system-fqdn}{[nameserver list][use-cache?]}{\fqdn}
\begin{desc}
\ex{host-fqdn} returns the fully qualified domain name (FQDN) for its
argument which can be either a unqualified host name or a socket
address. The procedure \ex{system-fqdn} returns the FQDN of the
current host.\oops{optional arguments not implemented yet}
\ex{host-fqdn} returns the fully qualified domain name (FQDN) for
its argument which can be either a unqualified host name or a socket
address. The procedure \ex{system-fqdn} returns the FQDN of the
current host. These procedures use a list of domain names obtained
from \texttt{/etc/resolv.conf} to the generate FQDNs and try to
resolve these FQDNs.\oops{optional arguments not implemented yet}
\end{desc}
\section{Low-level Interface}
\defun{dns-lookup}{\fqdn/\ipaddr type [nameserver list][use-cache?]}{dns-message}
This section describes a set of data structures and procedures which
directly correspond to the data flow of the DNS protocol. The central
entity is a \var{message}, the abstraction of the packet sent to the
server or received from the server (The DNS protocol uses the same
data format for both directions). A \var{dns-message} encapsulates the
query message sent to the server, the response message received from
the server, and some additional information the library gathered while
generating the \var{dns-message}.
\defunx{dns-get-information}{message protocol answer-okay? [nameserver
list][use-cache?]}{dns-message}
\begin{desc}
This is the most general way to submit a DNS query. The return value
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
{'udp}. After receiving the reply, \ex{dns-get-information} applies
the predicate \var{answer-okay?} to the message. If it returns
\sharpf and the answer is not authoritative additional name servers
sent with the reply are checked until an authoritative answer is
found. If the predicate returns \sharpf but the answer is
authoritative a \var{bad-address} condition is signalled.
\oops{order of parameters differs in implementation}
\end{desc}
\defun{dns-lookup}{\fqdn{}/\ipaddr type [nameserver list][use-cache?]}{dns-message}
\begin{desc}
Convenient shortcut to submit a DNS query. The return value
is a \ex{dns-message} structure:\oops{optional arguments not implemented yet}
\end{desc}
@ -160,7 +185,7 @@ possess.
library took the reply from the cache, which protocol was used and
to which nameservers the query was sent.
\end{desc}
\defun{pretty-print-dns-message}{dns-message [output-port]}{\undefined}
\begin{desc}
Pretty prints a DNS message to \var{out-port} which defaults to the
@ -183,6 +208,18 @@ possess.
returns the actual data sent over the network.
\end{desc}
\defun{make-query-message header}{header question [questions]}{message}
\begin{desc}
The procedure generates a message the supplied questions,
\var{header}, and the standard message values for queries.
\end{desc}
\defun{make-simple-query-message}{name type class}{message}
\begin{desc}
This simplified constructor generates a message with one question
which is built from the parameters, and the standard header flags
for queries and the standard message values for queries.
\end{desc}
\defun{header?}{thing}{\boolean}
\defunx{header-id}{header}{number}
\defunx{header-flags}{header}{flags}
@ -220,8 +257,7 @@ possess.
A question sent to the DNS server.
\end{desc}
The type and class of the question and answer are elements of
enumerated types: \textbf{class doesn't start at 0}
enumerated types:
\dfn{message-class}{class-name}{message-class}{syntax}
\defunx{message-class?}{thing}{\boolean}
\defunx{message-class-name}{message-class}{symbol}
@ -332,7 +368,7 @@ The possible names for the classes are:
\begin{desc}
A zone of authority resource record.
\end{desc}
The protocol specifies other possiple values for the \texttt{rr-data}
The protocol specifies other possible values for the \texttt{rr-data}
field but we where no able to find test cases for them.
@ -381,7 +417,7 @@ field but we where no able to find test cases for them.
\begin{desc}
Returns the contents of \texttt{/etc/resolv.conv} as an alist with
the possible keys \texttt{nameserver}, \texttt{domain},
\texttt{search}, \texttt{sortlist}, \texttt{options}.
\texttt{search}, \texttt{sortlist} and \texttt{options}.
Note that the library caches the contents of
\texttt{/etc/resolv.conv} and \ex{resolv.conf} only really opens the
@ -404,7 +440,7 @@ field but we where no able to find test cases for them.
\texttt{/etc/resolv.conf} does not contain a \texttt{nameserver}
entry.
\end{desc}
\defun{domains-for-search}{}{\str list}
\defun{domains-for-search}{}{\str{} list}
\begin{desc}
Parses \texttt{/etc/resolv.conf} and extracts the domains specified
by the \texttt{search} keyword.