cpython-withatomic / Doc / libamoeba.tex

The branch 'legacy-trunk' does not exist.
\chapter{AMOEBA ONLY}

\section{Built-in Module \sectcode{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

Deletes a capability from the Amoeba directory tree.
Argument is the pathname.

Looks up a capability.
Argument is the pathname.
Returns a
object, to which various interesting operations apply, described below.

\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
in the behavior when the pathname already exists:
finds this an error while
allows it, as its name suggests.)

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,
is the capability of your root directory, similar to
in C.

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

Sets the transaction timeout, in milliseconds.
Returns the previous timeout.
Initially, the timeout is set to 2 seconds by the Python interpreter.

\subsection{Capability Operations}

Capabilities are written in a convenient ASCII format, also used by the
Amoeba utilities
{\it c2a}(U)
{\it a2c}(U).
For example:

>>> amoeba.name_lookup('/profile/cap')

The following methods are defined for capability objects.

\renewcommand{\indexsubitem}{(capability method)}
Returns a list of the names of the entries in an Amoeba directory.

\begin{funcdesc}{b_read}{offset\, maxsize}
Reads (at most)
bytes from a bullet file at offset
The data is returned as a string.
EOF is reported as an empty string.

Returns the size of a bullet file.

Like the corresponding
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.)

Returns the standard info string of the object.

Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from
a time server.

Sets the time kept by a time server.