diff options
Diffstat (limited to 'lib/erl_interface/doc/src/registry.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/registry.xml | 642 |
1 files changed, 0 insertions, 642 deletions
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> |