The R13B03 release.OTP_R13B03

1 files changed, 611 insertions, 0 deletions

diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml
new file mode 100644
index 0000000000..8aeb378d95
--- /dev/null
+++ b/lib/erl_interface/doc/src/registry.xml
@@ -0,0 +1,611 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE cref SYSTEM "cref.dtd">
+
+<cref>
+  <header>
+    <copyright>
+      <year>1998</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>registry</title>
+    <prepared>Gordon Beaton</prepared>
+    <responsible>Gordon Beaton</responsible>
+    <docno></docno>
+    <approved>Gordon Beaton</approved>
+    <checked>Gordon Beaton</checked>
+    <date>980707</date>
+    <rev>A</rev>
+    <file>registry.sgml</file>
+  </header>
+  <lib>registry</lib>
+  <libsummary>Store and backup 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>
+  </description>
+  <funcs>
+    <func>
+      <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>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>
+      </desc>
+    </func>
+    <func>
+      <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>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>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name>
+      <fsummary>Close a registry </fsummary>
+      <type>
+        <v>ei_reg *reg;</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>
+      </desc>
+    </func>
+    <func>
+      <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 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>
+      </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>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>
+      </desc>
+    </func>
+    <func>
+      <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>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>
+      </desc>
+    </func>
+    <func>
+      <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>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>
+      </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>
+      <type>
+        <v>ei_reg *reg;</v>
+        <v>const char *key;</v>
+        <v>int flags;</v>
+        <v>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>
+      </desc>
+    </func>
+    <func>
+      <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>
+      </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>
+      </desc>
+    </func>
+    <func>
+      <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>
+      </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>
+      </desc>
+    </func>
+    <func>
+      <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>
+      </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>
+      </desc>
+    </func>
+    <func>
+      <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>int size;</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>
+      </desc>
+    </func>
+    <func>
+      <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>void *v (see below)</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>
+      </desc>
+    </func>
+    <func>
+      <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>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>
+      </desc>
+    </func>
+    <func>
+      <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>const char *key;</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>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>ei_reg_stat(reg,key,obuf)</nametext></name>
+      <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>
+        <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>
+      </desc>
+    </func>
+    <func>
+      <name><ret>int</ret><nametext>ei_reg_tabstat(reg,obuf)</nametext></name>
+      <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
+          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>
+        <code type="none"><![CDATA[
+struct ei_reg_tabstat {
+  int size;  
+  int nelem; 
+  int npos;  
+  int collisions; 
+};
+        ]]></code>
+        <p>The <c><![CDATA[size]]></c> field 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>
+      </desc>
+    </func>
+  </funcs>
+</cref>
+