Restructured library documentation

Doc/lib/libamoeba.tex

@@ -0,0 +1,128 @@
+\chapter{AMOEBA ONLY}
+
+\section{Built-in Module \sectcode{amoeba}}
+
+\bimodindex{amoeba}
+This module provides some object types and operations useful for
+Amoeba applications.  It is only available on systems that support
+Amoeba operations.  RPC errors and other Amoeba errors are reported as
+the exception \code{amoeba.error = 'amoeba.error'}.
+
+The module \code{amoeba} defines the following items:
+
+\renewcommand{\indexsubitem}{(in module amoeba)}
+\begin{funcdesc}{name_append}{path\, cap}
+Stores a capability in the Amoeba directory tree.
+Arguments are the pathname (a string) and the capability (a capability
+object as returned by
+\code{name_lookup()}).
+\end{funcdesc}
+
+\begin{funcdesc}{name_delete}{path}
+Deletes a capability from the Amoeba directory tree.
+Argument is the pathname.
+\end{funcdesc}
+
+\begin{funcdesc}{name_lookup}{path}
+Looks up a capability.
+Argument is the pathname.
+Returns a
+\dfn{capability}
+object, to which various interesting operations apply, described below.
+\end{funcdesc}
+
+\begin{funcdesc}{name_replace}{path\, cap}
+Replaces a capability in the Amoeba directory tree.
+Arguments are the pathname and the new capability.
+(This differs from
+\code{name_append()}
+in the behavior when the pathname already exists:
+\code{name_append()}
+finds this an error while
+\code{name_replace()}
+allows it, as its name suggests.)
+\end{funcdesc}
+
+\begin{datadesc}{capv}
+A table representing the capability environment at the time the
+interpreter was started.
+(Alas, modifying this table does not affect the capability environment
+of the interpreter.)
+For example,
+\code{amoeba.capv['ROOT']}
+is the capability of your root directory, similar to
+\code{getcap("ROOT")}
+in C.
+\end{datadesc}
+
+\begin{excdesc}{error}
+The exception raised when an Amoeba function returns an error.
+The value accompanying this exception is a pair containing the numeric
+error code and the corresponding string, as returned by the C function
+\code{err_why()}.
+\end{excdesc}
+
+\begin{funcdesc}{timeout}{msecs}
+Sets the transaction timeout, in milliseconds.
+Returns the previous timeout.
+Initially, the timeout is set to 2 seconds by the Python interpreter.
+\end{funcdesc}
+
+\subsection{Capability Operations}
+
+Capabilities are written in a convenient ASCII format, also used by the
+Amoeba utilities
+{\it c2a}(U)
+and
+{\it a2c}(U).
+For example:
+
+\bcode\begin{verbatim}
+>>> amoeba.name_lookup('/profile/cap')
+aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
+>>> 
+\end{verbatim}\ecode
+
+The following methods are defined for capability objects.
+
+\renewcommand{\indexsubitem}{(capability method)}
+\begin{funcdesc}{dir_list}{}
+Returns a list of the names of the entries in an Amoeba directory.
+\end{funcdesc}
+
+\begin{funcdesc}{b_read}{offset\, maxsize}
+Reads (at most)
+\var{maxsize}
+bytes from a bullet file at offset
+\var{offset.}
+The data is returned as a string.
+EOF is reported as an empty string.
+\end{funcdesc}
+
+\begin{funcdesc}{b_size}{}
+Returns the size of a bullet file.
+\end{funcdesc}
+
+\begin{funcdesc}{dir_append}{}
+\funcline{dir_delete}{}\ 
+\funcline{dir_lookup}{}\ 
+\funcline{dir_replace}{}
+Like the corresponding
+\samp{name_}*
+functions, but with a path relative to the capability.
+(For paths beginning with a slash the capability is ignored, since this
+is the defined semantics for Amoeba.)
+\end{funcdesc}
+
+\begin{funcdesc}{std_info}{}
+Returns the standard info string of the object.
+\end{funcdesc}
+
+\begin{funcdesc}{tod_gettime}{}
+Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from
+a time server.
+\end{funcdesc}
+
+\begin{funcdesc}{tod_settime}{t}
+Sets the time kept by a time server.
+\end{funcdesc}