1DEPOT(3)                    Quick Database Manager                    DEPOT(3)
2
3
4

NAME

6       Depot - the basic API of QDBM
7
8

SYNOPSIS

10       #include <depot.h>
11       #include <stdlib.h>
12
13       extern const char *dpversion;
14
15       extern int dpecode;
16
17       const char *dperrmsg(int ecode);
18
19       DEPOT *dpopen(const char *name, int omode, int bnum);
20
21       int dpclose(DEPOT *depot);
22
23       int  dpput(DEPOT  *depot, const char *kbuf, int ksiz, const char *vbuf,
24       int vsiz, int dmode);
25
26       int dpout(DEPOT *depot, const char *kbuf, int ksiz);
27
28       char *dpget(DEPOT *depot, const char *kbuf, int ksiz,  int  start,  int
29       max, int *sp);
30
31       int  dpgetwb(DEPOT  *depot,  const char *kbuf, int ksiz, int start, int
32       max, char *vbuf);
33
34       int dpvsiz(DEPOT *depot, const char *kbuf, int ksiz);
35
36       int dpiterinit(DEPOT *depot);
37
38       char *dpiternext(DEPOT *depot, int *sp);
39
40       int dpsetalign(DEPOT *depot, int align);
41
42       int dpsetfbpsiz(DEPOT *depot, int size);
43
44       int dpsync(DEPOT *depot);
45
46       int dpoptimize(DEPOT *depot, int bnum);
47
48       char *dpname(DEPOT *depot);
49
50       int dpfsiz(DEPOT *depot);
51
52       int dpbnum(DEPOT *depot);
53
54       int dpbusenum(DEPOT *depot);
55
56       int dprnum(DEPOT *depot);
57
58       int dpwritable(DEPOT *depot);
59
60       int dpfatalerror(DEPOT *depot);
61
62       int dpinode(DEPOT *depot);
63
64       time_t dpmtime(DEPOT *depot);
65
66       int dpfdesc(DEPOT *depot);
67
68       int dpremove(const char *name);
69
70       int dprepair(const char *name);
71
72       int dpexportdb(DEPOT *depot, const char *name);
73
74       int dpimportdb(DEPOT *depot, const char *name);
75
76       char *dpsnaffle(const char *name, const char *kbuf, int ksiz, int *sp);
77
78       int dpinnerhash(const char *kbuf, int ksiz);
79
80       int dpouterhash(const char *kbuf, int ksiz);
81
82       int dpprimenum(int num);
83
84

DESCRIPTION

