aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/doc/src/registry.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/erl_interface/doc/src/registry.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/erl_interface/doc/src/registry.xml')
-rw-r--r--lib/erl_interface/doc/src/registry.xml611
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>
+