Filewatcher File Search File Search
Catalog
Content Search
» » » » » libqdbm-dev_1.8.74-1.1_i386.deb » Content »
pkg://libqdbm-dev_1.8.74-1.1_i386.deb:221800/usr/share/man/man3/  info  control  downloads

libqdbm-dev - QDBM Database Libraries [development]…  more info»

curia.3.gz

CURIA(3)               Quick Database Manager               CURIA(3)



NAME
       Curia - the extended API of QDBM


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

       CURIA  *cropen(const  char  *name,  int  omode, int bnum, int
       dnum);

       int crclose(CURIA *curia);

       int crput(CURIA *curia, const char  *kbuf,  int  ksiz,  const
       char *vbuf, int vsiz, int dmode);

       int crout(CURIA *curia, const char *kbuf, int ksiz);

       char  *crget(CURIA  *curia,  const  char *kbuf, int ksiz, int
       start, int max, int *sp);

       int crgetwb(CURIA *curia, const char  *kbuf,  int  ksiz,  int
       start, int max, char *vbuf);

       int crvsiz(CURIA *curia, const char *kbuf, int ksiz);

       int criterinit(CURIA *curia);

       char *criternext(CURIA *curia, int *sp);

       int crsetalign(CURIA *curia, int align);

       int crsetfbpsiz(CURIA *curia, int size);

       int crsync(CURIA *curia);

       int croptimize(CURIA *curia, int bnum);

       char *crname(CURIA *curia);

       int crfsiz(CURIA *curia);

       double crfsizd(CURIA *curia);

       int crbnum(CURIA *curia);

       int crbusenum(CURIA *curia);

       int crrnum(CURIA *curia);

       int crwritable(CURIA *curia);

       int crfatalerror(CURIA *curia);

       int crinode(CURIA *curia);

       time_t crmtime(CURIA *curia);

       int crremove(const char *name);

       int crrepair(const char *name);

       int crexportdb(CURIA *curia, const char *name);

       int crimportdb(CURIA *curia, const char *name);

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

       int crputlob(CURIA *curia, const char *kbuf, int ksiz,  const
       char *vbuf, int vsiz, int dmode);

       int croutlob(CURIA *curia, const char *kbuf, int ksiz);

       char  *crgetlob(CURIA *curia, const char *kbuf, int ksiz, int
       start, int max, int *sp);

       int crgetlobfd(CURIA *curia, const char *kbuf, int ksiz);

       int crvsizlob(CURIA *curia, const char *kbuf, int ksiz);

       int crrnumlob(CURIA *curia);


