diff options
Diffstat (limited to 'lib/erl_interface/doc')
| -rw-r--r-- | lib/erl_interface/doc/src/Makefile | 3 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/ei_users_guide.xml | 170 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/notes.xml | 3 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/ref_man.xml | 1 | ||||
| -rw-r--r-- | lib/erl_interface/doc/src/registry.xml | 642 |
5 files changed, 2 insertions, 817 deletions
diff --git a/lib/erl_interface/doc/src/Makefile b/lib/erl_interface/doc/src/Makefile index 73344b1a65..f709176508 100644 --- a/lib/erl_interface/doc/src/Makefile +++ b/lib/erl_interface/doc/src/Makefile @@ -39,8 +39,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) XML_REF1_FILES = erl_call_cmd.xml XML_REF3_FILES = ei_global.xml \ ei.xml \ - ei_connect.xml \ - registry.xml + ei_connect.xml BOOK_FILES = book.xml XML_APPLICATION_FILES = ref_man.xml diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 5dfaf556da..5c9452b516 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -70,7 +70,6 @@ <item>Sending and receiving Erlang messages</item> <item>Remote procedure calls</item> <item>Using global names</item> - <item>Using the registry</item> </list> </section> @@ -528,173 +527,4 @@ ei_global_register(fd,servicename,ei_self(ec)); ]]></code> ei_global_unregister(ec,fd,servicename); ]]></code> </section> - <section> - <title>Using the Registry</title> - - <note><p>This functionality is deprecated as of OTP 23, and will be - removed in OTP 24. Reasonably new <c>gcc</c> compilers will issue - deprecation warnings. In order to disable these warnings, define the - macro <c>EI_NO_DEPR_WARN</c>.</p></note> - - <p>This section describes the use of the registry, a simple mechanism - for storing key-value pairs in a C-node, as well as backing them up or - restoring them from an <c>Mnesia</c> table on an Erlang node. For more - detailed information about the individual API functions, see the - <seecref marker="registry"><c>registry</c></seecref> module.</p> - - <p>Keys are strings, that is, <c>NULL</c>-terminated arrays of characters, and - values are arbitrary objects. Although integers and floating point numbers - are treated specially by the registry, you can store strings or binary - objects of any type as pointers.</p> - - <p>To start, open a registry:</p> - - <code type="none"><![CDATA[ -ei_reg *reg; - -reg = ei_reg_open(45); ]]></code> - - <p>The number <c>45</c> in the example indicates the approximate number of - objects that you expect to store in the registry. Internally the - registry uses hash tables with collision chaining, so there is no - absolute upper limit on the number of objects that the registry can - contain, but if performance or memory usage is important, then you - are to choose a number accordingly. The registry can be resized later.</p> - - <p>You can open as many registries as you like (if memory permits).</p> - - <p>Objects are stored and retrieved through set and get functions. - The following example shows how to store integers, floats, strings, - and arbitrary binary objects:</p> - - <code type="none"><![CDATA[ -struct bonk *b = malloc(sizeof(*b)); -char *name = malloc(7); - -ei_reg_setival(reg,"age",29); -ei_reg_setfval(reg,"height",1.85); - -strcpy(name,"Martin"); -ei_reg_setsval(reg,"name",name); - -b->l = 42; -b->m = 12; -ei_reg_setpval(reg,"jox",b,sizeof(*b)); ]]></code> - - <p>If you try to store an object in the registry and there is an - existing object with the same key, the new value replaces the old - one. This is done regardless of whether the new object and the old one - have the same type, so you can, for example, replace a string with an - integer. If the existing value is a string or binary, it is freed - before the new value is assigned.</p> - - <p>Stored values are retrieved from the registry as follows:</p> - - <code type="none"><![CDATA[ -long i; -double f; -char *s; -struct bonk *b; -int size; - -i = ei_reg_getival(reg,"age"); -f = ei_reg_getfval(reg,"height"); -s = ei_reg_getsval(reg,"name"); -b = ei_reg_getpval(reg,"jox",&size); ]]></code> - - <p>In all the above examples, the object must exist and it must be of - the right type for the specified operation. If you do not know the - type of an object, you can ask:</p> - - <code type="none"><![CDATA[ -struct ei_reg_stat buf; - -ei_reg_stat(reg,"name",&buf); ]]></code> - - <p>Buf is initialized to contain object attributes.</p> - - <p>Objects can be removed from the registry:</p> - - <code type="none"><![CDATA[ -ei_reg_delete(reg,"name"); ]]></code> - - <p>When you are finished with a registry, close it to remove all the - objects and free the memory back to the system:</p> - - <code type="none"><![CDATA[ -ei_reg_close(reg); ]]></code> - - <section> - <title>Backing Up the Registry to Mnesia</title> - <p>The contents of a registry can be backed up to - <seeerl marker="mnesia:mnesia"><c>Mnesia</c></seeerl> on a "nearby" Erlang - node. You must provide an open connection to the Erlang node - (see <seecref marker="ei_connect"><c>ei_connect</c></seecref>). - Also, <c>Mnesia</c> 3.0 or later must be running - on the Erlang node before the backup is initiated:</p> - - <code type="none"><![CDATA[ -ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code> - - <p>This example back up the contents of the registry to the - specified <c>Mnesia</c> table <c>"mtab"</c>. - Once a registry has been backed - up to <c>Mnesia</c> like this, more backups only affect - objects that have been modified since the most recent backup, that is, - objects that have been created, changed, or deleted. The backup - operation is done as a single atomic transaction, so that either the - entire backup is performed or none of it.</p> - - <p>Likewise, a registry can be restored from a <c>Mnesia</c> table:</p> - - <code type="none"><![CDATA[ -ei_reg_restore(fd, reg, "mtab"); ]]></code> - - <p>This reads the entire contents of <c>"mtab"</c> into the - specified registry. After the restore, all the objects in the registry - are marked as unmodified, so a later backup only affects - objects that you have modified since the restore.</p> - - <p>Notice that if you restore to a non-empty registry, objects in the - table overwrite objects in the registry with the same keys. Also, - the <em>entire</em> contents of the registry is marked as unmodified - after the restore, including any modified objects that were not - overwritten by the restore operation. This may not be your - intention.</p> - </section> - - <section> - <title>Storing Strings and Binaries</title> - <p>When string or binary objects are stored in the registry it is - important that some simple guidelines are followed.</p> - - <p>Most importantly, the object must have been created with a single call - to <c>malloc()</c> (or similar), so that it can later be - removed by a single call to <c>free()</c>. - Objects are freed by the registry - when it is closed, or when you assign a new value to an object that - previously contained a string or binary.</p> - - <p>Notice that if you store binary objects that are context-dependent - (for example, containing pointers or open file descriptors), - they lose their meaning if they are backed up to a <c>Mnesia</c> table - and later restored in a different context.</p> - - <p>When you retrieve a stored string or binary value from the registry, - the registry maintains a pointer to the object and you are passed a - copy of that pointer. You should never free an object retrieved in - this manner because when the registry later attempts to free it, a - runtime error occurs that likely causes the C-node to crash.</p> - - <p>You are free to modify the contents of an object retrieved this way. - However, when you do so, the registry is not aware of your changes, - possibly causing it to be missed the next time you make an - <c>Mnesia</c> backup of the registry contents. This can be avoided if - you mark the object as dirty after any such changes with - <seecref marker="registry#ei_reg_markdirty"> - <c>ei_reg_markdirty</c></seecref>, or pass appropriate flags to - <seecref marker="registry#ei_reg_dump"> - <c>ei_reg_dump</c></seecref>.</p> - </section> - </section> </chapter> diff --git a/lib/erl_interface/doc/src/notes.xml b/lib/erl_interface/doc/src/notes.xml index fde35537ba..3a7c64b98b 100644 --- a/lib/erl_interface/doc/src/notes.xml +++ b/lib/erl_interface/doc/src/notes.xml @@ -270,8 +270,7 @@ Own Id: OTP-16624</p> </item> <item> - <p>The <c>erl_interface</c> <seecref - marker="erl_interface:registry"><c>registry</c></seecref> + <p>The <c>erl_interface</c> <c>registry</c> functionality is deprecated as of OTP 23, and will be removed in OTP 24. Reasonably new <c>gcc</c> compilers will issue deprecation warnings when using this diff --git a/lib/erl_interface/doc/src/ref_man.xml b/lib/erl_interface/doc/src/ref_man.xml index 064a83a4ba..a0d75128a3 100644 --- a/lib/erl_interface/doc/src/ref_man.xml +++ b/lib/erl_interface/doc/src/ref_man.xml @@ -32,7 +32,6 @@ </description> <xi:include href="ei.xml"/> <xi:include href="ei_connect.xml"/> - <xi:include href="registry.xml"/> <xi:include href="ei_global.xml"/> <xi:include href="erl_call_cmd.xml"/> </application> diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml deleted file mode 100644 index 92858516d9..0000000000 --- a/lib/erl_interface/doc/src/registry.xml +++ /dev/null @@ -1,642 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>1998</year><year>2020</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - 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 - distributed under the License is distributed on an "AS IS" BASIS, - 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> - <prepared>Gordon Beaton</prepared> - <responsible>Gordon Beaton</responsible> - <docno></docno> - <approved>Gordon Beaton</approved> - <checked>Gordon Beaton</checked> - <date>1998-07-07</date> - <rev>A</rev> - <file>registry.xml</file> - </header> - <lib>registry</lib> - <libsummary>Store and back up key-value pairs.</libsummary> - <description> - <note><p>This functionality is deprecated as of OTP 23, and will be - removed in OTP 24. Reasonably new <c>gcc</c> compilers will issue - deprecation warnings. In order to disable these warnings, define the - macro <c>EI_NO_DEPR_WARN</c>.</p></note> - - <p>This module provides support for storing key-value - pairs in a table known as a registry, backing up registries to - <seeerl marker="mnesia:mnesia">Mnesia</seeerl> - in an atomic manner, and later restoring the contents of a - registry from <c>Mnesia</c>.</p> - </description> - - <funcs> - <func> - <name since=""><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>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 since=""><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>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 since=""><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>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 - <seeerl marker="mnesia:mnesia"><c>Mnesia</c></seeerl>.</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 since=""><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>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 since=""><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>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 since=""><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>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 since=""><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>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 since=""><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>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 since=""><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>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 since=""><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 since=""><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name> - <fsummary>Remove deleted objects.</fsummary> - <type> - <v>ei_reg *reg;</v> - </type> - <desc> - <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 since=""><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 since=""><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 since=""><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>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 since=""><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>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 since=""><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>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 since=""><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>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 since=""><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>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 since=""><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>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>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 since=""><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>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> - <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; - int nelem; - int npos; - int collisions; -}; - ]]></code> - <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 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> |