86       Depot is the basic API of QDBM.  Almost all  features  for  managing  a
87       database  provided by QDBM are implemented by Depot.  Other APIs are no
88       more than wrappers of Depot.  Depot is the fastest in all APIs of QDBM.
89
90       In order to use Depot, you should include `depot.h' and  `stdlib.h'  in
91       the  source files.  Usually, the following description will be near the
92       beginning of a source file.
93
94              #include <depot.h>
95              #include <stdlib.h>
96
97       A pointer to `DEPOT' is used as a database handle.   It  is  like  that
98       some  file  I/O routines of `stdio.h' use a pointer to `FILE'.  A data‐
99       base handle is opened  with  the  function  `dpopen'  and  closed  with
100       `dpclose'.   You should not refer directly to any member of the handle.
101       If a fatal error occurs in a database, any access method via the handle
102       except  `dpclose'  will  not  work and return error status.  Although a
103       process is allowed to use multiple database handles at the  same  time,
104       handles of the same database file should not be used.
105
106       The  external variable `dpversion' is the string containing the version
107       information.
108
109       extern const char *dpversion;
110
111       The external variable `dpecode' is  assigned  with  the  last  happened
112       error code.  Refer to `depot.h' for details of the error codes.
113
114       extern int dpecode;
115              The  initial  value  of  this variable is `DP_NOERR'.  The other
116              values are `DP_EFATAL',  `DP_EMODE',  `DP_EBROKEN',  `DP_EKEEP',
117              `DP_ENOITEM',  `DP_EALLOC',  `DP_EMAP', `DP_EOPEN', `DP_ECLOSE',
118              `DP_ETRUNC',  `DP_ESYNC',  `DP_ESTAT',  `DP_ESEEK',  `DP_EREAD',
119              `DP_EWRITE', `DP_ELOCK', `DP_EUNLINK', `DP_EMKDIR', `DP_ERMDIR',
120              and `DP_EMISC'.
121
122       The function `dperrmsg' is used in order to get a message string corre‐
123       sponding to an error code.
124
125       const char *dperrmsg(int ecode);
126              `ecode'  specifies  an error code.  The return value is the mes‐
127              sage string of the error code.  The region of the  return  value
128              is not writable.
129
130       The function `dpopen' is used in order to get a database handle.
131
132       DEPOT *dpopen(const char *name, int omode, int bnum);
133              `name' specifies the name of a database file.  `omode' specifies
134              the connection mode: `DP_OWRITER' as a writer, `DP_OREADER' as a
135              reader.  If the mode is `DP_OWRITER', the following may be added
136              by bitwise or: `DP_OCREAT', which means it creates a  new  data‐
137              base  if  not  exist,  `DP_OTRUNC', which means it creates a new
138              database regardless if one exists.   Both  of  `DP_OREADER'  and
139              `DP_OWRITER'  can  be added to by bitwise or: `DP_ONOLCK', which
140              means  it  opens  a  database  file  without  file  locking,  or
141              `DP_OLCKNB',  which means locking is performed without blocking.
142              `DP_OCREAT' can be added to by bitwise or:  `DP_OSPARSE',  which
143              means it creates a database file as a sparse file.  `bnum' spec‐
144              ifies the number of elements of the bucket array.  If it is  not
145              more  than  0,  the  default  value is specified.  The size of a
146              bucket array is determined on creating, and can not  be  changed
147              except for by optimization of the database.  Suggested size of a
148              bucket array is about from 0.5 to 4 times of the number  of  all
149              records  to  store.   The return value is the database handle or
150              `NULL' if it is not successful.  While connecting as  a  writer,
151              an  exclusive  lock is invoked to the database file.  While con‐
152              necting as a reader, a shared lock is invoked  to  the  database
153              file.   The  thread  blocks  until  the  lock  is  achieved.  If
154              `DP_ONOLCK' is used, the application is responsible  for  exclu‐
155              sion control.
156
157       The function `dpclose' is used in order to close a database handle.
158
159       int dpclose(DEPOT *depot);
160              `depot'  specifies a database handle.  If successful, the return
161              value is true, else, it is  false.   Because  the  region  of  a
162              closed handle is released, it becomes impossible to use the han‐
163              dle.  Updating a database is assured to be written when the han‐
164              dle  is closed.  If a writer opens a database but does not close
165              it appropriately, the database will be broken.
166
167       The function `dpput' is used in order to store a record.
168
169       int dpput(DEPOT *depot, const char *kbuf, int ksiz, const  char  *vbuf,
170       int vsiz, int dmode);
171              `depot'  specifies  a  database  handle  connected  as a writer.
172              `kbuf' specifies the pointer to the region  of  a  key.   `ksiz'
173              specifies the size of the region of the key.  If it is negative,
174              the size is assigned with `strlen(kbuf)'.  `vbuf' specifies  the
175              pointer  to the region of a value.  `vsiz' specifies the size of
176              the region of the  value.   If  it  is  negative,  the  size  is
177              assigned  with  `strlen(vbuf)'.  `dmode' specifies behavior when
178              the key overlaps, by the  following  values:  `DP_DOVER',  which
179              means   the   specified   value  overwrites  the  existing  one,
180              `DP_DKEEP', which means the existing value is  kept,  `DP_DCAT',
181              which  means  the  specified value is concatenated at the end of
182              the existing value.  If successful, the return  value  is  true,
183              else, it is false.
184
185       The function `dpout' is used in order to delete a record.
186
187       int dpout(DEPOT *depot, const char *kbuf, int ksiz);
188              `depot'  specifies  a  database  handle  connected  as a writer.
189              `kbuf' specifies the pointer to the region  of  a  key.   `ksiz'
190              specifies the size of the region of the key.  If it is negative,
191              the size is assigned with `strlen(kbuf)'.   If  successful,  the
192              return value is true, else, it is false.  false is returned when
193              no record corresponds to the specified key.
194
195       The function `dpget' is used in order to retrieve a record.
196
197       char *dpget(DEPOT *depot, const char *kbuf, int ksiz,  int  start,  int
198       max, int *sp);
199              `depot'  specifies  a  database  handle.   `kbuf'  specifies the
200              pointer to the region of a key.  `ksiz' specifies  the  size  of
201              the  region of the key.  If it is negative, the size is assigned
202              with `strlen(kbuf)'.  `start' specifies the  offset  address  of
203              the  beginning  of  the  region  of the value to be read.  `max'
204              specifies the max size to be read.  If it is negative, the  size
205              to  read is unlimited.  `sp' specifies the pointer to a variable
206              to which the size of the region of the return value is assigned.
207              If  it  is  `NULL',  it  is not used.  If successful, the return
208              value is the pointer to the region of the value  of  the  corre‐
209              sponding record, else, it is `NULL'.  `NULL' is returned when no
210              record corresponds to the specified key or the size of the value
211              of  the  corresponding  record is less than `start'.  Because an
212              additional zero code is appended at the end of the region of the
213              return  value,  the  return  value can be treated as a character
214              string.  Because the region of the  return  value  is  allocated
215              with  the  `malloc'  call, it should be released with the `free'
216              call if it is no longer in use.
217
218       The function `dpgetwb' is used in order to retrieve a record and  write
219       the value into a buffer.
220
221       int  dpgetwb(DEPOT  *depot,  const char *kbuf, int ksiz, int start, int
222       max, char *vbuf);
223              `depot' specifies  a  database  handle.   `kbuf'  specifies  the
224              pointer  to  the  region of a key.  `ksiz' specifies the size of
225              the region of the key.  If it is negative, the size is  assigned
226              with  `strlen(kbuf)'.   `start'  specifies the offset address of
227              the beginning of the region of the  value  to  be  read.   `max'
228              specifies the max size to be read.  It shuld be equal to or less
229              than the size of  the  writing  buffer.   `vbuf'  specifies  the
230              pointer  to  a  buffer into which the value of the corresponding
231              record is written.  If successful, the return value is the  size
232              of  the  written  data,  else, it is -1.  -1 is returned when no
233              record corresponds to the specified key or the size of the value
234              of  the corresponding record is less than `start'.  Note that no
235              additional zero code is appended at the end of the region of the
236              writing buffer.
237
238       The  function `dpvsiz' is used in order to get the size of the value of
239       a record.
240
241       int dpvsiz(DEPOT *depot, const char *kbuf, int ksiz);
242              `depot' specifies  a  database  handle.   `kbuf'  specifies  the
243              pointer  to  the  region of a key.  `ksiz' specifies the size of
244              the region of the key.  If it is negative, the size is  assigned
245              with  `strlen(kbuf)'.   If  successful,  the return value is the
246              size of the value of the corresponding record, else, it  is  -1.
247              Because  this  function does not read the entity of a record, it
248              is faster than `dpget'.
249
250       The function `dpiterinit' is used in order to initialize  the  iterator
251       of a database handle.
252
253       int dpiterinit(DEPOT *depot);
254              `depot'  specifies a database handle.  If successful, the return
255              value is true, else, it is false.  The iterator is used in order
256              to access the key of every record stored in a database.
257
258       The  function  `dpiternext' is used in order to get the next key of the
259       iterator.
260
261       char *dpiternext(DEPOT *depot, int *sp);
262              `depot' specifies a database handle.  `sp' specifies the pointer
263              to  a  variable  to  which  the size of the region of the return
264              value is assigned.  If it is `NULL', it is not  used.   If  suc‐
265              cessful,  the  return  value is the pointer to the region of the
266              next key, else, it is `NULL'.  `NULL' is returned when no record
267              is  to  be  get out of the iterator.  Because an additional zero
268              code is appended at the end of the region of the  return  value,
269              the  return value can be treated as a character string.  Because
270              the region of the return value is allocated  with  the  `malloc'
271              call,  it  should  be  released with the `free' call if it is no
272              longer in use.  It is possible to access every record by  itera‐
273              tion  of  calling  this function.  However, it is not assured if
274              updating the database is occurred while the iteration.  Besides,
275              the order of this traversal access method is arbitrary, so it is
276              not assured that the order of storing matches  the  one  of  the
277              traversal access.
278
279       The  function `dpsetalign' is used in order to set alignment of a data‐
280       base handle.
281
282       int dpsetalign(DEPOT *depot, int align);
283              `depot' specifies a  database  handle  connected  as  a  writer.
284              `align'  specifies  the  size  of alignment.  If successful, the
285              return value is true, else, it is false.  If alignment is set to
286              a  database,  the  efficiency of overwriting values is improved.
287              The size of alignment is suggested to be  average  size  of  the
288              values  of  the records to be stored.  If alignment is positive,
289              padding whose size  is  multiple  number  of  the  alignment  is
290              placed.   If  alignment  is negative, as `vsiz' is the size of a
291              value, the size of padding is calculated with  `(vsiz  /  pow(2,
292              abs(align)  - 1))'.  Because alignment setting is not saved in a
293              database, you should specify alignment every opening a database.
294
295       The function `dpsetfbpsiz' is used in order to set the size of the free
296       block pool of a database handle.
297
298       int dpsetfbpsiz(DEPOT *depot, int size);
299              `depot'  specifies  a  database  handle  connected  as a writer.
300              `size' specifies the size of the free block pool of a  database.
301              If successful, the return value is true, else, it is false.  The
302              default size of the free block pool  is  16.   If  the  size  is
303              greater,  the space efficiency of overwriting values is improved
304              with the time efficiency sacrificed.
305
306       The function `dpsync' is used in order to synchronize updating contents
307       with the file and the device.
308
309       int dpsync(DEPOT *depot);
310              `depot'  specifies  a database handle connected as a writer.  If
311              successful, the return value is true, else, it is  false.   This
312              function is useful when another process uses the connected data‐
313              base file.
314
315       The function `dpoptimize' is used in order to optimize a database.
316
317       int dpoptimize(DEPOT *depot, int bnum);
318              `depot' specifies a  database  handle  connected  as  a  writer.
319              `bnum' specifies the number of the elements of the bucket array.
320              If it is not more than 0, the default value  is  specified.   If
321              successful,  the return value is true, else, it is false.  In an
322              alternating succession of deleting and storing with overwrite or
323              concatenate,  dispensable  regions accumulate.  This function is
324              useful to do away with them.
325
326       The function `dpname' is used in order to get the name of a database.
327
328       char *dpname(DEPOT *depot);
329              `depot' specifies a database handle.  If successful, the  return
330              value  is the pointer to the region of the name of the database,
331              else, it is `NULL'.  Because the region of the return  value  is
332              allocated with the `malloc' call, it should be released with the
333              `free' call if it is no longer in use.
334
335       The function `dpfsiz' is used in order to get the size  of  a  database
336       file.
337
338       int dpfsiz(DEPOT *depot);
339              `depot'  specifies a database handle.  If successful, the return
340              value is the size of the database file, else, it is -1.
341
342       The function `dpbnum' is used in order to get the number  of  the  ele‐
343       ments of the bucket array.
344
345       int dpbnum(DEPOT *depot);
346              `depot'  specifies a database handle.  If successful, the return
347              value is the number of the elements of the bucket  array,  else,
348              it is -1.
349
350       The function `dpbusenum' is used in order to get the number of the used
351       elements of the bucket array.
352
353       int dpbusenum(DEPOT *depot);
354              `depot' specifies a database handle.  If successful, the  return
355              value  is  the  number of the used elements of the bucket array,
356              else, it  is  -1.   This  function  is  inefficient  because  it
357              accesses all elements of the bucket array.
358
359       The function `dprnum' is used in order to get the number of the records
360       stored in a database.
361
362       int dprnum(DEPOT *depot);
363              `depot' specifies a database handle.  If successful, the  return
364              value is the number of the records stored in the database, else,
365              it is -1.
366
367       The function `dpwritable' is used in order to check whether a  database
368       handle is a writer or not.
369
370       int dpwritable(DEPOT *depot);
371              `depot'  specifies  a database handle.  The return value is true
372              if the handle is a writer, false if not.
373
374       The function `dpfatalerror' is used in order to check whether  a  data‐
375       base has a fatal error or not.
376
377       int dpfatalerror(DEPOT *depot);
378              `depot'  specifies  a database handle.  The return value is true
379              if the database has a fatal error, false if not.
380
381       The function `dpinode' is used in order to get the inode  number  of  a
382       database file.
383
384       int dpinode(DEPOT *depot);
385              `depot'  specifies  a  database handle.  The return value is the
386              inode number of the database file.
387
388       The function `dpmtime' is used in order to get the last  modified  time
389       of a database.
390
391       time_t dpmtime(DEPOT *depot);
392              `depot'  specifies  a  database handle.  The return value is the
393              last modified time of the database.
394
395       The function `dpfdesc' is used in order to get the file descriptor of a
396       database file.
397
398       int dpfdesc(DEPOT *depot);
399              `depot'  specifies  a  database handle.  The return value is the
400              file  descriptor  of  the  database  file.   Handling  the  file
401              descriptor of a database file directly is not suggested.
402
403       The function `dpremove' is used in order to remove a database file.
404
405       int dpremove(const char *name);
406              `name'  specifies  the  name of a database file.  If successful,
407              the return value is true, else, it is false.
408
409       The function `dprepair' is used in order to repair  a  broken  database
410       file.
411
412       int dprepair(const char *name);
413              `name'  specifies  the  name of a database file.  If successful,
414              the return value is true, else, it is false.  There is no  guar‐
415              antee that all records in a repaired database file correspond to
416              the original or expected state.
417
418       The function `dpexportdb' is used in  order  to  dump  all  records  as
419       endian independent data.
420
421       int dpexportdb(DEPOT *depot, const char *name);
422              `depot'  specifies a database handle.  `name' specifies the name
423              of an output file.  If successful, the  return  value  is  true,
424              else, it is false.
425
426       The  function  `dpimportdb'  is  used in order to load all records from
427       endian independent data.
428
429       int dpimportdb(DEPOT *depot, const char *name);
430              `depot' specifies a database handle connected as a writer.   The
431              database of the handle must be empty.  `name' specifies the name
432              of an input file.  If successful,  the  return  value  is  true,
433              else, it is false.
434
435       The function `dpsnaffle' is used in order to retrieve a record directly
436       from a database file.
437
438       char *dpsnaffle(const char *name, const char *kbuf, int ksiz, int *sp);
439              `name' specifies the name of a database file.  `kbuf'  specifies
440              the  pointer  to the region of a key.  `ksiz' specifies the size
441              of the region of the key.   If  it  is  negative,  the  size  is
442              assigned  with  `strlen(kbuf)'.  `sp' specifies the pointer to a
443              variable to which the size of the region of the return value  is
444              assigned.   If it is `NULL', it is not used.  If successful, the
445              return value is the pointer to the region of the  value  of  the
446              corresponding  record,  else,  it is `NULL'.  `NULL' is returned
447              when no record corresponds to the  specified  key.   Because  an
448              additional zero code is appended at the end of the region of the
449              return value, the return value can be  treated  as  a  character
450              string.   Because  the  region  of the return value is allocated
451              with the `malloc' call, it should be released  with  the  `free'
452              call  if  it is no longer in use.  Although this function can be
453              used even while the database file is locked by another  process,
454              it is not assured that recent updated is reflected.
455
456       The function `dpinnerhash' is a hash function used inside Depot.
457
458       int dpinnerhash(const char *kbuf, int ksiz);
459              `kbuf'  specifies  the  pointer  to the region of a key.  `ksiz'
460              specifies the size of the region of the key.  If it is negative,
461              the  size  is assigned with `strlen(kbuf)'.  The return value is
462              the hash value of 31 bits length computed from  the  key.   This
463              function  is  useful when an application calculates the state of
464              the inside bucket array.
465
466       The function `dpouterhash' is a hash function which is independent from
467       the hash functions used inside Depot.
468
469       int dpouterhash(const char *kbuf, int ksiz);
470              `kbuf'  specifies  the  pointer  to the region of a key.  `ksiz'
471              specifies the size of the region of the key.  If it is negative,
472              the  size  is assigned with `strlen(kbuf)'.  The return value is
473              the hash value of 31 bits length computed from  the  key.   This
474              function  is  useful when an application uses its own hash algo‐
475              rithm outside Depot.
476
477       The function `dpprimenum' is used in order to get a natural prime  num‐
478       ber not less than a number.
479
480       int dpprimenum(int num);
481              `num' specified a natural number.  The return value is a natural
482              prime number not less than the specified number.  This  function
483              is  useful  when  an application determines the size of a bucket
484              array of its own hash algorithm.
485
486       If QDBM was built  with  POSIX  thread  enabled,  the  global  variable
487       `dpecode'  is  treated  as thread specific data, and functions of Depot
488       are reentrant.  In that case, they are thread-safe as long as a  handle
489       is  not  accessed  by  threads at the same time, on the assumption that
490       `errno', `malloc', and so on are thread-safe.
491
492

SEE ALSO

494       qdbm(3), curia(3), relic(3), hovel(3),  cabin(3),  villa(3),  odeum(3),
495       ndbm(3), gdbm(3)
496
497
498
499Man Page                          2004-04-22                          DEPOT(3)
Impressum