DESCRIPTION
       Curia is the extended API of QDBM.  It provides routines  for
       managing  multiple  database  files in a directory.  Restric‐
       tions of some file systems that the size of each file is lim‐
       ited  are  escaped  by  dividing  a database file into two or
       more.  If the database files deploy on multiple devices,  the
       scalability is improved.

       Although  Depot  creates  a  database with a file name, Curia
       creates a database with a directory name.   A  database  file
       named  as  `depot'  is  placed  in  the  specified directory.
       Although it keeps the attribute of the database, it does  not
       keep  the  entities of the records.  Besides, sub directories
       are created by the number of division of the database,  named
       with  4  digits.  The database files are placed in the subdi‐
       rectories.  The entities of the records  are  stored  in  the
       database  file.   For  example,  in  the case that a database
       directory named as `casket' and the number of division is  3,
       `casket/depot',  `casket/0001/depot', `casket/0002/depot' and
       `casket/0003/depot' are created.  No error occurs even if the
       namesake  directory  exists when creating a database.  So, if
       sub directories exists and some devices are  mounted  on  the
       sub  directories,  the  database files deploy on the multiple
       devices.  It is possible for the database files to deploy  on
       multiple file servers using NFS and so on.

       Curia   features  managing  large  objects.   Although  usual
       records are stored in some database files, records  of  large
       objects are stored in individual files.  Because the files of
       large objects are deployed  in  different  directories  named
       with  the  hash  values,  the access speed is part-way robust
       although it is slower than the speed of usual records.  Large
       and  not  often  accessed  data  should  be secluded as large
       objects.  By doing this, the access speed of usual records is
       improved.   The  directory  hierarchies  of large objects are
       placed in the directory named as `lob' in the sub directories
       of the database.  Because the key spaces of the usual records
       and the large objects are different, the operations keep  out
       of each other.

       In   order  to  use  Curia,  you  should  include  `depot.h',
       `curia.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 <curia.h>
              #include <stdlib.h>

       A pointer to `CURIA' is used as a  database  handle.   It  is
       like  that  some file I/O routines of `stdio.h' use a pointer
       to `FILE'.  A database handle is  opened  with  the  function
       `cropen'  and  closed  with  `crclose'.  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
       `crclose' 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 directory should  not
       be used.

       Curia  also  assign  the external variable `dpecode' with the
       error code.  The function `dperrmsg' is used in order to  get
       the message of the error code.

       The function `cropen' is used in order to get a database han‐
       dle.

       CURIA *cropen(const char *name,  int  omode,  int  bnum,  int
       dnum);
              `name'  specifies  the  name  of a database directory.
              `omode' specifies the connection mode: `CR_OWRITER' as
              a  writer,  `CR_OREADER'  as a reader.  If the mode is
              `CR_OWRITER', the following may be  added  by  bitwise
              or: `CR_OCREAT', which means it creates a new database
              if not exist, `CR_OTRUNC', which means  it  creates  a
              new  database  regardless  if  one  exists.   Both  of
              `CR_OREADER' and `CR_OWRITER' can be added to by  bit‐
              wise  or: `CR_ONOLCK', which means it opens a database
              directory without file locking, or `CR_OLCKNB',  which
              means   locking   is   performed   without   blocking.
              `CR_OCREAT'  can  be   added   to   by   bitwise   or:
              `CR_OSPARSE', which means it creates database files as
              sparse files.  `bnum' specifies the number of elements
              of  each  bucket array.  If it is not more than 0, the
              default value is specified.  The size of  each  bucket
              array  is  determined  on  creating,  and  can  not be
              changed except for by optimization  of  the  database.
              Suggested  size of each bucket array is about from 0.5
              to 4 times of the number  of  all  records  to  store.
              `dnum'  specifies  the number of division of the data‐
              base.  If it is not more than 0, the default value  is
              specified.   The number of division can not be changed
              from the initial value.  The max number of division is
              512.   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
              directory.  While connecting as  a  reader,  a  shared
              lock is invoked to the database directory.  The thread
              blocks until the lock is achieved.  If `CR_ONOLCK'  is
              used,  the  application  is  responsible for exclusion
              control.

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

       int crclose(CURIA *curia);
              `curia'  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 handle.  Updating a database  is
              assured to be written when the handle is closed.  If a
              writer opens a database but does not close  it  appro‐
              priately, the database will be broken.

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

       int  crput(CURIA  *curia,  const  char *kbuf, int ksiz, const
       char *vbuf, int vsiz, int dmode);
              `curia' 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  val‐
              ues: `CR_DOVER', which means the specified value over‐
              writes the existing one, `CR_DKEEP', which  means  the
              existing  value  is  kept,  `CR_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 `crout' is used in order to delete a record.

       int crout(CURIA *curia, const char *kbuf, int ksiz);
              `curia' 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 `crget' is used in order to retrieve a record.

       char *crget(CURIA *curia, const char  *kbuf,  int  ksiz,  int
       start, int max, int *sp);
              `curia' 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 corresponding record, else,
              it  is `NULL'.  `NULL' is returned when no record cor‐
              responds 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 `mal‐
              loc' call, it should be released with the `free'  call
              if it is no longer in use.

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

       int crgetwb(CURIA *curia, const char  *kbuf,  int  ksiz,  int
       start, int max, char *vbuf);
              `curia' 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 cor‐
              responding 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 `crvsiz' is used in order to get the size of the
       value of a record.

       int crvsiz(CURIA *curia, const char *kbuf, int ksiz);
              `curia' 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 success‐
              ful,  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 `crget'.

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

       int criterinit(CURIA *curia);
              `curia'  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 `criternext' is used in order to  get  the  next
       key of the iterator.

       char *criternext(CURIA *curia, int *sp);
              `curia'  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  successful,  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 addi‐
              tional 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 iteration 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  `crsetalign' is used in order to set alignment
       of a database handle.

       int crsetalign(CURIA *curia, int align);
              `curia' 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 effi‐
              ciency of overwriting values is improved.  The size of
              alignment  is suggested to be average size of the val‐
              ues of the records to be stored.  If alignment is pos‐
              itive,  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 `crsetfbpsiz' is used in order to set  the  size
       of the free block pool of a database handle.

       int crsetfbpsiz(CURIA *curia, int size);
              `curia'  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 `crsync' is used in order to synchronize updat‐
       ing contents with the files and the devices.

       int crsync(CURIA *curia);
              `curia' 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 database directory.

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

       int croptimize(CURIA *curia, int bnum);
              `curia' specifies a database  handle  connected  as  a
              writer.   `bnum'  specifies the number of the elements
              of each bucket array.  If it is not more than  0,  the
              default value is specified.  In an alternating succes‐
              sion of deleting and storing with  overwrite  or  con‐
              catenate,  dispensable regions accumulate.  This func‐
              tion is useful to do away with them.

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

       char *crname(CURIA *curia);
              `curia'  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 `mal‐
              loc'  call, it should be released with the `free' call
              if it is no longer in use.

       The function `crfsiz' is used in order to get the total  size
       of database files.

       int crfsiz(CURIA *curia);
              `curia'  specifies  a database handle.  If successful,
              the return value is the total  size  of  the  database
              files, else, it is -1.  If the total size is more than
              2GB, the return value overflows.

       The function `crfsizd' is used in order to get the total size
       of database files as double-precision floating-point number.

       double crfsizd(CURIA *curia);
              `curia'  specifies  a database handle.  If successful,
              the return value is the total  size  of  the  database
              files, else, it is -1.0.

       The  function `crbnum' is used in order to get the total num‐
       ber of the elements of each bucket array.

       int crbnum(CURIA *curia);
              `curia' specifies a database handle.   If  successful,
              the  return  value is the total number of the elements
              of each bucket array, else, it is -1.

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

       int crbusenum(CURIA *curia);
              `curia'  specifies  a database handle.  If successful,
              the return value is the total number of the used  ele‐
              ments  of  each  bucket  array,  else, it is -1.  This
              function is inefficient because it accesses  all  ele‐
              ments of each bucket array.

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

       int crrnum(CURIA *curia);
              `curia' 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 `crwritable' is used in order to check whether a
       database handle is a writer or not.

       int crwritable(CURIA *curia);
              `curia' specifies a database handle.  The return value
              is true if the handle is a writer, false if not.

       The function `crfatalerror' is used in order to check whether
       a database has a fatal error or not.

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

       The function `crinode' is used in order to get the inode num‐
       ber of a database directory.

       int crinode(CURIA *curia);
              `curia' specifies a database handle.  The return value
              is the inode number of the database directory.

       The function `crmtime' is used in order to get the last modi‐
       fied time of a database.

       time_t crmtime(CURIA *curia);
              `curia' specifies a database handle.  The return value
              is the last modified time of the database.

       The function `crremove' is used in order to remove a database
       directory.

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

       The function `crrepair' is used in order to repair  a  broken
       database directory.

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

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

       int crexportdb(CURIA *curia, const char *name);
              `curia' specifies a database handle.  `name' specifies
              the  name  of an output directory.  If successful, the
              return value is true, else, it is  false.   Note  that
              large objects are ignored.

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

       int crimportdb(CURIA *curia, const char *name);
              `curia' specifies a database  handle  connected  as  a
              writer.   The  database  of  the handle must be empty.
              `name' specifies the name of an input  directory.   If
              successful,  the  return  value  is  true, else, it is
              false.  Note that large objects are ignored.

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

       char *crsnaffle(const char *name, const char *kbuf, int ksiz,
       int *sp);
              `name' specifies the name  of  a  database  directory.
              `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 vari‐
              able  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 cor‐
              responds 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  directory is locked by another process,
              it is not assured that recent updated is reflected.

       The function `crputlob' is used in order  to  store  a  large
       object.

       int  crputlob(CURIA *curia, const char *kbuf, int ksiz, const
       char *vbuf, int vsiz, int dmode);
              `curia' 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  val‐
              ues: `CR_DOVER', which means the specified value over‐
              writes the existing one, `CR_DKEEP', which  means  the
              existing  value  is  kept,  `CR_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 `croutlob' is used in order to  delete  a  large
       object.

       int croutlob(CURIA *curia, const char *kbuf, int ksiz);
              `curia'  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
              large object corresponds to the specified key.

       The  function `crgetlob' is used in order to retrieve a large
       object.

       char *crgetlob(CURIA *curia, const char *kbuf, int ksiz,  int
       start, int max, int *sp);
              `curia' 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 corresponding large object,
              else,  it is `NULL'.  `NULL' is returned when no large
              object corresponds to the specified key or the size of
              the  value  of  the corresponding large object 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  `crgetlobfd'  is used in order to get the file
       descriptor of a large object.

       int crgetlobfd(CURIA *curia, const char *kbuf, int ksiz);
              `curia' 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 success‐
              ful, the return value is the file  descriptor  of  the
              corresponding  large  object,  else,  it is -1.  -1 is
              returned when no large object corresponds to the spec‐
              ified  key.   The  returned  file descriptor is opened
              with the `open' call.   If  the  database  handle  was
              opened   as  a  writer,  the  descriptor  is  writable
              (O_RDWR), else, it is not  writable  (O_RDONLY).   The
              descriptor  should  be closed with the `close' call if
              it is no longer in use.

       The function `crvsizlob' is used in order to get the size  of
       the value of a large object.

       int crvsizlob(CURIA *curia, const char *kbuf, int ksiz);
              `curia' 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 success‐
              ful,  the return value is the size of the value of the
              corresponding large object, else, it is  -1.   Because
              this  function  does  not  read  the entity of a large
              object, it is faster than `crgetlob'.

       The function `crrnumlob' is used in order to get  the  number
       of the large objects stored in a database.

       int crrnumlob(CURIA *curia);
              `curia'  specifies  a database handle.  If successful,
              the return value is the number of  the  large  objects
              stored in the database, else, it is -1.

       If QDBM was built with POSIX thread enabled, the global vari‐
       able `dpecode' is treated as thread specific data, and  func‐
       tions  of  Curia  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), depot(3), relic(3),  hovel(3),  cabin(3),  villa(3),
       odeum(3), ndbm(3), gdbm(3)



Man Page                     2004-04-22                     CURIA(3)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017 FileWatcher.com