Merge branch 'maint'

1 files changed, 447 insertions, 422 deletions

diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml
index 285a2402b8..6d70fb3475 100644
--- a/lib/erl_interface/doc/src/registry.xml
+++ b/lib/erl_interface/doc/src/registry.xml
@@ -11,7 +11,7 @@
       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at
- 
+
           http://www.apache.org/licenses/LICENSE-2.0
 
       Unless required by applicable law or agreed to in writing, software
@@ -19,7 +19,7 @@
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.
-    
+
     </legalnotice>
 
     <title>registry</title>
@@ -28,457 +28,585 @@
     <docno></docno>
     <approved>Gordon Beaton</approved>
     <checked>Gordon Beaton</checked>
-    <date>980707</date>
+    <date>1998-07-07</date>
     <rev>A</rev>
-    <file>registry.sgml</file>
+    <file>registry.xml</file>
   </header>
   <lib>registry</lib>
-  <libsummary>Store and backup key-value pairs</libsummary>
+  <libsummary>Store and back up key-value pairs.</libsummary>
   <description>
     <p>This module provides support for storing key-value
       pairs in a table known as a registry, backing up registries to
-      Mnesia in an atomic manner, and later restoring the contents of a
-      registry from Mnesia.</p>
+      <seealso marker="mnesia:mnesia">Mnesia</seealso>
+      in an atomic manner, and later restoring the contents of a
+      registry from <c>Mnesia</c>.</p>
   </description>
+
   <funcs>
     <func>
-      <name><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name>
-      <fsummary>Create and open a registry</fsummary>
+      <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name>
+      <fsummary>Close a registry.</fsummary>
       <type>
-        <v>int size;</v>
+        <v>ei_reg *reg;</v>
       </type>
       <desc>
-        <p>Open (create) a registry. The registry will be
-          initially empty. Use <c><![CDATA[ei_reg_close()]]></c> to close the registry
-          later.
-          </p>
-        <p><c><![CDATA[size]]></c> is the approximate number of objects you intend
-          to store in the registry. Since the registry uses a hash table
-          with collision chaining, there is no absolute upper limit on the
-          number of objects that can be stored in it. However for reasons
-          of efficiency, it is a good idea to choose a number that is
-          appropriate for your needs. It is possible to use
-          <c><![CDATA[ei_reg_resize()]]></c> to change the size later. Note that the
-          number you provide will be increased to the nearest larger prime
-          number.
-          </p>
-        <p>On success, an empty registry will be returned. On failure, NULL
-          will be returned.</p>
+        <p>A registry that has previously been created with
+          <c>ei_reg_open()</c> is closed, and all the objects it
+          contains are freed.</p>
+        <p><c>reg</c> is the registry to close.</p>
+        <p>Returns <c>0</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name>
-      <fsummary>Resize a registry</fsummary>
+      <name><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name>
+      <fsummary>Delete an object from the registry.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
-        <v>int newsize;</v>
+        <v>const char *key;</v>
       </type>
       <desc>
-        <p>Change the size of a registry.
-          </p>
-        <p><c><![CDATA[newsize]]></c> is the new size to make the registry. The
-          number will be increased to the nearest larger prime number.
-          </p>
-        <p>On success, the registry will be resized, all contents
-          rehashed, and the function will return 0. On failure, the
-          registry will be left unchanged and the function will return -1.</p>
+        <p>Deletes an object from the registry. The object is not
+          removed from the registry, it is only marked for later
+          removal so that on later backups to <c>Mnesia</c>, the
+          corresponding object can be removed from the <c>Mnesia</c> table as
+          well. If another object is later created with the same key, the
+          object will be reused. </p>
+        <p>The object is removed from the registry after a call to
+          <c>ei_reg_dump()</c> or <c>ei_reg_purge()</c>.
+        </p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry containing
+            <c>key</c>.</item>
+          <item><c>key</c> is the object to remove.</item>
+        </list>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name>
-      <fsummary>Close a registry </fsummary>
+      <name><ret>int</ret><nametext>ei_reg_dump(fd,reg,mntab,flags)</nametext></name>
+      <fsummary>Back up a registry to Mnesia.</fsummary>
       <type>
+        <v>int fd;</v>
         <v>ei_reg *reg;</v>
+        <v>const char *mntab;</v>
+        <v>int flags;</v>
       </type>
       <desc>
