Unix/Linux Go Back    


Linux 2.6 - man page for registry (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


registry(3erl)			       C Library Functions			   registry(3erl)

NAME
       registry - Store and backup key-value pairs

DESCRIPTION
       This  module  provides support for storing key-value pairs in a table known as a registry,
       backing up registries to Mnesia in an atomic manner, and later restoring the contents of a
       registry from Mnesia.

EXPORTS
       ei_reg * ei_reg_open(size)

	      Types  int size;

	      Open  (create) a registry. The registry will be initially empty. Use ei_reg_close()
	      to close the registry later.

	      size is the approximate number of objects you intend  to	store  in  the	registry.
	      Since  the registry uses a hash table with collision chaining, there is no absolute
	      upper limit on the number of objects that can be stored in it. However for  reasons
	      of  efficiency,  it  is a good idea to choose a number that is appropriate for your
	      needs. It is possible to use ei_reg_resize() to change the size  later.  Note  that
	      the number you provide will be increased to the nearest larger prime number.

	      On success, an empty registry will be returned. On failure, NULL will be returned.

       int ei_reg_resize(reg,newsize)

	      Types  ei_reg *reg;
		     int newsize;

	      Change the size of a registry.

	      newsize  is  the new size to make the registry. The number will be increased to the
	      nearest larger prime number.

	      On success, the registry will be resized, all contents rehashed, and  the  function
	      will  return  0.	On  failure, the registry will be left unchanged and the function
	      will return -1.

       int ei_reg_close(reg)

	      Types  ei_reg *reg;

	      A registry that has previously been created with ei_reg_open() is closed,  and  all
	      the objects it contains are freed.

	      reg is the registry to close.

	      The function returns 0.

       int ei_reg_setival(reg,key,i)

	      Types  ei_reg *reg;
		     const char *key;
		     int i;

	      Create  a  key-value pair with the specified key and integer value i . If an object
	      already existed with the same key , the new value replaces the old one. If the pre-
	      vious value was a binary or string, it is freed with free() .

	      reg is the registry where the object should be placed.

	      key is the name of the object.

	      i is the integer value to assign.

	      The function returns 0 on success, or -1 on failure.

       int ei_reg_setfval(reg,key,f)

	      Types  ei_reg *reg;
		     const char *key;
		     double f;

	      Create  a  key-value pair with the specified key and floating point value f . If an
	      object already existed with the same key , the new value replaces the old  one.  If
	      the previous value was a binary or string, it is freed with free() .

	      reg is the registry where the object should be placed.

	      key is the name of the object.

	      f is the floating point value to assign.

	      The function returns 0 on success, or -1 on failure.

       int ei_reg_setsval(reg,key,s)

	      Types  ei_reg *reg;
		     const char *key;
		     const char *s;

	      Create  a  key-value  pair  with	the  specified key whose "value" is the specified
	      string s . If an object already existed with the same key , the new value  replaces
	      the  old one. If the previous value was a binary or string, it is freed with free()
	      .

	      reg is the registry where the object should be placed.

	      key is the name of the object.

	      s is the string to assign. The string itself must have been created through a  sin-
	      gle  call to malloc() or similar function, so that the registry can later delete it
	      if necessary by calling free() .

	      The function returns 0 on success, or -1 on failure.

       int ei_reg_setpval(reg,key,p,size)

	      Types  ei_reg *reg;
		     const char *key;
		     const void *p;
		     int size;

	      Create a key-value pair with the specified key whose "value" is the  binary  object
	      pointed  to  by  p . If an object already existed with the same key , the new value
	      replaces the old one. If the previous value was a binary or  string,  it	is  freed
	      with free() .

	      reg is the registry where the object should be placed.

	      key is the name of the object.

	      p  is  a	pointer  to  the  binary object. The object itself must have been created
	      through a single call to malloc() or similar function, so  that  the  registry  can
	      later delete it if necessary by calling free() .

	      size is the length in bytes of the binary object.

	      The function returns 0 on success, or -1 on failure.

       int ei_reg_setval(reg,key,flags,v,...)

	      Types  ei_reg *reg;
		     const char *key;
		     int flags;
		     v (see below)

	      Create  a  key-value pair with the specified key whose value is specified by v . If
	      an object already existed with the same key , the new value replaces the	old  one.
	      If the previous value was a binary or string, it is freed with free() .

	      reg is the registry where the object should be placed.

	      key is the name of the object.

	      flags  indicates	the  type  of  the  object  specified by v . Flags must be one of
	      EI_INT, EI_FLT, EI_STR and EI_BIN, indicating whether v is int , double , char*  or
	      void*  . If flags is EI_BIN, then a fifth argument size is required, indicating the
	      size in bytes of the object pointed to by v .

	      If you wish to store an arbitrary pointer in the registry, specify a size of 0.  In
	      this case, the object itself will not be transferred by an ei_reg_dump() operation,
	      just the pointer value.

	      The function returns 0 on success, or -1 on failure.

       int ei_reg_getival(reg,key)

	      Types  ei_reg *reg;
		     const char *key;

	      Get the value associated with key in the registry. The value must be an integer.

	      reg is the registry where the object will be looked up.

	      key is the name of the object to look up.

	      On success, the function returns the value associated with key . If the object  was
	      not  found  or it was not an integer object, -1 is returned. To avoid problems with
	      in-band error reporting (i.e. if you cannot distinguish  between	-1  and  a  valid
	      result) use the more general function ei_reg_getval() instead.

       double ei_reg_getfval(reg,key)

	      Types  ei_reg *reg;
		     const char *key;

	      Get  the	value  associated  with key in the registry. The value must be a floating
	      point type.

	      reg is the registry where the object will be looked up.

	      key is the name of the object to look up.

	      On success, the function returns the value associated with key . If the object  was
	      not  found  or it was not a floating point object, -1.0 is returned. To avoid prob-
	      lems with in-band error reporting (i.e. if you cannot distinguish between -1.0  and
	      a valid result) use the more general function ei_reg_getval() instead.

       const char * ei_reg_getsval(reg,key)

	      Types  ei_reg *reg;
		     const char *key;

	      Get the value associated with key in the registry. The value must be a string.

	      reg is the registry where the object will be looked up.

	      key is the name of the object to look up.

	      On  success, the function returns the value associated with key . If the object was
	      not found or it was not a string, NULL is returned. To avoid problems with  in-band
	      error  reporting	(i.e.  if you cannot distinguish between NULL and a valid result)
	      use the more general function ei_reg_getval() instead.

       const void * ei_reg_getpval(reg,key,size)

	      Types  ei_reg *reg;
		     const char *key;
		     int size;

	      Get the value associated with key in the registry.  The  value  must  be	a  binary
	      (pointer) type.

	      reg is the registry where the object will be looked up.

	      key is the name of the object to look up.

	      size  will  be  initialized  to contain the length in bytes of the object, if it is
	      found.

	      On success, the function returns the value associated with key  and  indicates  its
	      length in size . If the object was not found or it was not a binary object, NULL is
	      returned. To avoid problems with in-band error reporting (i.e. if you  cannot  dis-
	      tinguish between NULL and a valid result) use the more general function ei_reg_get-
	      val() instead.

       int ei_reg_getval(reg,key,flags,v,...)

	      Types  ei_reg *reg;
		     const char *key;
		     int flags;
		     void *v (see below)

	      This is a general function for retrieving any kind of object from the registry.

	      reg is the registry where the object will be looked up.

	      key is the name of the object to look up.

	      flags indicates the type of object that you are looking for. If flags  is  0,  then
	      any  kind  of object will be returned. If flags is one of EI_INT, EI_FLT, EI_STR or
	      EI_BIN, then only values of that kind will be returned. The buffer pointed to by	v
	      must  be	large enough to hold the return data, i.e. it must be a pointer to one of
	      int , double , char* or void* , respectively. Also, if  flags  is  EI_BIN,  then	a
	      fifth  argument  int  *size  is  required,  so  that  the size of the object can be
	      returned.

	      If the function succeeds, v (and size if the object is binary) will be  initialized
	      with  the  value	associated with key , and the function will return one of EI_INT,
	      EI_FLT, EI_STR or EI_BIN, indicating the type of object. On  failure  the  function
	      will return -1 and the arguments will not be updated.

       int ei_reg_markdirty(reg,key)

	      Types  ei_reg *reg;
		     const char *key;

	      Mark  a  registry object as dirty. This will ensure that it is included in the next
	      backup to Mnesia. Normally this operation will not be necessary since  all  of  the
	      normal  registry	'set'  functions  do  this  automatically.  However  if  you have
	      retrieved the value of a string or binary object from the registry and modified the
	      contents,  then the change will be invisible to the registry and the object will be
	      assumed to be unmodified. This function allows you to make such  modifications  and
	      then let the registry know about them.

	      reg is the registry containing the object.

	      key is the name of the object to mark.

	      The function returns 0 on success, or -1 on failure.

       int ei_reg_delete(reg,key)

	      Types  ei_reg *reg;
		     const char *key;

	      Delete  an  object  from	the registry. The object is not actually removed from the
	      registry, it is only marked for later removal so that on subsequent backups to Mne-
	      sia,  the  corresponding	object	can  be removed from the Mnesia table as well. If
	      another object is later created with the same key, the object will be reused.

	      The object will be removed from the registry  after  a  call  to	ei_reg_dump()  or
	      ei_reg_purge() .

	      reg is the registry containing key .

	      key is the object to remove.

	      If  the  object was found, the function returns 0 indicating success. Otherwise the
	      function returns -1.

       int ei_reg_stat(reg,key,obuf)

	      Types  ei_reg *reg;
		     const char *key;
		     struct ei_reg_stat *obuf;

	      Return information about an object.

	      reg is the registry containing the object.

	      key is the name of the object.

	      obuf is a pointer to an ei_reg_stat structure, defined below:

	      struct ei_reg_stat {
		int attr;
		int size;
	      };

	      In attr the object's attributes are stored as the logical OR of its  type  (one  of
	      EI_INT,  EI_FLT,	EI_BIN	and EI_STR), whether it is marked for deletion (EI_DELET)
	      and whether it has been modified since the last backup to Mnesia (EI_DIRTY).

	      The size field indicates the size in bytes required to store EI_STR (including  the
	      terminating 0) and EI_BIN objects, or 0 for EI_INT and EI_FLT.

	      The function returns 0 and initializes obuf on success, or returns -1 on failure.

       int ei_reg_tabstat(reg,obuf)

	      Types  ei_reg *reg;
		     struct ei_reg_tabstat *obuf;

	      Return  information  about a registry. Using information returned by this function,
	      you can see whether the size of the registry is suitable for the amount of data  it
	      contains.

	      reg is the registry to return information about.

	      obuf is a pointer to an ei_reg_tabstat structure, defined below:

	      struct ei_reg_tabstat {
		int size;
		int nelem;
		int npos;
		int collisions;
	      };

	      The  size field indicates the number of hash positions in the registry. This is the
	      number you provided when you created or last resized the registry,  rounded  up  to
	      the nearest prime.

	      nelem  indicates the number of elements stored in the registry. It includes objects
	      that are deleted but not purged.

	      npos indicates the number of unique positions that are occupied in the registry.

	      collisions indicates how many elements are sharing positions in the registry.

	      On success, the function returns 0 and obuf is initialized to contain table statis-
	      tics. On failure, the function returns -1.

       int ei_reg_dump(fd,reg,mntab,flags)

	      Types  int fd;
		     ei_reg *reg;
		     const char *mntab;
		     int flags;

	      Dump  the contents of a registry to a Mnesia table in an atomic manner, i.e. either
	      all data will be updated, or none of it will. If any errors are  encountered  while
	      backing up the data, the entire operation is aborted.

	      fd  is  an  open	connection  to Erlang. Mnesia 3.0 or later must be running on the
	      Erlang node.

	      reg is the registry to back up.

	      mntab is the name of the Mnesia table where the backed up data should be placed. If
	      the  table  does	not  exist,  it  will be created automatically using configurable
	      defaults. See your Mnesia documentation for information about configuring this  be-
	      haviour.

	      If  flags is 0, the backup will include only those objects which have been created,
	      modified or deleted since the last backup or restore (i.e. an incremental  backup).
	      After the backup, any objects that were marked dirty are now clean, and any objects
	      that had been marked for deletion are deleted.

	      Alternatively, setting flags to EI_FORCE will cause a full backup to be  done,  and
	      EI_NOPURGE  will	cause  the deleted objects to be left in the registry afterwards.
	      These can be bitwise ORed together if both behaviours are  desired.  If  EI_NOPURGE
	      was  specified,  you  can use ei_reg_purge() to explicitly remove the deleted items
	      from the registry later.

	      The function returns 0 on success, or -1 on failure.

       int ei_reg_restore(fd,reg,mntab)

	      Types  int fd;
		     ei_reg *reg;
		     const char *mntab;

	      The contents of a Mnesia table are read into the registry.

	      fd is an open connection to Erlang. Mnesia 3.0 or later  must  be  running  on  the
	      Erlang node.

	      reg is the registry where the data should be placed.

	      mntab is the name of the Mnesia table to read data from.

	      Note  that  only	tables	of a certain format can be restored, i.e. those that have
	      been created and backed up to with ei_reg_dump() . If the registry  was  not  empty
	      before  the  operation, then the contents of the table are added to the contents of
	      the registry. If the table contains objects with the same keys as those already  in
	      the  registry, the registry objects will be overwritten with the new values. If the
	      registry contains objects that were not in the table, they  will	be  unchanged  by
	      this operation.

	      After  the  restore  operation,  the  entire  contents of the registry is marked as
	      unmodified. Note that this includes any  objects	that  were  modified  before  the
	      restore and not overwritten by the restore.

	      The function returns 0 on success, or -1 on failure.

       int ei_reg_purge(reg)

	      Types  ei_reg *reg;

	      Remove   all   objects   marked	for  deletion.	When  objects  are  deleted  with
	      ei_reg_delete() they are not actually removed from the registry,	only  marked  for
	      later  removal.  This  is so that on a subsequent backup to Mnesia, the objects can
	      also be removed from the Mnesia table. If you are not backing up to Mnesia then you
	      may wish to remove the objects manually with this function.

	      reg is a registry containing objects marked for deletion.

	      The function returns 0 on success, or -1 on failure.

Ericsson AB			       erl_interface 3.7.3			   registry(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:57 AM.