.TH registry 3erl "erl_interface 3.9.2" "Ericsson AB" "C Library Functions"
.SH NAME
registry \- Store and back up key-value pairs.
.SH DESCRIPTION
.LP
This module provides support for storing key-value pairs in a table known as a registry, backing up registries to \fBMnesia\fR\& in an atomic manner, and later restoring the contents of a registry from \fIMnesia\fR\&\&.
.SH EXPORTS
.LP
.B
int ei_reg_close(reg)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
.RE
.RE
.RS
.LP
A registry that has previously been created with \fIei_reg_open()\fR\& is closed, and all the objects it contains are freed\&.
.LP
\fIreg\fR\& is the registry to close\&.
.LP
Returns \fI0\fR\&\&.
.RE

.LP
.B
int ei_reg_delete(reg,key)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
.RE
.RE
.RS
.LP
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 \fIMnesia\fR\&, the corresponding object can be removed from the \fIMnesia\fR\& table as well\&. If another object is later created with the same key, the object will be reused\&.
.LP
The object is removed from the registry after a call to \fIei_reg_dump()\fR\& or \fIei_reg_purge()\fR\&\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry containing \fIkey\fR\&\&.
.LP
.TP 2
*
\fIkey\fR\& is the object to remove\&.
.LP
.RE

.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
int ei_reg_dump(fd,reg,mntab,flags)
.br
.RS
.LP
Types:

.RS 3
int fd;
.br
ei_reg *reg;
.br
const char *mntab;
.br
int flags;
.br
.RE
.RE
.RS
.LP
Dumps the contents of a registry to a \fIMnesia\fR\& 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\&.
.RS 2
.TP 2
*
\fIfd\fR\& is an open connection to Erlang\&. \fIMnesia\fR\& 3\&.0 or later must be running on the Erlang node\&. 
.LP
.TP 2
*
\fIreg\fR\& is the registry to back up\&.
.LP
.TP 2
*
\fImntab\fR\& is the name of the \fIMnesia\fR\& 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 \fB\fIMnesia\fR\&\fR\&\&.
.LP
.RE

.LP
If \fIflags\fR\& is \fI0\fR\&, 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\&.
.LP
Alternatively, setting flags to \fIEI_FORCE\fR\& causes a full backup to be done, and \fIEI_NOPURGE\fR\& causes the deleted objects to be left in the registry afterwards\&. These can be bitwise OR\&'ed together if both behaviors are desired\&. If \fIEI_NOPURGE\fR\& was specified, \fIei_reg_purge()\fR\& can be used to explicitly remove the deleted items from the registry later\&.
.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
double ei_reg_getfval(reg,key)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
.RE
.RE
.RS
.LP
Gets the value associated with \fIkey\fR\& in the registry\&. The value must be a floating point type\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object will be looked up\&.
.LP
.TP 2
*
\fIkey\fR\& is the name of the object to look up\&. 
.LP
.RE

.LP
On success, the function returns the value associated with \fIkey\fR\&\&. If the object is not found or if it is not a floating point object, \fI-1\&.0\fR\& is returned\&. To avoid problems with in-band error reporting (that is, if you cannot distinguish between \fI-1\&.0\fR\& and a valid result), use the more general function \fIei_reg_getval()\fR\& instead\&.
.RE

.LP
.B
int ei_reg_getival(reg,key)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
.RE
.RE
.RS
.LP
Gets the value associated with \fIkey\fR\& in the registry\&. The value must be an integer\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object will be looked up\&.
.LP
.TP 2
*
\fIkey\fR\& is the name of the object to look up\&. 
.LP
.RE

.LP
On success, the function returns the value associated with \fIkey\fR\&\&. If the object is not found or if it is not an integer object, \fI-1\fR\& is returned\&. To avoid problems with in-band error reporting (that is, if you cannot distinguish between \fI-1\fR\& and a valid result), use the more general function \fIei_reg_getval()\fR\& instead\&.
.RE

.LP
.B
const void *ei_reg_getpval(reg,key,size)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
int size;
.br
.RE
.RE
.RS
.LP
Gets the value associated with \fIkey\fR\& in the registry\&. The value must be a binary (pointer) type\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object will be looked up\&.
.LP
.TP 2
*
\fIkey\fR\& is the name of the object to look up\&. 
.LP
.TP 2
*
\fIsize\fR\& is initialized to contain the length in bytes of the object, if it is found\&.
.LP
.RE