-        <p>A registry that has previously been created with
-          <c><![CDATA[ei_reg_open()]]></c> is closed, and all the objects it contains
-          are freed.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry to close.
-          </p>
-        <p>The function returns 0.</p>
+        <p>Dumps the contents of a registry to a <c>Mnesia</c> table in an
+          atomic manner, that is, either all data or no data is updated.
+          If any errors are encountered while backing up
+          the data, the entire operation is aborted.</p>
+        <list type="bulleted">
+          <item><c>fd</c> is an open connection to Erlang.
+            <c>Mnesia</c> 3.0 or later must be running on the Erlang node.
+          </item>
+          <item><c>reg</c> is the registry to back up.</item>
+          <item><c>mntab</c> is the name of the <c>Mnesia</c> table
+            where the backed up data is to be placed. If the table does not
+            exist, it is created automatically using configurable defaults.
+            For information about configuring this behavior, see
+            <seealso marker="mnesia:mnesia"><c>Mnesia</c></seealso>.</item>
+        </list>
+        <p>If <c>flags</c> is <c>0</c>, the backup includes only
+          those objects that have been created, modified, or deleted since the
+          last backup or restore (that is, an incremental backup). After the
+          backup, any objects that were marked dirty are now clean, and any
+          objects that had been marked for deletion are deleted.</p>
+        <p>Alternatively, setting flags to <c>EI_FORCE</c> causes a full
+          backup to be done, and <c>EI_NOPURGE</c> causes the deleted objects
+          to be left in the registry afterwards. These can be bitwise OR'ed
+          together if both behaviors are desired. If <c>EI_NOPURGE</c> was
+          specified, <c>ei_reg_purge()</c> can be used to
+          explicitly remove the deleted items from the registry later.</p>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name>
-      <fsummary>Assign an integer object</fsummary>
+      <name><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name>
+      <fsummary>Get a floating point object.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
-        <v>int i;</v>
       </type>
       <desc>
-        <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and integer
-          value <c><![CDATA[i]]></c>. If an object already existed with the same
-          <c><![CDATA[key]]></c>, the new value replaces the old one. If the previous
-          value was a binary or string, it is freed with <c><![CDATA[free()]]></c>.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object should be placed.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object.
-          </p>
-        <p><c><![CDATA[i]]></c> is the integer value to assign.
-          </p>
-        <p>The function returns 0 on success, or -1 on failure.</p>
+        <p>Gets the value associated with <c>key</c> in the
+          registry. The value must be a floating point type.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry where the object will be
+            looked up.</item>
+          <item><c>key</c> is the name of the object to look up.
+          </item>
+        </list>
+        <p>On success, the function returns the value associated with
+          <c>key</c>.
+          If the object is not found or if it is not a floating point
+          object, <c>-1.0</c> is returned. To avoid problems with in-band error
+          reporting (that is, if you cannot distinguish between <c>-1.0</c> and
+          a valid result), use the more general function
+          <c>ei_reg_getval()</c> instead.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name>
-      <fsummary>Assign a floating point object</fsummary>
+      <name><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name>
+      <fsummary>Get an integer object.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
-        <v>double f;</v>
       </type>
       <desc>
-        <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and
-          floating point value <c><![CDATA[f]]></c>. If an object already existed with
-          the same <c><![CDATA[key]]></c>, the new value replaces the old one. If the
-          previous value was a binary or string, it is freed with <c><![CDATA[free()]]></c>.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object should be placed.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object.
-          </p>
-        <p><c><![CDATA[f]]></c> is the floating point value to assign.
-          </p>
-        <p>The function returns 0 on success, or -1 on failure.</p>
+        <p>Gets the value associated with <c>key</c> in the
+          registry. The value must be an integer.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry where the object will be
+            looked up.</item>
+          <item><c>key</c> is the name of the object to look up.
+          </item>
+        </list>
+        <p>On success, the function returns the value associated with
+          <c>key</c>.
+          If the object is not found or if it is not an integer
+          object, <c>-1</c> is returned. To avoid problems with in-band error
+          reporting (that is, if you cannot distinguish between <c>-1</c> and a
+          valid result), use the more general function
+          <c>ei_reg_getval()</c> instead.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name>
-      <fsummary>Assign a string object</fsummary>
+      <name><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name>
+      <fsummary>Get a binary object.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
-        <v>const char *s;</v>
+        <v>int size;</v>
       </type>
       <desc>
-        <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose
-          "value" is the specified string <c><![CDATA[s]]></c>. If an object already
-          existed with the same <c><![CDATA[key]]></c>, the new value replaces the old
-          one. If the previous value was a binary or string, it is freed
-          with <c><![CDATA[free()]]></c>.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object should be placed.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object.
-          </p>
-        <p><c><![CDATA[s]]></c> is the string to assign. The string itself
-          must have been created through a single call to <c><![CDATA[malloc()]]></c> or
-          similar function, so that the registry can later delete it if
-          necessary by calling <c><![CDATA[free()]]></c>.
-          </p>
-        <p>The function returns 0 on success, or -1 on failure.</p>
+        <p>Gets the value associated with <c>key</c> in the
+          registry. The value must be a binary (pointer) type.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry where the object will be
+            looked up.</item>
+          <item><c>key</c> is the name of the object to look up.
+          </item>
+          <item><c>size</c> is initialized to contain the length in
+            bytes of the object, if it is found.</item>
+        </list>
+        <p>On success, the function returns the value associated with
+          <c>key</c> and indicates its length in
+          <c>size</c>.
+          If the object is not found or if it is not a binary object,
+          <c>NULL</c> is returned. To avoid problems with in-band error
+          reporting (that is, if you cannot distinguish between <c>NULL</c> and
+          a valid result), use the more general function
+          <c>ei_reg_getval()</c> instead.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name>
-      <fsummary>Assign a binary object</fsummary>
+      <name><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name>
+      <fsummary>Get a string object.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
-        <v>const void *p;</v>
-        <v>int size;</v>
       </type>
       <desc>
