The final bit of my Mac documentation.

2 files changed, 232 insertions, 0 deletions

diff --git a/Doc/libmacdnr.tex b/Doc/libmacdnr.tex
new file mode 100644
index 0000000..ca75971
--- /dev/null
+++ b/Doc/libmacdnr.tex
@@ -0,0 +1,116 @@
+
+\section{Built-in module \sectcode{macdnr}}
+\bimodindex{macdnr}
+
+This module provides an interface to the Macintosh Domain Name
+Resolver. It is usually used in conjunction with the \var{mactcp} module, to
+map hostnames to IP-addresses.
+
+The \code{macdnr} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module macdnr)}
+
+\begin{funcdesc}{Open}{\optional{filename}}
+Open the domain name resolver extension. If \var{filename} is given it
+should be the pathname of the extension, otherwise a default is
+used. Normally, this call is not needed since the other calls will
+open the extension automatically.
+\end{funcdesc}
+
+\begin{funcdesc}{Close}{}
+Close the resolver extension. Again, not needed for normal use.
+\end{funcdesc}
+
+\begin{funcdesc}{StrToAddr}{hostname}
+Look up the IP address for \var{hostname}. This call returns a dnr
+result object of the ``address'' variation.
+\end{funcdesc}
+
+\begin{funcdesc}{AddrToName}{addr}
+Do a reverse lookup on the 32-bit integer IP-address
+\var{addr}. Returns a dnr result object of the ``address'' variation.
+\end{funcdesc}
+
+\begin{funcdesc}{AddrToStr}{addr}
+Convert the 32-bit integer IP-address \var{addr} to a dotted-decimal
+string. Returns the string.
+\end{funcdesc}
+
+\begin{funcdesc}{HInfo}{hostname}
+Query the nameservers for a \code{HInfo} record for host
+\var{hostname}. These records contain hardware and software
+information about the machine in question (if they are available in
+the first place). Returns a dnr result object of the ``hinfo''
+variety.
+\end{funcdesc}
+
+\begin{funcdesc}{MXInfo}{domain}
+Query the nameservers for a mail exchanger for \var{domain}. This is
+the hostname of a host willing to accept SMTP mail for the given
+domain. Returns a dnr result object of the ``mx'' variety.
+\end{funcdesc}
+
+\subsection{dnr result object}
+
+Since the DNR calls all execute asynchronously you do not get the
+results back immedeately. In stead, you get a dnr result object. You
+can check this object to see whether the query is complete, and access
+its attributes to obtain the information when it is.
+
+Alternatively, you can also reference the result attributes directly,
+this will result in an implicit wait for the query to complete.
+
+The \var{rtnCode} and \var{cname} attributes are always available, the
+others depend on the type of query (address, hinfo or mx).
+
+\renewcommand{\indexsubitem}{(dnr result object method)}
+
+% Add args, as in {arg1\, arg2 \optional{\, arg3}}
+\begin{funcdesc}{wait}{}
+Wait for the query to complete.
+\end{funcdesc}
+
+% Add args, as in {arg1\, arg2 \optional{\, arg3}}
+\begin{funcdesc}{isdone}{}
+Return 1 if the query is complete.
+\end{funcdesc}
+
+\begin{datadesc}{rtnCode}
+The error code returned by the query.
+\end{datadesc}
+
+\begin{datadesc}{cname}
+The canonical name of the host that was queried.
+\end{datadesc}
+
+\begin{datadesc}{ip0}
+\dataline{ip1}
+\dataline{ip2}
+\dataline{ip3}
+At most four integer IP addresses for this host. Unused entries are
+zero. Valid only for address queries.
+\end{datadesc}
+
+\begin{datadesc}{cpuType}
+\dataline{osType}
+Textual strings giving the machine type an OS name. Valid for hinfo
+queries.
+\end{datadesc}
+
+\begin{datadesc}{exchange}
+The name of a mail-exchanger host. Valid for mx queries.
+\end{datadesc}
+
+\begin{datadesc}{preference}
+The preference of this mx record. Not too useful, since the Macintosh
+will only return a single mx record. Mx queries only.
+\end{datadesc}
+
+The simplest way to use the module to convert names to dotted-decimal
+strings, without worrying about idle time, etc:
+\begin{verbatim}
+>>> def gethostname(name):
+...     import macdnr
+...     dnrr = macdnr.StrToAddr(name)
+...     return macdnr.AddrToStr(dnrr.ip0)
+\end{verbatim}
diff --git a/Doc/mac/libmacdnr.tex b/Doc/mac/libmacdnr.tex
new file mode 100644
index 0000000..ca75971
--- /dev/null
+++ b/Doc/mac/libmacdnr.tex
@@ -0,0 +1,116 @@
+
+\section{Built-in module \sectcode{macdnr}}
+\bimodindex{macdnr}
+
+This module provides an interface to the Macintosh Domain Name
+Resolver. It is usually used in conjunction with the \var{mactcp} module, to
+map hostnames to IP-addresses.
+
+The \code{macdnr} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module macdnr)}
+
+\begin{funcdesc}{Open}{\optional{filename}}
+Open the domain name resolver extension. If \var{filename} is given it
+should be the pathname of the extension, otherwise a default is
+used. Normally, this call is not needed since the other calls will
+open the extension automatically.
+\end{funcdesc}
+
+\begin{funcdesc}{Close}{}
+Close the resolver extension. Again, not needed for normal use.
+\end{funcdesc}
+
+\begin{funcdesc}{StrToAddr}{hostname}
+Look up the IP address for \var{hostname}. This call returns a dnr
+result object of the ``address'' variation.
+\end{funcdesc}
+
+\begin{funcdesc}{AddrToName}{addr}
+Do a reverse lookup on the 32-bit integer IP-address
+\var{addr}. Returns a dnr result object of the ``address'' variation.
+\end{funcdesc}
+
+\begin{funcdesc}{AddrToStr}{addr}
+Convert the 32-bit integer IP-address \var{addr} to a dotted-decimal
+string. Returns the string.
+\end{funcdesc}
+
+\begin{funcdesc}{HInfo}{hostname}
+Query the nameservers for a \code{HInfo} record for host
+\var{hostname}. These records contain hardware and software
+information about the machine in question (if they are available in
+the first place). Returns a dnr result object of the ``hinfo''
+variety.
+\end{funcdesc}
+
+\begin{funcdesc}{MXInfo}{domain}
+Query the nameservers for a mail exchanger for \var{domain}. This is
+the hostname of a host willing to accept SMTP mail for the given
+domain. Returns a dnr result object of the ``mx'' variety.
+\end{funcdesc}
+
+\subsection{dnr result object}
+
+Since the DNR calls all execute asynchronously you do not get the
+results back immedeately. In stead, you get a dnr result object. You
+can check this object to see whether the query is complete, and access
+its attributes to obtain the information when it is.
+
+Alternatively, you can also reference the result attributes directly,
+this will result in an implicit wait for the query to complete.
+
+The \var{rtnCode} and \var{cname} attributes are always available, the
+others depend on the type of query (address, hinfo or mx).
+
+\renewcommand{\indexsubitem}{(dnr result object method)}
+
+% Add args, as in {arg1\, arg2 \optional{\, arg3}}
+\begin{funcdesc}{wait}{}
+Wait for the query to complete.
+\end{funcdesc}
+
+% Add args, as in {arg1\, arg2 \optional{\, arg3}}
+\begin{funcdesc}{isdone}{}
+Return 1 if the query is complete.
+\end{funcdesc}
+
+\begin{datadesc}{rtnCode}
+The error code returned by the query.
+\end{datadesc}
+
+\begin{datadesc}{cname}
+The canonical name of the host that was queried.
+\end{datadesc}
+
+\begin{datadesc}{ip0}
+\dataline{ip1}
+\dataline{ip2}
+\dataline{ip3}
+At most four integer IP addresses for this host. Unused entries are
+zero. Valid only for address queries.
+\end{datadesc}
+
+\begin{datadesc}{cpuType}
+\dataline{osType}
+Textual strings giving the machine type an OS name. Valid for hinfo
+queries.
+\end{datadesc}
+
+\begin{datadesc}{exchange}
+The name of a mail-exchanger host. Valid for mx queries.
+\end{datadesc}
+
+\begin{datadesc}{preference}
+The preference of this mx record. Not too useful, since the Macintosh
+will only return a single mx record. Mx queries only.
+\end{datadesc}
+
+The simplest way to use the module to convert names to dotted-decimal
+strings, without worrying about idle time, etc:
+\begin{verbatim}
+>>> def gethostname(name):
+...     import macdnr
+...     dnrr = macdnr.StrToAddr(name)
+...     return macdnr.AddrToStr(dnrr.ip0)
+\end{verbatim}