.LP
On success, the function returns the value associated with \fIkey\fR\& and indicates its length in \fIsize\fR\&\&. If the object is not found or if it is not a binary object, \fINULL\fR\& is returned\&. To avoid problems with in-band error reporting (that is, if you cannot distinguish between \fINULL\fR\& and a valid result), use the more general function \fIei_reg_getval()\fR\& instead\&.
.RE

.LP
.B
const char *ei_reg_getsval(reg,key)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
.RE
.RE
.RS
.LP
Gets the value associated with \fIkey\fR\& in the registry\&. The value must be a string\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object will be looked up\&.
.LP
.TP 2
*
\fIkey\fR\& is the name of the object to look up\&. 
.LP
.RE

.LP
On success, the function returns the value associated with \fIkey\fR\&\&. If the object is not found or if it is not a string, \fINULL\fR\& is returned\&. To avoid problems with in-band error reporting (that is, if you cannot distinguish between \fINULL\fR\& and a valid result), use the more general function \fIei_reg_getval()\fR\& instead\&.
.RE

.LP
.B
int ei_reg_getval(reg,key,flags,v,...)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
int flags;
.br
void *v (see below)
.br
.RE
.RE
.RS
.LP
A general function for retrieving any kind of object from the registry\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object will be looked up\&.
.LP
.TP 2
*
\fIkey\fR\& is the name of the object to look up\&.
.LP
.TP 2
*
\fIflags\fR\& indicates the type of object that you are looking for\&. If \fIflags\fR\& is \fI0\fR\&, any kind of object is returned\&. If \fIflags\fR\& is \fIEI_INT\fR\&, \fIEI_FLT\fR\&, \fIEI_STR\fR\&, or \fIEI_BIN\fR\&, then only values of that kind are returned\&.
.RS 2
.LP
The buffer pointed to by \fIv\fR\& must be large enough to hold the return data, that is, it must be a pointer to one of \fIint\fR\&, \fIdouble\fR\&, \fIchar*\fR\&, or \fIvoid*\fR\&, respectively\&.
.RE

.RS 2
.LP
If \fIflags\fR\& is \fIEI_BIN\fR\&, a fifth argument \fIint *size\fR\& is required, so that the size of the object can be returned\&.
.RE

.LP
.RE

.LP
On success, \fIv\fR\& (and \fIsize\fR\& if the object is binary) is initialized with the value associated with \fIkey\fR\&, and the function returns \fIEI_INT\fR\&, \fIEI_FLT\fR\&, \fIEI_STR\fR\&, or \fIEI_BIN\fR\&, indicating the type of object\&. On failure, \fI-1\fR\& is returned and the arguments are not updated\&.
.RE

.LP
.B
int ei_reg_markdirty(reg,key)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
.RE
.RE
.RS
.LP
Marks a registry object as dirty\&. This ensures that it is included in the next backup to \fIMnesia\fR\&\&. 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\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry containing the object\&. 
.LP
.TP 2
*
\fIkey\fR\& is the name of the object to mark\&. 
.LP
.RE

.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
ei_reg *ei_reg_open(size)
.br
.RS
.LP
Types:

.RS 3
int size;
.br
.RE
.RE
.RS
.LP
Opens (creates) a registry, which initially is empty\&. To close the registry later, use \fIei_reg_close()\fR\&\&.
.LP
\fIsize\fR\& 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 \fIei_reg_resize()\fR\&\&. Notice that the number you provide is increased to the nearest larger prime number\&.
.LP
Returns an empty registry on success, otherwise \fINULL\fR\&\&.
.RE