-        <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose
-          "value" is the binary object pointed to by <c><![CDATA[p]]></c>. If an
-          object already existed with the same <c><![CDATA[key]]></c>, the new value
-          replaces the old one. If the previous value was a binary or
-          string, it is freed with <c><![CDATA[free()]]></c>.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object should be placed.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object.
-          </p>
-        <p><c><![CDATA[p]]></c> is a pointer to the binary object. The object itself
-          must have been created through a single call to <c><![CDATA[malloc()]]></c> or
-          similar function, so that the registry can later delete it if
-          necessary by calling <c><![CDATA[free()]]></c>.
-          </p>
-        <p><c><![CDATA[size]]></c> is the length in bytes of the binary object.
-          </p>
-        <p>The function returns 0 on success, or -1 on failure.</p>
+        <p>Gets the value associated with <c>key</c> in the
+          registry. The value must be a string.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry where the object will be
+            looked up.</item>
+          <item><c>key</c> is the name of the object to look up.
+          </item>
+        </list>
+        <p>On success, the function returns the value associated with
+          <c>key</c>. If the object is not found or if it is not a
+          string, <c>NULL</c> is returned. To avoid problems with in-band error
+          reporting (that is, if you cannot distinguish between <c>NULL</c> and
+          a valid result), use the more general function
+          <c>ei_reg_getval()</c> instead.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_setval(reg,key,flags,v,...)</nametext></name>
-      <fsummary>Assign a value to any object type</fsummary>
+      <name><ret>int</ret><nametext>ei_reg_getval(reg,key,flags,v,...)</nametext></name>
+      <fsummary>Get any object.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
         <v>int flags;</v>
-        <v>v (see below)</v>
+        <v>void *v (see below)</v>
       </type>
       <desc>
-        <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose
-          value is specified by <c><![CDATA[v]]></c>. If an object already
-          existed with the same <c><![CDATA[key]]></c>, the new value replaces the old
-          one. If the previous value was a binary or string, it is freed
-          with <c><![CDATA[free()]]></c>. 
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object should be placed.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object.
-          </p>
-        <p><c><![CDATA[flags]]></c> indicates the type of the object specified by
-          <c><![CDATA[v]]></c>. Flags must be one of EI_INT, EI_FLT, EI_STR and
-          EI_BIN, indicating whether <c><![CDATA[v]]></c> is <c><![CDATA[int]]></c>, <c><![CDATA[double]]></c>,
-          <c><![CDATA[char*]]></c> or <c><![CDATA[void*]]></c>. If <c><![CDATA[flags]]></c> is EI_BIN, then a
-          fifth argument <c><![CDATA[size]]></c> is required, indicating the size
-          in bytes of the object pointed to by <c><![CDATA[v]]></c>.
-          </p>
-        <p>If you wish to store an arbitrary pointer in the registry,
-          specify a <c><![CDATA[size]]></c> of 0. In this case, the object itself will
-          not be transferred by an <c><![CDATA[ei_reg_dump()]]></c> operation, just
-          the pointer value.
-          </p>
-        <p>The function returns 0 on success, or -1 on failure.</p>
+        <p>A general function for retrieving any kind of
+          object from the registry.</p>
+        <list type="bulleted">
+          <item>
+            <p><c>reg</c> is the registry where the object will be
+              looked up.</p>
+          </item>
+          <item>
+            <p><c>key</c> is the name of the object to look up.</p>
+          </item>
+          <item>
+            <p><c>flags</c> indicates the type of object that you
+              are looking for. If <c>flags</c> is <c>0</c>, any
+              kind of object is returned.
+              If <c>flags</c> is <c>EI_INT</c>, <c>EI_FLT</c>,
+              <c>EI_STR</c>, or <c>EI_BIN</c>, then only values of
+              that kind are returned.</p>
+            <p>The buffer pointed to by <c>v</c>
+              must be large enough to hold the return data, that is, it must be
+              a pointer to one of <c>int</c>,
+              <c>double</c>, <c>char*</c>, or
+              <c>void*</c>, respectively.</p>
+            <p>If <c>flags</c> is <c>EI_BIN</c>, a fifth argument
+              <c>int *size</c> is required, so that the size of the
+              object can be returned.</p>
+          </item>
+        </list>
+        <p>On success, <c>v</c> (and <c>size</c> if the
+          object is binary) is initialized with the value associated
+          with <c>key</c>, and the function returns <c>EI_INT</c>,
+          <c>EI_FLT</c>, <c>EI_STR</c>, or <c>EI_BIN</c>, indicating the type
+          of object. On failure, <c>-1</c> is returned and the
+          arguments are not updated.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name>
-      <fsummary>Get an integer object</fsummary>
+      <name><ret>int</ret><nametext>ei_reg_markdirty(reg,key)</nametext></name>
+      <fsummary>Mark an object as dirty.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
       </type>
       <desc>
