1registry(3)                   C Library Functions                  registry(3)
2
3
4

NAME

6       registry - Store and back up key-value pairs.
7

DESCRIPTION

9       This  module  provides  support  for storing key-value pairs in a table
10       known as a registry, backing up registries to Mnesia in an atomic  man‐
11       ner, and later restoring the contents of a registry from Mnesia.
12

EXPORTS

14       int ei_reg_close(reg)
15
16              Types:
17
18                 ei_reg *reg;
19
20              A  registry  that has previously been created with ei_reg_open()
21              is closed, and all the objects it contains are freed.
22
23              reg is the registry to close.
24
25              Returns 0.
26
27       int ei_reg_delete(reg,key)
28
29              Types:
30
31                 ei_reg *reg;
32                 const char *key;
33
34              Deletes an object from the registry. The object is  not  removed
35              from  the  registry, it is only marked for later removal so that
36              on later backups to Mnesia,  the  corresponding  object  can  be
37              removed  from  the  Mnesia  table  as well. If another object is
38              later created with the same key, the object will be reused.
39
40              The object  is  removed  from  the  registry  after  a  call  to
41              ei_reg_dump() or ei_reg_purge().
42
43                * reg is the registry containing key.
44
45                * key is the object to remove.
46
47              Returns 0 on success, otherwise -1.
48
49       int ei_reg_dump(fd,reg,mntab,flags)
50
51              Types:
52
53                 int fd;
54                 ei_reg *reg;
55                 const char *mntab;
56                 int flags;
57
58              Dumps  the contents of a registry to a Mnesia table in an atomic
59              manner, that is, either all data or no data is updated.  If  any
60              errors  are  encountered  while  backing up the data, the entire
61              operation is aborted.
62
63                * fd is an open connection to Erlang. Mnesia 3.0 or later must
64                  be running on the Erlang node.
65
66                * reg is the registry to back up.
67
68                * mntab  is  the  name of the Mnesia table where the backed up
69                  data is to be placed. If the table does  not  exist,  it  is
70                  created   automatically  using  configurable  defaults.  For
71                  information about configuring this behavior, see Mnesia.
72
73              If flags is 0, the backup includes only those objects that  have
74              been  created,  modified,  or  deleted  since the last backup or
75              restore (that is, an incremental backup). After the backup,  any
76              objects  that  were  marked dirty are now clean, and any objects
77              that had been marked for deletion are deleted.
78
79              Alternatively, setting flags to EI_FORCE causes a full backup to
80              be done, and EI_NOPURGE causes the deleted objects to be left in
81              the registry afterwards. These can be bitwise OR'ed together  if
82              both   behaviors  are  desired.  If  EI_NOPURGE  was  specified,
83              ei_reg_purge() can be used  to  explicitly  remove  the  deleted
84              items from the registry later.
85
86              Returns 0 on success, otherwise -1.
87
88       double ei_reg_getfval(reg,key)
89
90              Types:
91
92                 ei_reg *reg;
93                 const char *key;
94
95              Gets  the  value  associated with key in the registry. The value
96              must be a floating point type.
97
98                * reg is the registry where the object will be looked up.
99
100                * key is the name of the object to look up.
101
102              On success, the function returns the value associated with  key.
103              If  the  object  is  not  found or if it is not a floating point
104              object, -1.0 is returned. To avoid problems with  in-band  error
105              reporting (that is, if you cannot distinguish between -1.0 and a
106              valid result), use the  more  general  function  ei_reg_getval()
107              instead.
108
109       int ei_reg_getival(reg,key)
110
111              Types:
112
113                 ei_reg *reg;
114                 const char *key;
115
116              Gets  the  value  associated with key in the registry. The value
117              must be an integer.
118
119                * reg is the registry where the object will be looked up.
120
121                * key is the name of the object to look up.
122
123              On success, the function returns the value associated with  key.
124              If the object is not found or if it is not an integer object, -1
125              is returned. To avoid  problems  with  in-band  error  reporting
126              (that  is,  if  you  cannot  distinguish  between -1 and a valid
127              result), use the more general function ei_reg_getval() instead.
128
129       const void *ei_reg_getpval(reg,key,size)
130
131              Types:
132
133                 ei_reg *reg;
134                 const char *key;
135                 int size;
136
137              Gets the value associated with key in the  registry.  The  value
138              must be a binary (pointer) type.
139
140                * reg is the registry where the object will be looked up.
141
142                * key is the name of the object to look up.
143
144                * size  is  initialized  to contain the length in bytes of the
145                  object, if it is found.
146
147              On success, the function returns the value associated  with  key
148              and  indicates its length in size. If the object is not found or
149              if it is not a binary object, NULL is returned. To  avoid  prob‐
150              lems  with  in-band error reporting (that is, if you cannot dis‐
151              tinguish between NULL and a valid result), use the more  general
152              function ei_reg_getval() instead.
153
154       const char *ei_reg_getsval(reg,key)
155
156              Types:
157
158                 ei_reg *reg;
159                 const char *key;
160
161              Gets  the  value  associated with key in the registry. The value
162              must be a string.
163
164                * reg is the registry where the object will be looked up.
165
166                * key is the name of the object to look up.
167
168              On success, the function returns the value associated with  key.
169              If  the  object  is  not found or if it is not a string, NULL is
170              returned. To avoid problems with in-band error  reporting  (that
171              is,  if you cannot distinguish between NULL and a valid result),
172              use the more general function ei_reg_getval() instead.
173
174       int ei_reg_getval(reg,key,flags,v,...)
175
176              Types:
177
178                 ei_reg *reg;
179                 const char *key;
180                 int flags;
181                 void *v (see below)
182
183              A general function for retrieving any kind of  object  from  the
184              registry.
185
186                * reg is the registry where the object will be looked up.
187
188                * key is the name of the object to look up.
189
190                * flags indicates the type of object that you are looking for.
191                  If flags is 0, any kind of object is returned. If  flags  is
192                  EI_INT,  EI_FLT, EI_STR, or EI_BIN, then only values of that
193                  kind are returned.
194
195                  The buffer pointed to by v must be large enough to hold  the
196                  return  data,  that  is, it must be a pointer to one of int,
197                  double, char*, or void*, respectively.
198
199                  If flags is EI_BIN, a fifth argument int *size is  required,
200                  so that the size of the object can be returned.
201
202              On  success, v (and size if the object is binary) is initialized
203              with the value associated with key,  and  the  function  returns
204              EI_INT,  EI_FLT,  EI_STR,  or  EI_BIN,  indicating  the  type of
205              object. On failure, -1 is returned and  the  arguments  are  not
206              updated.
207
208       int ei_reg_markdirty(reg,key)
209
210              Types:
211
212                 ei_reg *reg;
213                 const char *key;
214
215              Marks  a  registry  object  as  dirty.  This  ensures that it is
216              included in the next backup to Mnesia. Normally  this  operation
217              is  not necessary, as all of the normal registry 'set' functions
218              do this automatically. However, if you have retrieved the  value
219              of  a string or binary object from the registry and modified the
220              contents, then the change is invisible to the registry  and  the
221              object  is assumed to be unmodified. This function allows you to
222              make such modifications and then let  the  registry  know  about
223              them.
224
225                * reg is the registry containing the object.
226
227                * key is the name of the object to mark.
228
229              Returns 0 on success, otherwise -1.
230
231       ei_reg *ei_reg_open(size)
232
233              Types:
234
235                 int size;
236
237              Opens  (creates)  a registry, which initially is empty. To close
238              the registry later, use ei_reg_close().
239
240              size is the approximate number of objects you intend to store in
241              the  registry.  As the registry uses a hash table with collision
242              chaining, no absolute  upper  limit  exists  on  the  number  of
243              objects  that can be stored in it. However, for reasons of effi‐
244              ciency, it is a good idea to choose a number that is appropriate
245              for  your  needs. To change the size later, use ei_reg_resize().
246              Notice that the number you provide is increased to  the  nearest
247              larger prime number.
248
249              Returns an empty registry on success, otherwise NULL.
250
251       int ei_reg_purge(reg)
252
253              Types:
254
255                 ei_reg *reg;
256
257              Removes  all  objects  marked  for  deletion.  When  objects are
258              deleted with ei_reg_delete() they are not removed from the  reg‐
259              istry,  only marked for later removal. On a later backup to Mne‐
260              sia, the objects can also be removed from the Mnesia  table.  If
261              you  are  not  backing  up to Mnesia, you may wish to remove the
262              objects manually with this function.
263
264              reg is a registry containing objects marked for deletion.
265
266              Returns 0 on success, otherwise -1.
267
268       int ei_reg_resize(reg,newsize)
269
270              Types:
271
272                 ei_reg *reg;
273                 int newsize;
274
275              Changes the size of a registry.
276
277              newsize is the new size to make  the  registry.  The  number  is
278              increased to the nearest larger prime number.
279
280              On  success, the registry is resized, all contents rehashed, and
281              0 is returned. On failure, the registry is left unchanged and -1
282              is returned.
283
284       int ei_reg_restore(fd,reg,mntab)
285
286              Types:
287
288                 int fd;
289                 ei_reg *reg;
290                 const char *mntab;
291
292              The contents of a Mnesia table are read into the registry.
293
294                * fd is an open connection to Erlang. Mnesia 3.0 or later must
295                  be running on the Erlang node.
296
297                * reg is the registry where the data is to be placed.
298
299                * mntab is the name of the Mnesia table to read data from.
300
301              Notice that only tables of a certain  format  can  be  restored,
302              that  is,  those  that  have  been created and backed up to with
303              ei_reg_dump(). If the registry was not empty before  the  opera‐
304              tion, the contents of the table are added to the contents of the
305              registry. If the table contains objects with the  same  keys  as
306              those  already  in  the registry, the registry objects are over‐
307              written with the new values. If the  registry  contains  objects
308              that  were  not  in the table, they are unchanged by this opera‐
309              tion.
310
311              After the restore operation, the entire contents of the registry
312              is  marked  as unmodified. Notice that this includes any objects
313              that were modified before the restore and not overwritten by the
314              restore.
315
316              Returns 0 on success, otherwise -1.
317
318       int ei_reg_setfval(reg,key,f)
319
320              Types:
321
322                 ei_reg *reg;
323                 const char *key;
324                 double f;
325
326              Creates  a  key-value  pair  with the specified key and floating
327              point value f. If an object already exists with  the  same  key,
328              the  new value replaces the old one. If the previous value was a
329              binary or string, it is freed with free().
330
331                * reg is the registry where the object is to be placed.
332
333                * key is the object name.
334
335                * f is the floating point value to assign.
336
337              Returns 0 on success, otherwise -1.
338
339       int ei_reg_setival(reg,key,i)
340
341              Types:
342
343                 ei_reg *reg;
344                 const char *key;
345                 int i;
346
347              Creates a key-value pair with  the  specified  key  and  integer
348              value  i. If an object already exists with the same key, the new
349              value replaces the old one. If the previous value was  a  binary
350              or string, it is freed with free().
351
352                * reg is the registry where the object is to be placed.
353
354                * key is the object name.
355
356                * i is the integer value to assign.
357
358              Returns 0 on success, otherwise -1.
359
360       int ei_reg_setpval(reg,key,p,size)
361
362              Types:
363
364                 ei_reg *reg;
365                 const char *key;
366                 const void *p;
367                 int size;
368
369              Creates a key-value pair with the specified key whose "value" is
370              the binary object pointed to by p. If an object  already  exists
371              with  the  same  key, the new value replaces the old one. If the
372              previous value was a binary or string, it is freed with free().
373
374                * reg is the registry where the object is to be placed.
375
376                * key is the object name.
377
378                * p is a pointer to the binary object. The object itself  must
379                  have  been  created  through  a single call to malloc() or a
380                  similar function, so that the registry can later  delete  it
381                  if necessary by calling free().
382
383                * size is the length in bytes of the binary object.
384
385              Returns 0 on success, otherwise -1.
386
387       int ei_reg_setsval(reg,key,s)
388
389              Types:
390
391                 ei_reg *reg;
392                 const char *key;
393                 const char *s;
394
395              Creates a key-value pair with the specified key whose "value" is
396              the specified string s. If an object  already  exists  with  the
397              same  key,  the  new value replaces the old one. If the previous
398              value was a binary or string, it is freed with free().
399
400                * reg is the registry where the object is to be placed.
401
402                * key is the object name.
403
404                * s is the string to assign. The string itself must have  been
405                  created through a single call to malloc() or similar a func‐
406                  tion, so that the registry can later delete it if  necessary
407                  by calling free().
408
409              Returns 0 on success, otherwise -1.
410
411       int ei_reg_setval(reg,key,flags,v,...)
412
413              Types:
414
415                 ei_reg *reg;
416                 const char *key;
417                 int flags;
418                 v (see below)
419
420              Creates  a  key-value pair with the specified key whose value is
421              specified by v. If an object already exists with the  same  key,
422              the  new value replaces the old one. If the previous value was a
423              binary or string, it is freed with free().
424
425                * reg is the registry where the object is to be placed.
426
427                * key is the object name.
428
429                * flags indicates the type of the object specified by v. Flags
430                  must  be one of EI_INT, EI_FLT, EI_STR, and EI_BIN, indicat‐
431                  ing whether v is int, double, char*, or void*.
432
433                  If flags is EI_BIN, a fifth argument size is required, indi‐
434                  cating the size in bytes of the object pointed to by v.
435
436              If you wish to store an arbitrary pointer in the registry, spec‐
437              ify a size of 0. In this case, the object itself is  not  trans‐
438              ferred by an ei_reg_dump() operation, only the pointer value.
439
440              Returns 0 on success, otherwise -1.
441
442       int ei_reg_stat(reg,key,obuf)
443
444              Types:
445
446                 ei_reg *reg;
447                 const char *key;
448                 struct ei_reg_stat *obuf;
449
450              Returns information about an object.
451
452                * reg is the registry containing the object.
453
454                * key is the object name.
455
456                * obuf  is  a  pointer to an ei_reg_stat structure, defined as
457                  follows:
458
459              struct ei_reg_stat {
460                int attr;
461                int size;
462              };
463
464
465              In attr the attributes of the object are stored as  the  logical
466              OR  of  its  type  (one  of EI_INT, EI_FLT, EI_BIN, and EI_STR),
467              whether it is marked for deletion (EI_DELET), and whether it has
468              been modified since the last backup to Mnesia (EI_DIRTY).
469
470              Field  size indicates the size in bytes required to store EI_STR
471              (including the terminating 0)  and  EI_BIN  objects,  or  0  for
472              EI_INT and EI_FLT.
473
474              Returns 0 and initializes obuf on success, otherwise -1.
475
476       int ei_reg_tabstat(reg,obuf)
477
478              Types:
479
480                 ei_reg *reg;
481                 struct ei_reg_tabstat *obuf;
482
483              Returns information about a registry. Using information returned
484              by this function, you can see whether the size of  the  registry
485              is suitable for the amount of data it contains.
486
487                * reg is the registry to return information about.
488
489                * obuf is a pointer to an ei_reg_tabstat structure, defined as
490                  follows:
491
492              struct ei_reg_tabstat {
493                int size;
494                int nelem;
495                int npos;
496                int collisions;
497              };
498
499
500              Field size indicates the number of hash positions  in  the  reg‐
501              istry.  This is the number you provided when you created or last
502              resized the registry, rounded up to the nearest prime number.
503
504                * nelem indicates the number of elements stored  in  the  reg‐
505                  istry. It includes objects that are deleted but not purged.
506
507                * npos indicates the number of unique positions that are occu‐
508                  pied in the registry.
509
510                * collisions indicates how many elements are sharing positions
511                  in the registry.
512
513              On success, 0 is returned and obuf is initialized to contain ta‐
514              ble statistics, otherwise -1 is returned.
515
516
517
518Ericsson AB                   erl_interface 3.13                   registry(3)
Impressum