.LP
.B
int ei_reg_purge(reg)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
.RE
.RE
.RS
.LP
Removes all objects marked for deletion\&. When objects are deleted with \fIei_reg_delete()\fR\& they are not removed from the registry, only marked for later removal\&. On a later backup to \fIMnesia\fR\&, the objects can also be removed from the \fIMnesia\fR\& table\&. If you are not backing up to \fIMnesia\fR\&, you may wish to remove the objects manually with this function\&.
.LP
\fIreg\fR\& is a registry containing objects marked for deletion\&.
.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
int ei_reg_resize(reg,newsize)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
int newsize;
.br
.RE
.RE
.RS
.LP
Changes the size of a registry\&.
.LP
\fInewsize\fR\& is the new size to make the registry\&. The number is increased to the nearest larger prime number\&.
.LP
On success, the registry is resized, all contents rehashed, and \fI0\fR\& is returned\&. On failure, the registry is left unchanged and \fI-1\fR\& is returned\&.
.RE

.LP
.B
int ei_reg_restore(fd,reg,mntab)
.br
.RS
.LP
Types:

.RS 3
int fd;
.br
ei_reg *reg;
.br
const char *mntab;
.br
.RE
.RE
.RS
.LP
The contents of a \fIMnesia\fR\& table are read into the registry\&.
.RS 2
.TP 2
*
\fIfd\fR\& is an open connection to Erlang\&. \fIMnesia\fR\& 3\&.0 or later must be running on the Erlang node\&. 
.LP
.TP 2
*
\fIreg\fR\& is the registry where the data is to be placed\&.
.LP
.TP 2
*
\fImntab\fR\& is the name of the \fIMnesia\fR\& table to read data from\&.
.LP
.RE

.LP
Notice that only tables of a certain format can be restored, that is, those that have been created and backed up to with \fIei_reg_dump()\fR\&\&. 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\&.
.LP
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\&.
.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
int ei_reg_setfval(reg,key,f)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
double f;
.br
.RE
.RE
.RS
.LP
Creates a key-value pair with the specified \fIkey\fR\& and floating point value \fIf\fR\&\&. If an object already exists with the same \fIkey\fR\&, the new value replaces the old one\&. If the previous value was a binary or string, it is freed with \fIfree()\fR\&\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object is to be placed\&.
.LP
.TP 2
*
\fIkey\fR\& is the object name\&.
.LP
.TP 2
*
\fIf\fR\& is the floating point value to assign\&. 
.LP
.RE

.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
int ei_reg_setival(reg,key,i)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
int i;
.br
.RE
.RE
.RS
.LP
Creates a key-value pair with the specified \fIkey\fR\& and integer value \fIi\fR\&\&. If an object already exists with the same \fIkey\fR\&, the new value replaces the old one\&. If the previous value was a binary or string, it is freed with \fIfree()\fR\&\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object is to be placed\&.
.LP
.TP 2
*
\fIkey\fR\& is the object name\&.
.LP
.TP 2
*
\fIi\fR\& is the integer value to assign\&.
.LP
.RE

.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
int ei_reg_setpval(reg,key,p,size)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
const void *p;
.br
int size;
.br
.RE
.RE
.RS
.LP
Creates a key-value pair with the specified \fIkey\fR\& whose "value" is the binary object pointed to by \fIp\fR\&\&. If an object already exists with the same \fIkey\fR\&, the new value replaces the old one\&. If the previous value was a binary or string, it is freed with \fIfree()\fR\&\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object is to be placed\&.
.LP
.TP 2
*
\fIkey\fR\& is the object name\&.
.LP
.TP 2
*
\fIp\fR\& is a pointer to the binary object\&. The object itself must have been created through a single call to \fImalloc()\fR\& or a similar function, so that the registry can later delete it if necessary by calling \fIfree()\fR\&\&.
.LP
.TP 2
*
\fIsize\fR\& is the length in bytes of the binary object\&.
.LP
.RE

.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
int ei_reg_setsval(reg,key,s)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
const char *s;
.br
.RE
.RE
.RS
.LP
Creates a key-value pair with the specified \fIkey\fR\& whose "value" is the specified string \fIs\fR\&\&. If an object already exists with the same \fIkey\fR\&, the new value replaces the old one\&. If the previous value was a binary or string, it is freed with \fIfree()\fR\&\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object is to be placed\&.
.LP
.TP 2
*
\fIkey\fR\& is the object name\&.
.LP
.TP 2
*
\fIs\fR\& is the string to assign\&. The string itself must have been created through a single call to \fImalloc()\fR\& or similar a function, so that the registry can later delete it if necessary by calling \fIfree()\fR\&\&.
.LP
.RE

.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
int ei_reg_setval(reg,key,flags,v,...)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
int flags;
.br
v (see below)
.br
.RE
.RE
.RS
.LP
Creates a key-value pair with the specified \fIkey\fR\& whose value is specified by \fIv\fR\&\&. If an object already exists with the same \fIkey\fR\&, the new value replaces the old one\&. If the previous value was a binary or string, it is freed with \fIfree()\fR\&\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry where the object is to be placed\&.
.LP
.TP 2
*
\fIkey\fR\& is the object name\&.
.LP
.TP 2
*
\fIflags\fR\& indicates the type of the object specified by \fIv\fR\&\&. Flags must be one of \fIEI_INT\fR\&, \fIEI_FLT\fR\&, \fIEI_STR\fR\&, and \fIEI_BIN\fR\&, indicating whether \fIv\fR\& is \fIint\fR\&, \fIdouble\fR\&, \fIchar*\fR\&, or \fIvoid*\fR\&\&.
.RS 2
.LP
If \fIflags\fR\& is \fIEI_BIN\fR\&, a fifth argument \fIsize\fR\& is required, indicating the size in bytes of the object pointed to by \fIv\fR\&\&.
.RE

.LP
.RE

.LP
If you wish to store an arbitrary pointer in the registry, specify a \fIsize\fR\& of \fI0\fR\&\&. In this case, the object itself is not transferred by an \fIei_reg_dump()\fR\& operation, only the pointer value\&.
.LP
Returns \fI0\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
int ei_reg_stat(reg,key,obuf)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
const char *key;
.br
struct ei_reg_stat *obuf;
.br
.RE
.RE
.RS
.LP
Returns information about an object\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry containing the object\&. 
.LP
.TP 2
*
\fIkey\fR\& is the object name\&.
.LP
.TP 2
*
\fIobuf\fR\& is a pointer to an \fIei_reg_stat\fR\& structure, defined as follows:
.LP
.RE

.LP
.nf

struct ei_reg_stat {
  int attr;
  int size;
};
        
.fi
.LP
In \fIattr\fR\& the attributes of the object are stored as the logical \fIOR\fR\& of its type (one of \fIEI_INT\fR\&, \fIEI_FLT\fR\&, \fIEI_BIN\fR\&, and \fIEI_STR\fR\&), whether it is marked for deletion (\fIEI_DELET\fR\&), and whether it has been modified since the last backup to \fIMnesia\fR\& (\fIEI_DIRTY\fR\&)\&.
.LP
Field \fIsize\fR\& indicates the size in bytes required to store \fIEI_STR\fR\& (including the terminating \fI0\fR\&) and \fIEI_BIN\fR\& objects, or \fI0\fR\& for \fIEI_INT\fR\& and \fIEI_FLT\fR\&\&.
.LP
Returns \fI0\fR\& and initializes \fIobuf\fR\& on success, otherwise \fI-1\fR\&\&.
.RE

.LP
.B
int ei_reg_tabstat(reg,obuf)
.br
.RS
.LP
Types:

.RS 3
ei_reg *reg;
.br
struct ei_reg_tabstat *obuf;
.br
.RE
.RE
.RS
.LP
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\&.
.RS 2
.TP 2
*
\fIreg\fR\& is the registry to return information about\&.
.LP
.TP 2
*
\fIobuf\fR\& is a pointer to an \fIei_reg_tabstat\fR\& structure, defined as follows: 
.LP
.RE

.LP
.nf

struct ei_reg_tabstat {
  int size;  
  int nelem; 
  int npos;  
  int collisions; 
};
        
.fi
.LP
Field \fIsize\fR\& 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\&.
.RS 2
.TP 2
*
\fInelem\fR\& indicates the number of elements stored in the registry\&. It includes objects that are deleted but not purged\&.
.LP
.TP 2
*
\fInpos\fR\& indicates the number of unique positions that are occupied in the registry\&.
.LP
.TP 2
*
\fIcollisions\fR\& indicates how many elements are sharing positions in the registry\&.
.LP
.RE

.LP
On success, \fI0\fR\& is returned and \fIobuf\fR\& is initialized to contain table statistics, otherwise \fI-1\fR\& is returned\&.
.RE