-        <p>Get the value associated with <c><![CDATA[key]]></c> in the
-          registry. The value must be an integer.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object will be looked
-          up.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object to look up.
-          </p>
-        <p>On success, the function returns the value associated with <c><![CDATA[key]]></c>.
-          If the object was not found or it was not an integer
-          object, -1 is returned. To avoid problems with in-band error
-          reporting (i.e. if you cannot distinguish between -1 and a
-          valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c>
-          instead.</p>
+        <p>Marks a registry object as dirty. This ensures that
+          it is included in the next backup to <c>Mnesia</c>. Normally this
+          operation is not necessary, as all of the normal registry
+          'set' functions do this automatically. However, if you have
+          retrieved the value of a string or binary object from the
+          registry and modified the contents, then the change is
+          invisible to the registry and the object is assumed to be
+          unmodified. This function allows you to make such modifications
+          and then let the registry know about them.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry containing the object.
+          </item>
+          <item><c>key</c> is the name of the object to mark.
+          </item>
+        </list>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name>
-      <fsummary>Get a floating point object</fsummary>
+      <name><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name>
+      <fsummary>Create and open a registry.</fsummary>
+      <type>
+        <v>int size;</v>
+      </type>
+      <desc>
+        <p>Opens (creates) a registry, which initially is empty. To
+          close the registry later, use <c>ei_reg_close()</c>.</p>
+        <p><c>size</c> is the approximate number of objects you
+          intend to store in the registry. As the registry uses a hash table
+          with collision chaining, no absolute upper limit exists on the
+          number of objects that can be stored in it. However, for reasons
+          of efficiency, it is a good idea to choose a number that is
+          appropriate for your needs. To change the size later, use
+          <c>ei_reg_resize()</c>. Notice that the number
+          you provide is increased to the nearest larger prime number.</p>
+        <p>Returns an empty registry on success, otherwise <c>NULL</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name>
+      <fsummary>Remove deleted objects.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
-        <v>const char *key;</v>
       </type>
       <desc>
-        <p>Get the value associated with <c><![CDATA[key]]></c> in the
-          registry. The value must be a floating point type.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object will be looked
-          up.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object to look up.
-          </p>
-        <p>On success, the function returns the value associated with <c><![CDATA[key]]></c>.
-          If the object was not found or it was not a floating point
-          object, -1.0 is returned. To avoid problems with in-band error
-          reporting (i.e. if you cannot distinguish between -1.0 and a
-          valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c>
-          instead.</p>
+        <p>Removes all objects marked for deletion. When objects
+          are deleted with <c>ei_reg_delete()</c> they are not
+          removed from the registry, only marked for later removal.
+          On a later backup to <c>Mnesia</c>, the
+          objects can also be removed from the <c>Mnesia</c> table. If you are
+          not backing up to <c>Mnesia</c>, you may wish to remove the objects
+          manually with this function.</p>
+        <p><c>reg</c> is a registry containing objects marked for
+          deletion.</p>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name>
-      <fsummary>Get a string object</fsummary>
+      <name><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name>
+      <fsummary>Resize a registry.</fsummary>
+      <type>
+        <v>ei_reg *reg;</v>
+        <v>int newsize;</v>
+      </type>
+      <desc>
+        <p>Changes the size of a registry.</p>
+        <p><c>newsize</c> is the new size to make the registry. The
+          number is increased to the nearest larger prime number.</p>
+        <p>On success, the registry is resized, all contents
+          rehashed, and <c>0</c> is returned. On failure, the
+          registry is left unchanged and <c>-1</c> is returned.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name><ret>int</ret><nametext>ei_reg_restore(fd,reg,mntab)</nametext></name>
+      <fsummary>Restore a registry from Mnesia.</fsummary>
+      <type>
+        <v>int fd;</v>
+        <v>ei_reg *reg;</v>
+        <v>const char *mntab;</v>
+      </type>
+      <desc>
+        <p>The contents of a <c>Mnesia</c> table are read into the registry.</p>
+        <list type="bulleted">
+          <item><c>fd</c> is an open connection to Erlang.
+            <c>Mnesia</c> 3.0 or later must be running on the Erlang node.
+          </item>
+          <item><c>reg</c> is the registry where the data is to be
+            placed.</item>
+          <item><c>mntab</c> is the name of the <c>Mnesia</c> table
+            to read data from.</item>
+        </list>
+        <p>Notice that only tables of a certain format can be
+          restored, that is, those that have been created and backed up to
+          with <c>ei_reg_dump()</c>. If the registry was not empty
+          before the operation, the contents of the table are added to the
+          contents of the registry. If the table contains objects with the
+          same keys as those already in the registry, the registry objects
+          are overwritten with the new values. If the registry
+          contains objects that were not in the table, they are
+          unchanged by this operation.</p>
+        <p>After the restore operation, the entire contents of the
+          registry is marked as unmodified. Notice that this includes any
+          objects that were modified before the restore and not
+          overwritten by the restore.</p>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name>
+      <fsummary>Assign a floating point object.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
+        <v>double f;</v>
       </type>
       <desc>
-        <p>Get the value associated with <c><![CDATA[key]]></c> in the
-          registry. The value must be a string.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object will be looked
-          up.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object to look up.
-          </p>
-        <p>On success, the function returns the value associated with
-          <c><![CDATA[key]]></c>. If the object was not found or it was not a string,
-          NULL is returned. To avoid problems with in-band error
-          reporting (i.e. if you cannot distinguish between NULL and a
-          valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c>
-          instead.</p>
+        <p>Creates a key-value pair with the specified <c>key</c>
+          and floating point value <c>f</c>. If an object already
+          exists with the same <c>key</c>, the new value replaces
+          the old one. If the previous value was a binary or string, it is
+          freed with <c>free()</c>.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry where the object is to be
+            placed.</item>
+          <item><c>key</c> is the object name.</item>
+          <item><c>f</c> is the floating point value to assign.
+          </item>
+        </list>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name>
-      <fsummary>Get a binary object</fsummary>
+      <name><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name>
+      <fsummary>Assign an integer object.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
-        <v>int size;</v>
+        <v>int i;</v>
       </type>
       <desc>
-        <p>Get the value associated with <c><![CDATA[key]]></c> in the
-          registry. The value must be a binary (pointer) type.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object will be looked
-          up.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object to look up.
-          </p>
-        <p><c><![CDATA[size]]></c> will be initialized to contain the length in
-          bytes of the object, if it is found.
-          </p>
-        <p>On success, the function returns the value associated with
-          <c><![CDATA[key]]></c> and indicates its length in <c><![CDATA[size]]></c>.
-          If the object was not found or it was not a binary object,
-          NULL is returned. To avoid problems with in-band error
-          reporting (i.e. if you cannot distinguish between NULL and a
-          valid result) use the more general function <c><![CDATA[ei_reg_getval()]]></c>
-          instead.</p>
+        <p>Creates a key-value pair with the specified <c>key</c>
+          and integer value <c>i</c>. If an object already exists
+          with the same <c>key</c>, the new value replaces the old
+          one. If the previous value was a binary or string, it is freed with
+          <c>free()</c>.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry where the object is to be
+            placed.</item>
+          <item><c>key</c> is the object name.</item>
+          <item><c>i</c> is the integer value to assign.</item>
+        </list>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_getval(reg,key,flags,v,...)</nametext></name>
-      <fsummary>Get any object</fsummary>
+      <name><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name>
+      <fsummary>Assign a binary object.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
-        <v>int flags;</v>
-        <v>void *v (see below)</v>
+        <v>const void *p;</v>
+        <v>int size;</v>
       </type>
       <desc>
-        <p>This is a general function for retrieving any kind of
-          object from the registry. 
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the object will be looked
-          up.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object to look up.
-          </p>
-        <p><c><![CDATA[flags]]></c> indicates the type of object that you are
-          looking for. If <c><![CDATA[flags]]></c> is 0, then any kind of object will
-          be returned. If <c><![CDATA[flags]]></c> is one of EI_INT, EI_FLT, EI_STR or
-          EI_BIN, then only values of that kind will be returned. The
-          buffer pointed to by <c><![CDATA[v]]></c> must be large enough to hold the return
-          data, i.e. it must be a pointer to one of <c><![CDATA[int]]></c>,
-          <c><![CDATA[double]]></c>, <c><![CDATA[char*]]></c> or <c><![CDATA[void*]]></c>, respectively. Also,
-          if <c><![CDATA[flags]]></c> is EI_BIN, then a fifth argument <c><![CDATA[int *size]]></c> is required, so that the size of the object can be
-          returned.
-          </p>
-        <p>If the function succeeds, <c><![CDATA[v]]></c> (and <c><![CDATA[size]]></c> if the
-          object is binary) will be initialized with the value associated
-          with <c><![CDATA[key]]></c>, and the function will return one of EI_INT,
-          EI_FLT, EI_STR or EI_BIN, indicating the type of object. On failure the
-          function will return -1 and the arguments will not be updated.</p>
+        <p>Creates a key-value pair with the specified <c>key</c>
+          whose "value" is the binary object pointed to by <c>p</c>.
+          If an object already exists with the same <c>key</c>,
+          the new value replaces the old one. If the previous value was a
+          binary or string, it is freed with <c>free()</c>.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry where the object is to be
+            placed.</item>
+          <item><c>key</c> is the object name.</item>
+          <item><c>p</c> is a pointer to the binary object. The
+            object itself must have been created through a single call to
+            <c>malloc()</c> or a similar function, so that the
+            registry can later delete it if necessary by calling
+            <c>free()</c>.</item>
+          <item><c>size</c> is the length in bytes of the binary
+            object.</item>
+        </list>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_markdirty(reg,key)</nametext></name>
-      <fsummary>Mark an object as dirty </fsummary>
+      <name><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name>
+      <fsummary>Assign a string object.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
+        <v>const char *s;</v>
       </type>
       <desc>
-        <p>Mark a registry object as dirty. This will ensure that
-          it is included in the next backup to Mnesia. Normally this
-          operation will not be necessary since all of the normal registry
-          'set' functions do this automatically. However if you have
-          retrieved the value of a string or binary object from the
-          registry and modified the contents, then the change will be
-          invisible to the registry and the object will be assumed to be
-          unmodified. This function allows you to make such modifications
-          and then let the registry know about them. 
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry containing the object.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object to mark.
-          </p>
-        <p>The function returns 0 on success, or -1 on failure.</p>
+        <p>Creates a key-value pair with the specified <c>key</c>
+          whose "value" is the specified string <c>s</c>. If an
+          object already exists with the same <c>key</c>, the new
+          value replaces the old one. If the previous value was a binary or
+          string, it is freed with <c>free()</c>.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry where the object is to be
+            placed.</item>
+          <item><c>key</c> is the object name.</item>
+          <item><c>s</c> is the string to assign. The string itself
+            must have been created through a single call to
+            <c>malloc()</c> or similar a function,
+            so that the registry can later delete it if
+            necessary by calling <c>free()</c>.</item>
+        </list>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name>
-      <fsummary>Delete an object from the registry</fsummary>
+      <name><ret>int</ret><nametext>ei_reg_setval(reg,key,flags,v,...)</nametext></name>
+      <fsummary>Assign a value to any object type.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
+        <v>int flags;</v>
+        <v>v (see below)</v>
       </type>
       <desc>
-        <p>Delete an object from the registry. The object is not
-          actually removed from the registry, it is only marked for later
-          removal so that on subsequent backups to Mnesia, the
-          corresponding object can be removed from the Mnesia table as
-          well. If another object is later created with the same key, the
-          object will be reused. 
-          </p>
-        <p>The object will be removed from the registry after a call to
-          <c><![CDATA[ei_reg_dump()]]></c> or <c><![CDATA[ei_reg_purge()]]></c>.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry containing <c><![CDATA[key]]></c>.
-          </p>
-        <p><c><![CDATA[key]]></c> is the object to remove.
-          </p>
-        <p>If the object was found, the function returns 0 indicating
-          success. Otherwise the function returns -1.</p>
+        <p>Creates a key-value pair with the specified <c>key</c>
+          whose value is specified by <c>v</c>. If an object already
+          exists with the same <c>key</c>, the new value replaces
+          the old one. If the previous value was a binary or string, it is freed
+          with <c>free()</c>.</p>
+        <list type="bulleted">
+          <item>
+            <p><c>reg</c> is the registry where the object is to be
+              placed.</p>
+          </item>
+          <item>
+            <p><c>key</c> is the object name.</p>
+          </item>
+          <item>
+            <p><c>flags</c> indicates the type of the object
+              specified by <c>v</c>. Flags must be one of
+              <c>EI_INT</c>, <c>EI_FLT</c>, <c>EI_STR</c>, and <c>EI_BIN</c>,
+              indicating whether
+              <c>v</c> is <c>int</c>,
+              <c>double</c>, <c>char*</c>, or
+              <c>void*</c>.</p>
+            <p>If <c>flags</c> is <c>EI_BIN</c>, a fifth argument
+              <c>size</c> is required, indicating the size
+              in bytes of the object pointed to by <c>v</c>.</p>
+          </item>
+        </list>
+        <p>If you wish to store an arbitrary pointer in the registry,
+          specify a <c>size</c> of <c>0</c>. In this case, the
+          object itself is not transferred by an
+          <c>ei_reg_dump()</c> operation, only the pointer
+          value.</p>
+        <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_reg_stat(reg,key,obuf)</nametext></name>
-      <fsummary>Get object information</fsummary>
+      <fsummary>Get object information.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>const char *key;</v>
         <v>struct ei_reg_stat *obuf;</v>
       </type>
       <desc>
-        <p>Return information about an object.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry containing the object.
-          </p>
-        <p><c><![CDATA[key]]></c> is the name of the object.
-          </p>
-        <p><c><![CDATA[obuf]]></c> is a pointer to an <c><![CDATA[ei_reg_stat]]></c> structure,
-          defined below:
-          </p>
+        <p>Returns information about an object.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry containing the object.
+          </item>
+          <item><c>key</c> is the object name.</item>
+          <item><c>obuf</c> is a pointer to an
+            <c>ei_reg_stat</c> structure, defined as follows:</item>
+        </list>
         <code type="none"><![CDATA[
 struct ei_reg_stat {
   int attr;
   int size;
 };
         ]]></code>
-        <p>In <c><![CDATA[attr]]></c> the object's attributes are stored as the logical
-          OR of its type (one of EI_INT, EI_FLT, EI_BIN and EI_STR),
-          whether it is marked for deletion (EI_DELET) and whether it has
-          been modified since the last backup to Mnesia (EI_DIRTY). 
-          </p>
-        <p>The <c><![CDATA[size]]></c> field indicates the size in bytes required to store
-          EI_STR (including the terminating 0) and EI_BIN objects, or 0
-          for EI_INT and EI_FLT.
-          </p>
-        <p>The function returns 0 and initializes <c><![CDATA[obuf]]></c> on
-          success, or returns -1 on failure.</p>
+        <p>In <c>attr</c> the attributes of the object are stored
+          as the logical <em>OR</em> of its type (one of <c>EI_INT</c>,
+          <c>EI_FLT</c>, <c>EI_BIN</c>, and <c>EI_STR</c>),
+          whether it is marked for deletion (<c>EI_DELET</c>), and whether it
+          has been modified since the last backup to <c>Mnesia</c>
+          (<c>EI_DIRTY</c>).</p>
+        <p>Field <c>size</c> indicates the size in bytes required
+          to store <c>EI_STR</c> (including the terminating <c>0</c>) and
+          <c>EI_BIN</c> objects, or <c>0</c> for <c>EI_INT</c> and
+          <c>EI_FLT</c>.</p>
+        <p>Returns <c>0</c> and initializes <c>obuf</c> on success,
+          otherwise <c>-1</c>.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_reg_tabstat(reg,obuf)</nametext></name>
-      <fsummary>Get registry information</fsummary>
+      <fsummary>Get registry information.</fsummary>
       <type>
         <v>ei_reg *reg;</v>
         <v>struct ei_reg_tabstat *obuf;</v>
       </type>
       <desc>
-        <p>Return information about a registry. Using information
+        <p>Returns information about a registry. Using information
           returned by this function, you can see whether the size of the
-          registry is suitable for the amount of data it contains.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry to return information about.
-          </p>
-        <p><c><![CDATA[obuf]]></c> is a pointer to an <c><![CDATA[ei_reg_tabstat]]></c> structure,
-          defined below:
-          </p>
+          registry is suitable for the amount of data it contains.</p>
+        <list type="bulleted">
+          <item><c>reg</c> is the registry to return information
+            about.</item>
+          <item><c>obuf</c> is a pointer to an
+            <c>ei_reg_tabstat</c> structure, defined as follows:
+          </item>
+        </list>
         <code type="none"><![CDATA[
 struct ei_reg_tabstat {
   int size;  
@@ -487,126 +615,23 @@ struct ei_reg_tabstat {
   int collisions; 
 };
         ]]></code>
-        <p>The <c><![CDATA[size]]></c> field indicates the number of hash positions
+        <p>Field <c>size</c> indicates the number of hash positions
           in the registry. This is the number you provided when you
           created or last resized the registry, rounded up to the nearest
-          prime.
-          </p>
-        <p><c><![CDATA[nelem]]></c> indicates the number of elements stored in the
-          registry. It includes objects that are deleted but not purged.
-          </p>
-        <p><c><![CDATA[npos]]></c> indicates the number of unique positions that are
-          occupied in the registry. 
-          </p>
-        <p><c><![CDATA[collisions]]></c> indicates how many elements are sharing
-          positions in the registry.
-          </p>
-        <p>On success, the function returns 0 and <c><![CDATA[obuf]]></c> is
-          initialized to contain table statistics. On failure, the function
-          returns -1.</p>
-      </desc>
-    </func>
-    <func>
-      <name><ret>int</ret><nametext>ei_reg_dump(fd,reg,mntab,flags)</nametext></name>
-      <fsummary>Back up a registry to Mnesia</fsummary>
-      <type>
-        <v>int fd;</v>
-        <v>ei_reg *reg;</v>
-        <v>const char *mntab;</v>
-        <v>int flags;</v>
-      </type>
-      <desc>
-        <p>Dump the contents of a registry to a Mnesia table in an
-          atomic manner, i.e. either all data will be updated, or none of
-          it will. If any errors are encountered while backing up
-          the data, the entire operation is aborted.
-          </p>
-        <p><c><![CDATA[fd]]></c> is an open connection to Erlang.
-          Mnesia 3.0 or later must be running on the Erlang node.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry to back up.
-          </p>
-        <p><c><![CDATA[mntab]]></c> is the name of the Mnesia table where the backed
-          up data should be placed. If the table does not exist, it will
-          be created automatically using configurable defaults. See your
-          Mnesia documentation for information about configuring this
-          behaviour. 
-          </p>
-        <p>If <c><![CDATA[flags]]></c> is 0, the backup will include only those
-          objects which have been created, modified or deleted since the
-          last backup or restore (i.e. an incremental backup). After the
-          backup, any objects that were marked dirty are now clean, and any
-          objects that had been marked for deletion are deleted.
-          </p>
-        <p>Alternatively, setting flags to EI_FORCE will cause a full
-          backup to be done, and EI_NOPURGE will cause the deleted objects
-          to be left in the registry afterwards. These can be bitwise ORed
-          together if both behaviours are desired. If EI_NOPURGE was
-          specified, you can use <c><![CDATA[ei_reg_purge()]]></c> to explicitly remove
-          the deleted items from the registry later. 
-          </p>
-        <p>The function returns 0 on success, or -1 on failure.</p>
-      </desc>
-    </func>
-    <func>
-      <name><ret>int</ret><nametext>ei_reg_restore(fd,reg,mntab)</nametext></name>
-      <fsummary>Restore a registry from Mnesia</fsummary>
-      <type>
-        <v>int fd;</v>
-        <v>ei_reg *reg;</v>
-        <v>const char *mntab;</v>
-      </type>
-      <desc>
-        <p>The contents of a Mnesia table are read into the
-          registry. 
-          </p>
-        <p><c><![CDATA[fd]]></c> is an open connection to Erlang.
-          Mnesia 3.0 or later must be running on the Erlang node.
-          </p>
-        <p><c><![CDATA[reg]]></c> is the registry where the data should be placed.
-          </p>
-        <p><c><![CDATA[mntab]]></c> is the name of the Mnesia table to read data
-          from. 
-          </p>
-        <p>Note that only tables of a certain format can be
-          restored, i.e. those that have been created and backed up to
-          with <c><![CDATA[ei_reg_dump()]]></c>. If the registry was not empty before
-          the operation, then the contents of the table are added to the
-          contents of the registry. If the table contains objects with the
-          same keys as those already in the registry, the registry objects
-          will be overwritten with the new values. If the registry
-          contains objects that were not in the table, they will be
-          unchanged by this operation.
-          </p>
-        <p>After the restore operation, the entire contents of the
-          registry is marked as unmodified. Note that this includes any
-          objects that were modified before the restore and not
-          overwritten by the restore.  
-          </p>
-        <p>The function returns 0 on success, or -1 on failure.</p>
-      </desc>
-    </func>
-    <func>
-      <name><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name>
-      <fsummary>Remove deleted objects</fsummary>
-      <type>
-        <v>ei_reg *reg;</v>
-      </type>
-      <desc>
-        <p>Remove all objects marked for deletion. When objects
-          are deleted with <c><![CDATA[ei_reg_delete()]]></c> they are not actually
-          removed from the registry, only marked for later removal. This
-          is so that on a subsequent backup to Mnesia, the
-          objects can also be removed from the Mnesia table. If you are
-          not backing up to Mnesia then you may wish to remove the objects
-          manually with this function.
-          </p>
-        <p><c><![CDATA[reg]]></c> is a registry containing objects marked for
-          deletion.
-          </p>
-        <p>The function returns 0 on success, or -1 on failure.</p>
+          prime number.</p>
+        <list type="bulleted">
+          <item><c>nelem</c> indicates the number of elements stored
+            in the registry. It includes objects that are deleted but not
+            purged.</item>
+          <item><c>npos</c> indicates the number of unique positions
+            that are occupied in the registry.</item>
+          <item><c>collisions</c> indicates how many elements are
+            sharing positions in the registry.</item>
+        </list>
+        <p>On success, <c>0</c> is returned and
+          <c>obuf</c> is initialized to contain table statistics,
+          otherwise <c>-1</c> is returned.</p>
       </desc>
     </func>
   </funcs>
 </cref>
-