Doc/lib/libamoeba.tex

   1 \chapter{Amoeba Specific Services}
   2
   3 \section{\module{amoeba} ---
   4          Amoeba system support}
   5
   6 \declaremodule{builtin}{amoeba}
   7   \platform{Amoeba}
   8 \modulesynopsis{Functions for the Amoeba operating system.}
   9
  10
  11 This module provides some object types and operations useful for
  12 Amoeba applications.  It is only available on systems that support
  13 Amoeba operations.  RPC errors and other Amoeba errors are reported as
  14 the exception \code{amoeba.error = 'amoeba.error'}.
  15
  16 The module \module{amoeba} defines the following items:
  17
  18 \begin{funcdesc}{name_append}{path, cap}
  19 Stores a capability in the Amoeba directory tree.
  20 Arguments are the pathname (a string) and the capability (a capability
  21 object as returned by
  22 \function{name_lookup()}).
  23 \end{funcdesc}
  24
  25 \begin{funcdesc}{name_delete}{path}
  26 Deletes a capability from the Amoeba directory tree.
  27 Argument is the pathname.
  28 \end{funcdesc}
  29
  30 \begin{funcdesc}{name_lookup}{path}
  31 Looks up a capability.
  32 Argument is the pathname.
  33 Returns a
  34 \dfn{capability}
  35 object, to which various interesting operations apply, described below.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{name_replace}{path, cap}
  39 Replaces a capability in the Amoeba directory tree.
  40 Arguments are the pathname and the new capability.
  41 (This differs from
  42 \function{name_append()}
  43 in the behavior when the pathname already exists:
  44 \function{name_append()}
  45 finds this an error while
  46 \function{name_replace()}
  47 allows it, as its name suggests.)
  48 \end{funcdesc}
  49
  50 \begin{datadesc}{capv}
  51 A table representing the capability environment at the time the
  52 interpreter was started.
  53 (Alas, modifying this table does not affect the capability environment
  54 of the interpreter.)
  55 For example,
  56 \code{amoeba.capv['ROOT']}
  57 is the capability of your root directory, similar to
  58 \code{getcap("ROOT")}
  59 in C.
  60 \end{datadesc}
  61
  62 \begin{excdesc}{error}
  63 The exception raised when an Amoeba function returns an error.
  64 The value accompanying this exception is a pair containing the numeric
  65 error code and the corresponding string, as returned by the C function
  66 \cfunction{err_why()}.
  67 \end{excdesc}
  68
  69 \begin{funcdesc}{timeout}{msecs}
  70 Sets the transaction timeout, in milliseconds.
  71 Returns the previous timeout.
  72 Initially, the timeout is set to 2 seconds by the Python interpreter.
  73 \end{funcdesc}
  74
  75 \subsection{Capability Operations}
  76
  77 Capabilities are written in a convenient \ASCII{} format, also used by the
  78 Amoeba utilities
  79 \emph{c2a}(U)
  80 and
  81 \emph{a2c}(U).
  82 For example:
  83
  84 \begin{verbatim}
  85 >>> amoeba.name_lookup('/profile/cap')
  86 aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
  87 >>>
  88 \end{verbatim}
  89 %
  90 The following methods are defined for capability objects.
  91
  92 \setindexsubitem{(capability method)}
  93 \begin{funcdesc}{dir_list}{}
  94 Returns a list of the names of the entries in an Amoeba directory.
  95 \end{funcdesc}
  96
  97 \begin{funcdesc}{b_read}{offset, maxsize}
  98 Reads (at most)
  99 \var{maxsize}
 100 bytes from a bullet file at offset
 101 \var{offset.}
 102 The data is returned as a string.
 103 EOF is reported as an empty string.
 104 \end{funcdesc}
 105
 106 \begin{funcdesc}{b_size}{}
 107 Returns the size of a bullet file.
 108 \end{funcdesc}
 109
 110 \begin{funcdesc}{dir_append}{}
 111 \funcline{dir_delete}{}
 112 \funcline{dir_lookup}{}
 113 \funcline{dir_replace}{}
 114 Like the corresponding
 115 \samp{name_}*
 116 functions, but with a path relative to the capability.
 117 (For paths beginning with a slash the capability is ignored, since this
 118 is the defined semantics for Amoeba.)
 119 \end{funcdesc}
 120
 121 \begin{funcdesc}{std_info}{}
 122 Returns the standard info string of the object.
 123 \end{funcdesc}
 124
 125 \begin{funcdesc}{tod_gettime}{}
 126 Returns the time (in seconds since the Epoch, in UCT, as for \POSIX) from
 127 a time server.
 128 \end{funcdesc}
 129
 130 \begin{funcdesc}{tod_settime}{t}
 131 Sets the time kept by a time server.
 132 \end{funcdesc}