sunet/doc/latex/dns.tex

175 lines
5.8 KiB
TeX

\chapter{DNS Client Library}\label{cha:dns}
The \ex{dns} structure contains a library for querying DNS servers.
Features:
\begin{itemize}
\item Parsing of \texttt{resolv.conf}, including \texttt{search}
entries. This enables looking up the FQDN of a host.
\end{itemize}
\section{Conditions}
The library defines a set of conditions raised by the procedures of
the library. The supertype of these conditions is \exi{dns-error}.
\defun{dns-error?}{thing}{\boolean}
\begin{desc}
The predicate for \ex{dns-error} conditions.
\end{desc}
\defun{dns-error->string} {dns-error-condition} {\str}
\begin{desc}
Returns a string with the description of the condition.
\end{desc}
\defvarx {dns-format-error} {condition}
\defvarx {dns-server-failure} {condition}
\defvarx {dns-name-error} {condition}
\defvarx {dns-not-implemented} {condition}
\defvarx {dns-refused} {condition}
These conditons correspond to errors returned by the DNS server. They
are all subtypes of the \exi{dns-server-error} condition which in
turn is a subtype of \ex{dns-error}.
\defun{dns-server-error?}{thing}{\boolean}
\begin{desc}
The predicate for \ex{dns-server-error} conditions.
\end{desc}
\defun {dns-format-error?} {thing} {\boolean}
\defunx {dns-server-failure?} {thing} {\boolean}
\defunx {dns-name-error?} {thing} {\boolean}
\defunx {dns-not-implemented?} {thing} {\boolean}
\defunx {dns-refused?} {thing} {\boolean}
\begin{desc}
The type predicates for the conditions above.
\end{desc}
\section{High-level Interface}
\def\ipaddr{\textnormal{IP-address\xspace}}
\def\fqdn{\textnormal{FQDN\xspace}}
\defun{dns-lookup-ip}{\fqdn [nameserver list]}{\fqdn}
\begin{desc}
Given the FQDN of a host, \ex{dns-lookup-ip} returns the IP address.
The optional argument specifes the nameservers to query, it defaults
to the ones found in \texttt{/etc/resolv.conf}. \textbf{always uses
the cache}
\end{desc}
\defun{dns-lookup-ip}{\ipaddr [nameserver list]}{\fqdn}
\begin{desc}
Looks up the FQDN for the given IP address. The optional argument
specifes the nameservers to query, it defaults to the ones found in
\texttt{/etc/resolv.conf}. \textbf{always uses the cache}
\end{desc}
\defun{dns-lookup-nameserver}{name/\ipaddr [nameserver list]}{\ipaddr list}
\begin{desc}
Looks up an authoritative nameserver for a hostname, returns a list
of nameservers. The optional argument specifes the nameservers to
query, it defaults to the ones found in
\texttt{/etc/resolv.conf}\textbf{Why a list if there is only one and
why is there only one for wsi hosts?}\textbf{always uses the cache}
\end{desc}
\defun{dns-lookup-mail-exchanger}{name/\ipaddr [nameserver list]}{\fqdn list}
\begin{desc}
Looks up mail-exchangers for a hostname und returns them in a list
sorted by preference. \textbf{Always uses the cache}\textbf{why is
there only one MX for wsi?}
\end{desc}
\defun{socket-address->fqdn}{socket-address cache?}{\fqdn}
\begin{desc}
Returns the FQDN for of the address bound to argument. The argument
\var{cache?} indicates whether the internal cache may be queried to
obtain the information.
\end{desc}
\defun{maybe-dns-lookup-name}{name}{\ipaddr or \sharpf}
\defunx{maybe-dns-lookup-ip}{\ipaddr}{\fqdn{} or \sharpf}
\begin{desc}
These procedures provide the same functionality as
\ex{dns-lookup-name} and \ex{dns-lookup-ip} but return \sharpf{} in
case of an \ex{dns-error}.
\end{desc}
\defun{host-fqdn} {name/socket-address}{\fqdn}
\defunx{system-fqdn}{}{\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.
\end{desc}
\section{Low-level Interface}
\defun{dns-lookup}{\fqdn/\ipaddr type [nameserver list]}{dns-message}
\begin{desc}
This is the most general way to submit a DNS query. The return value
is a DNS message.\textbf{need to explain dns-message}
\end{desc}
\defun{show-dns-message}{dns-message}{\undefined}
\begin{desc}
Pretty prints a DNS message to standard output.
\textbf{Better return a string}
\end{desc}
\defun{domains-for-search}{}{\str list}
\begin{desc}
Parses \texttt{/etc/resolv.conf} and extracts the domains specified
by the \texttt{search} keyword.
\end{desc}
\section{Host Names}
\defun{is-fqdn?}{\str}{\boolean}
\begin{desc}
Indicates whether the argument matches the grammar for a fully
qualified domain name.
\oops{The current implementation simply searches for a dot in the name}
\end{desc}
\defun{unqualified-hostname}{\str}{\boolean}
\begin{desc}
Returns true if the argument matches the grammar for a unqualified
host name
\oops{This procedure isn't implemented yet}
\end{desc}
\section{Parsing \texttt{/etc/resolv.conf}}
\defun{resolv.conf}{}{symbol$\rightarrow$string alist}
\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}.
Note that the library caches the contents of
\texttt{/etc/resolv.conv} and \ex{resolv.conf} only really opens the
file if its modification time is more recent than the creation time
of the cache.
\end{desc}
\defun{parse-resolv.conf!}{}{\undefined}
\begin{desc}
Parses the contents of \texttt{/etc/resolv.conv} and updates the
internal cache of the library.
\end{desc}
\defun{dns-find-nameserver-list}{}{\fqdn list}
\begin{desc}
Returns a list of nameservers from \texttt{/etc/resolv.conf}
\end{desc}
\defun{dns-find-nameserver}{}{\fqdn}
\begin{desc}
Returns the first nameservers found in \texttt{/etc/resolv.conf}.
\ex{dns-find-nameserver} raises \ex{no-nameservers} if
\texttt{/etc/resolv.conf} does not contain a \texttt{nameserver}
entry.
\end{desc}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "man"
%%% End: