dpopen man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

DEPOT(3)		    Quick Database Manager		      DEPOT(3)

NAME
       Depot - the basic API of QDBM

SYNOPSIS
       #include <depot.h>
       #include <stdlib.h>

       extern const char *dpversion;

       extern int dpecode;

       const char *dperrmsg(int ecode);

       DEPOT *dpopen(const char *name, int omode, int bnum);

       int dpclose(DEPOT *depot);

       int  dpput(DEPOT	 *depot, const char *kbuf, int ksiz, const char *vbuf,
       int vsiz, int dmode);

       int dpout(DEPOT *depot, const char *kbuf, int ksiz);

       char *dpget(DEPOT *depot, const char *kbuf, int ksiz,  int  start,  int
       max, int *sp);

       int  dpgetwb(DEPOT  *depot,  const char *kbuf, int ksiz, int start, int
       max, char *vbuf);

       int dpvsiz(DEPOT *depot, const char *kbuf, int ksiz);

       int dpiterinit(DEPOT *depot);

       char *dpiternext(DEPOT *depot, int *sp);

       int dpsetalign(DEPOT *depot, int align);

       int dpsetfbpsiz(DEPOT *depot, int size);

       int dpsync(DEPOT *depot);

       int dpoptimize(DEPOT *depot, int bnum);

       char *dpname(DEPOT *depot);

       int dpfsiz(DEPOT *depot);

       int dpbnum(DEPOT *depot);

       int dpbusenum(DEPOT *depot);

       int dprnum(DEPOT *depot);

       int dpwritable(DEPOT *depot);

       int dpfatalerror(DEPOT *depot);

       int dpinode(DEPOT *depot);

       time_t dpmtime(DEPOT *depot);

       int dpfdesc(DEPOT *depot);

       int dpremove(const char *name);

       int dprepair(const char *name);

       int dpexportdb(DEPOT *depot, const char *name);

       int dpimportdb(DEPOT *depot, const char *name);

       char *dpsnaffle(const char *name, const char *kbuf, int ksiz, int *sp);

       int dpinnerhash(const char *kbuf, int ksiz);

       int dpouterhash(const char *kbuf, int ksiz);

       int dpprimenum(int num);

DESCRIPTION
       Depot is the basic API of QDBM.	Almost all  features  for  managing  a
       database	 provided by QDBM are implemented by Depot.  Other APIs are no
       more than wrappers of Depot.  Depot is the fastest in all APIs of QDBM.

       In order to use Depot, you should include `depot.h' and	`stdlib.h'  in
       the  source files.  Usually, the following description will be near the
       beginning of a source file.

	      #include <depot.h>
	      #include <stdlib.h>

       A pointer to `DEPOT' is used as a database handle.   It	is  like  that
       some  file  I/O routines of `stdio.h' use a pointer to `FILE'.  A data‐
       base handle is opened  with  the	 function  `dpopen'  and  closed  with
       `dpclose'.   You should not refer directly to any member of the handle.
       If a fatal error occurs in a database, any access method via the handle
       except  `dpclose'  will	not  work and return error status.  Although a
       process is allowed to use multiple database handles at the  same	 time,
       handles of the same database file should not be used.

       The  external variable `dpversion' is the string containing the version
       information.

       extern const char *dpversion;

       The external variable `dpecode' is  assigned  with  the	last  happened
       error code.  Refer to `depot.h' for details of the error codes.

       extern int dpecode;
	      The  initial  value  of  this variable is `DP_NOERR'.  The other
	      values are `DP_EFATAL',  `DP_EMODE',  `DP_EBROKEN',  `DP_EKEEP',
	      `DP_ENOITEM',  `DP_EALLOC',  `DP_EMAP', `DP_EOPEN', `DP_ECLOSE',
	      `DP_ETRUNC',  `DP_ESYNC',	 `DP_ESTAT',  `DP_ESEEK',  `DP_EREAD',
	      `DP_EWRITE', `DP_ELOCK', `DP_EUNLINK', `DP_EMKDIR', `DP_ERMDIR',
	      and `DP_EMISC'.

       The function `dperrmsg' is used in order to get a message string corre‐
       sponding to an error code.

       const char *dperrmsg(int ecode);
	      `ecode'  specifies  an error code.  The return value is the mes‐
	      sage string of the error code.  The region of the	 return	 value
	      is not writable.

       The function `dpopen' is used in order to get a database handle.

       DEPOT *dpopen(const char *name, int omode, int bnum);
	      `name' specifies the name of a database file.  `omode' specifies
	      the connection mode: `DP_OWRITER' as a writer, `DP_OREADER' as a
	      reader.  If the mode is `DP_OWRITER', the following may be added
	      by bitwise or: `DP_OCREAT', which means it creates a  new	 data‐
	      base  if	not  exist,  `DP_OTRUNC', which means it creates a new
	      database regardless if one exists.   Both	 of  `DP_OREADER'  and
	      `DP_OWRITER'  can	 be added to by bitwise or: `DP_ONOLCK', which
	      means  it	 opens	a  database  file  without  file  locking,  or
	      `DP_OLCKNB',  which means locking is performed without blocking.
	      `DP_OCREAT' can be added to by bitwise or:  `DP_OSPARSE',	 which
	      means it creates a database file as a sparse file.  `bnum' spec‐
	      ifies the number of elements of the bucket array.	 If it is  not
	      more  than  0,  the  default  value is specified.	 The size of a
	      bucket array is determined on creating, and can not  be  changed
	      except for by optimization of the database.  Suggested size of a
	      bucket array is about from 0.5 to 4 times of the number  of  all
	      records  to  store.   The return value is the database handle or
	      `NULL' if it is not successful.  While connecting as  a  writer,
	      an  exclusive  lock is invoked to the database file.  While con‐
	      necting as a reader, a shared lock is invoked  to	 the  database
	      file.   The  thread  blocks  until  the  lock  is	 achieved.  If
	      `DP_ONOLCK' is used, the application is responsible  for	exclu‐
	      sion control.

       The function `dpclose' is used in order to close a database handle.

       int dpclose(DEPOT *depot);
	      `depot'  specifies a database handle.  If successful, the return
	      value is true, else, it is  false.   Because  the	 region	 of  a
	      closed handle is released, it becomes impossible to use the han‐
	      dle.  Updating a database is assured to be written when the han‐
	      dle  is closed.  If a writer opens a database but does not close
	      it appropriately, the database will be broken.

       The function `dpput' is used in order to store a record.

       int dpput(DEPOT *depot, const char *kbuf, int ksiz, const  char	*vbuf,
       int vsiz, int dmode);
	      `depot'  specifies  a  database  handle  connected  as a writer.
	      `kbuf' specifies the pointer to the region  of  a	 key.	`ksiz'
	      specifies the size of the region of the key.  If it is negative,
	      the size is assigned with `strlen(kbuf)'.	 `vbuf' specifies  the
	      pointer  to the region of a value.  `vsiz' specifies the size of
	      the region of the	 value.	  If  it  is  negative,	 the  size  is
	      assigned	with  `strlen(vbuf)'.  `dmode' specifies behavior when
	      the key overlaps, by the	following  values:  `DP_DOVER',	 which
	      means   the   specified	value  overwrites  the	existing  one,
	      `DP_DKEEP', which means the existing value is  kept,  `DP_DCAT',
	      which  means  the	 specified value is concatenated at the end of
	      the existing value.  If successful, the return  value  is	 true,
	      else, it is false.

       The function `dpout' is used in order to delete a record.

       int dpout(DEPOT *depot, const char *kbuf, int ksiz);
	      `depot'  specifies  a  database  handle  connected  as a writer.
	      `kbuf' specifies the pointer to the region  of  a	 key.	`ksiz'
	      specifies the size of the region of the key.  If it is negative,
	      the size is assigned with `strlen(kbuf)'.	  If  successful,  the
	      return value is true, else, it is false.	false is returned when
	      no record corresponds to the specified key.

       The function `dpget' is used in order to retrieve a record.

       char *dpget(DEPOT *depot, const char *kbuf, int ksiz,  int  start,  int
       max, int *sp);
	      `depot'  specifies  a  database  handle.	 `kbuf'	 specifies the
	      pointer to the region of a key.  `ksiz' specifies	 the  size  of
	      the  region of the key.  If it is negative, the size is assigned
	      with `strlen(kbuf)'.  `start' specifies the  offset  address  of
	      the  beginning  of  the  region  of the value to be read.	 `max'
	      specifies the max size to be read.  If it is negative, the  size
	      to  read is unlimited.  `sp' specifies the pointer to a variable
	      to which the size of the region of the return value is assigned.
	      If  it  is  `NULL',  it  is not used.  If successful, the return
	      value is the pointer to the region of the value  of  the	corre‐
	      sponding record, else, it is `NULL'.  `NULL' is returned when no
	      record corresponds to the specified key or the size of the value
	      of  the  corresponding  record is less than `start'.  Because an
	      additional zero code is appended at the end of the region of the
	      return  value,  the  return  value can be treated as a character
	      string.  Because the region of the  return  value	 is  allocated
	      with  the	 `malloc'  call, it should be released with the `free'
	      call if it is no longer in use.

       The function `dpgetwb' is used in order to retrieve a record and	 write
       the value into a buffer.

       int  dpgetwb(DEPOT  *depot,  const char *kbuf, int ksiz, int start, int
       max, char *vbuf);
	      `depot' specifies	 a  database  handle.	`kbuf'	specifies  the
	      pointer  to  the	region of a key.  `ksiz' specifies the size of
	      the region of the key.  If it is negative, the size is  assigned
	      with  `strlen(kbuf)'.   `start'  specifies the offset address of
	      the beginning of the region of the  value	 to  be	 read.	 `max'
	      specifies the max size to be read.  It shuld be equal to or less
	      than the size of	the  writing  buffer.	`vbuf'	specifies  the
	      pointer  to  a  buffer into which the value of the corresponding
	      record is written.  If successful, the return value is the  size
	      of  the  written	data,  else, it is -1.	-1 is returned when no
	      record corresponds to the specified key or the size of the value
	      of  the corresponding record is less than `start'.  Note that no
	      additional zero code is appended at the end of the region of the
	      writing buffer.

       The  function `dpvsiz' is used in order to get the size of the value of
       a record.

       int dpvsiz(DEPOT *depot, const char *kbuf, int ksiz);
	      `depot' specifies	 a  database  handle.	`kbuf'	specifies  the
	      pointer  to  the	region of a key.  `ksiz' specifies the size of
	      the region of the key.  If it is negative, the size is  assigned
	      with  `strlen(kbuf)'.   If  successful,  the return value is the
	      size of the value of the corresponding record, else, it  is  -1.
	      Because  this  function does not read the entity of a record, it
	      is faster than `dpget'.

       The function `dpiterinit' is used in order to initialize	 the  iterator
       of a database handle.

       int dpiterinit(DEPOT *depot);
	      `depot'  specifies a database handle.  If successful, the return
	      value is true, else, it is false.	 The iterator is used in order
	      to access the key of every record stored in a database.

       The  function  `dpiternext' is used in order to get the next key of the
       iterator.

       char *dpiternext(DEPOT *depot, int *sp);
	      `depot' specifies a database handle.  `sp' specifies the pointer
	      to  a  variable  to  which  the size of the region of the return
	      value is assigned.  If it is `NULL', it is not  used.   If  suc‐
	      cessful,	the  return  value is the pointer to the region of the
	      next key, else, it is `NULL'.  `NULL' is returned when no record
	      is  to  be  get out of the iterator.  Because an additional zero
	      code is appended at the end of the region of the	return	value,
	      the  return value can be treated as a character string.  Because
	      the region of the return value is allocated  with	 the  `malloc'
	      call,  it	 should	 be  released with the `free' call if it is no
	      longer in use.  It is possible to access every record by	itera‐
	      tion  of	calling	 this function.	 However, it is not assured if
	      updating the database is occurred while the iteration.  Besides,
	      the order of this traversal access method is arbitrary, so it is
	      not assured that the order of storing matches  the  one  of  the
	      traversal access.

       The  function `dpsetalign' is used in order to set alignment of a data‐
       base handle.

       int dpsetalign(DEPOT *depot, int align);
	      `depot' specifies a  database  handle  connected	as  a  writer.
	      `align'  specifies  the  size  of alignment.  If successful, the
	      return value is true, else, it is false.	If alignment is set to
	      a	 database,  the	 efficiency of overwriting values is improved.
	      The size of alignment is suggested to be	average	 size  of  the
	      values  of  the records to be stored.  If alignment is positive,
	      padding whose size  is  multiple	number	of  the	 alignment  is
	      placed.	If  alignment  is negative, as `vsiz' is the size of a
	      value, the size of padding is calculated with  `(vsiz  /	pow(2,
	      abs(align)  - 1))'.  Because alignment setting is not saved in a
	      database, you should specify alignment every opening a database.

       The function `dpsetfbpsiz' is used in order to set the size of the free
       block pool of a database handle.

       int dpsetfbpsiz(DEPOT *depot, int size);
	      `depot'  specifies  a  database  handle  connected  as a writer.
	      `size' specifies the size of the free block pool of a  database.
	      If successful, the return value is true, else, it is false.  The
	      default size of the free block pool  is  16.   If	 the  size  is
	      greater,	the space efficiency of overwriting values is improved
	      with the time efficiency sacrificed.

       The function `dpsync' is used in order to synchronize updating contents
       with the file and the device.

       int dpsync(DEPOT *depot);
	      `depot'  specifies  a database handle connected as a writer.  If
	      successful, the return value is true, else, it is	 false.	  This
	      function is useful when another process uses the connected data‐
	      base file.

       The function `dpoptimize' is used in order to optimize a database.

       int dpoptimize(DEPOT *depot, int bnum);
	      `depot' specifies a  database  handle  connected	as  a  writer.
	      `bnum' specifies the number of the elements of the bucket array.
	      If it is not more than 0, the default value  is  specified.   If
	      successful,  the return value is true, else, it is false.	 In an
	      alternating succession of deleting and storing with overwrite or
	      concatenate,  dispensable	 regions accumulate.  This function is
	      useful to do away with them.

       The function `dpname' is used in order to get the name of a database.

       char *dpname(DEPOT *depot);
	      `depot' specifies a database handle.  If successful, the	return
	      value  is the pointer to the region of the name of the database,
	      else, it is `NULL'.  Because the region of the return  value  is
	      allocated with the `malloc' call, it should be released with the
	      `free' call if it is no longer in use.

       The function `dpfsiz' is used in order to get the size  of  a  database
       file.

       int dpfsiz(DEPOT *depot);
	      `depot'  specifies a database handle.  If successful, the return
	      value is the size of the database file, else, it is -1.

       The function `dpbnum' is used in order to get the number	 of  the  ele‐
       ments of the bucket array.

       int dpbnum(DEPOT *depot);
	      `depot'  specifies a database handle.  If successful, the return
	      value is the number of the elements of the bucket	 array,	 else,
	      it is -1.

       The function `dpbusenum' is used in order to get the number of the used
       elements of the bucket array.

       int dpbusenum(DEPOT *depot);
	      `depot' specifies a database handle.  If successful, the	return
	      value  is	 the  number of the used elements of the bucket array,
	      else, it	is  -1.	  This	function  is  inefficient  because  it
	      accesses all elements of the bucket array.

       The function `dprnum' is used in order to get the number of the records
       stored in a database.

       int dprnum(DEPOT *depot);
	      `depot' specifies a database handle.  If successful, the	return
	      value is the number of the records stored in the database, else,
	      it is -1.

       The function `dpwritable' is used in order to check whether a  database
       handle is a writer or not.

       int dpwritable(DEPOT *depot);
	      `depot'  specifies  a database handle.  The return value is true
	      if the handle is a writer, false if not.

       The function `dpfatalerror' is used in order to check whether  a	 data‐
       base has a fatal error or not.

       int dpfatalerror(DEPOT *depot);
	      `depot'  specifies  a database handle.  The return value is true
	      if the database has a fatal error, false if not.

       The function `dpinode' is used in order to get the inode	 number	 of  a
       database file.

       int dpinode(DEPOT *depot);
	      `depot'  specifies  a  database handle.  The return value is the
	      inode number of the database file.

       The function `dpmtime' is used in order to get the last	modified  time
       of a database.

       time_t dpmtime(DEPOT *depot);
	      `depot'  specifies  a  database handle.  The return value is the
	      last modified time of the database.

       The function `dpfdesc' is used in order to get the file descriptor of a
       database file.

       int dpfdesc(DEPOT *depot);
	      `depot'  specifies  a  database handle.  The return value is the
	      file  descriptor	of  the	 database  file.   Handling  the  file
	      descriptor of a database file directly is not suggested.

       The function `dpremove' is used in order to remove a database file.

       int dpremove(const char *name);
	      `name'  specifies	 the  name of a database file.	If successful,
	      the return value is true, else, it is false.

       The function `dprepair' is used in order to repair  a  broken  database
       file.

       int dprepair(const char *name);
	      `name'  specifies	 the  name of a database file.	If successful,
	      the return value is true, else, it is false.  There is no	 guar‐
	      antee that all records in a repaired database file correspond to
	      the original or expected state.

       The function `dpexportdb' is used in  order  to	dump  all  records  as
       endian independent data.

       int dpexportdb(DEPOT *depot, const char *name);
	      `depot'  specifies a database handle.  `name' specifies the name
	      of an output file.  If successful, the  return  value  is	 true,
	      else, it is false.

       The  function  `dpimportdb'  is	used in order to load all records from
       endian independent data.

       int dpimportdb(DEPOT *depot, const char *name);
	      `depot' specifies a database handle connected as a writer.   The
	      database of the handle must be empty.  `name' specifies the name
	      of an input file.	 If successful,	 the  return  value  is	 true,
	      else, it is false.

       The function `dpsnaffle' is used in order to retrieve a record directly
       from a database file.

       char *dpsnaffle(const char *name, const char *kbuf, int ksiz, int *sp);
	      `name' specifies the name of a database file.  `kbuf'  specifies
	      the  pointer  to the region of a key.  `ksiz' specifies the size
	      of the region of the key.	  If  it  is  negative,	 the  size  is
	      assigned	with  `strlen(kbuf)'.  `sp' specifies the pointer to a
	      variable to which the size of the region of the return value  is
	      assigned.	  If it is `NULL', it is not used.  If successful, the
	      return value is the pointer to the region of the	value  of  the
	      corresponding  record,  else,  it is `NULL'.  `NULL' is returned
	      when no record corresponds to the	 specified  key.   Because  an
	      additional zero code is appended at the end of the region of the
	      return value, the return value can be  treated  as  a  character
	      string.	Because	 the  region  of the return value is allocated
	      with the `malloc' call, it should be released  with  the	`free'
	      call  if	it is no longer in use.	 Although this function can be
	      used even while the database file is locked by another  process,
	      it is not assured that recent updated is reflected.

       The function `dpinnerhash' is a hash function used inside Depot.

       int dpinnerhash(const char *kbuf, int ksiz);
	      `kbuf'  specifies	 the  pointer  to the region of a key.	`ksiz'
	      specifies the size of the region of the key.  If it is negative,
	      the  size	 is assigned with `strlen(kbuf)'.  The return value is
	      the hash value of 31 bits length computed from  the  key.	  This
	      function	is  useful when an application calculates the state of
	      the inside bucket array.

       The function `dpouterhash' is a hash function which is independent from
       the hash functions used inside Depot.

       int dpouterhash(const char *kbuf, int ksiz);
	      `kbuf'  specifies	 the  pointer  to the region of a key.	`ksiz'
	      specifies the size of the region of the key.  If it is negative,
	      the  size	 is assigned with `strlen(kbuf)'.  The return value is
	      the hash value of 31 bits length computed from  the  key.	  This
	      function	is  useful when an application uses its own hash algo‐
	      rithm outside Depot.

       The function `dpprimenum' is used in order to get a natural prime  num‐
       ber not less than a number.

       int dpprimenum(int num);
	      `num' specified a natural number.	 The return value is a natural
	      prime number not less than the specified number.	This  function
	      is  useful  when	an application determines the size of a bucket
	      array of its own hash algorithm.

       If QDBM was built  with	POSIX  thread  enabled,	 the  global  variable
       `dpecode'  is  treated  as thread specific data, and functions of Depot
       are reentrant.  In that case, they are thread-safe as long as a	handle
       is  not	accessed  by  threads at the same time, on the assumption that
       `errno', `malloc', and so on are thread-safe.

SEE ALSO
       qdbm(3), curia(3), relic(3), hovel(3),  cabin(3),  villa(3),  odeum(3),
       ndbm(3), gdbm(3)

Man Page			  2004-04-22			      DEPOT(3)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net