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

NAME

6       Hovel - the GDBM-compatible API of QDBM
7
8

SYNOPSIS

10       #include <hovel.h>
11       #include <stdlib.h>
12       #include <sys/types.h>
13       #include <sys/stat.h>
14
15       typedef struct { char *dptr; size_t dsize; } datum;
16
17       extern char *gdbm_version;
18
19       extern gdbm_error gdbm_errno;
20
21       char *gdbm_strerror(gdbm_error gdbmerrno);
22
23       GDBM_FILE  gdbm_open(char  *name,  int  block_size, int read_write, int
24       mode, void (*fatal_func)(void));
25
26       GDBM_FILE gdbm_open2(char *name, int read_write, int  mode,  int  bnum,
27       int dnum, int align);
28
29       void gdbm_close(GDBM_FILE dbf);
30
31       int gdbm_store(GDBM_FILE dbf, datum key, datum content, int flag);
32
33       int gdbm_delete(GDBM_FILE dbf, datum key);
34
35       datum gdbm_fetch(GDBM_FILE dbf, datum key);
36
37       int gdbm_exists(GDBM_FILE dbf, datum key);
38
39       datum gdbm_firstkey(GDBM_FILE dbf);
40
41       datum gdbm_nextkey(GDBM_FILE dbf, datum key);
42
43       void gdbm_sync(GDBM_FILE dbf);
44
45       int gdbm_reorganize(GDBM_FILE dbf);
46
47       int gdbm_fdesc(GDBM_FILE dbf);
48
49       int gdbm_setopt(GDBM_FILE dbf, int option, int *value, int size);
50
51

DESCRIPTION

53       Hovel  is the API which is compatible with GDBM.  So, Hovel wraps func‐
54       tions of Depot and Curia as API of GDBM.  It is easy to port an  appli‐
55       cation  from  GDBM to QDBM.  In most cases, you should only replace the
56       includings of `gdbm.h' with `hovel.h' and replace  the  linking  option
57       `-lgdbm' with `-lqdbm'.  Hovel cannot handle database files made by the
58       original GDBM.
59
60       In order to  use  Hovel,  you  should  include  `hovel.h',  `stdlib.h',
61       `sys/types.h'  and `sys/stat.h' in the source files.  Usually, the fol‐
62       lowing description will be near the beginning of a source file.
63
64              #include <hovel.h>
65              #include <stdlib.h>
66              #include <sys/types.h>
67              #include <sys/stat.h>
68
69       An object of `GDBM_FILE' is used as a database handle.  A database han‐
70       dle   is   opened   with  the  function  `gdbm_open'  and  closed  with
71       `gdbm_close'.  You should not refer directly to any member of a handle.
72       Although  Hovel works as a wrapper of Depot and handles a database file
73       usually, if you use the function `gdbm_open2' to open the handle, it is
74       possible to make behavior of a handle as a wrapper of Curia and treat a
75       database directory.
76
77       Structures of `datum' type is used in order to give and receive data of
78       keys and values with functions of Hovel.
79
80       typedef struct { char *dptr; size_t dsize; } datum;
81              `dptr'  specifies the pointer to the region of a key or a value.
82              `dsize' specifies the size of the region.
83
84       The external variable `gdbm_version' is the string containing the  ver‐
85       sion information.
86
87       extern char *gdbm_version;
88
89       The  external  variable `gdbm_errno' is assigned with the last happened
90       error code.  Refer to `hovel.h' for details of the error codes.
91
92       extern gdbm_error gdbm_errno;
93              The initial value of  this  variable  is  `GDBM_NO_ERROR'.   The
94              other  values  are `GDBM_MALLOC_ERROR', `GDBM_BLOCK_SIZE_ERROR',
95              `GDBM_FILE_OPEN_ERROR',                 `GDBM_FILE_WRITE_ERROR',
96              `GDBM_FILE_SEEK_ERROR',                  `GDBM_FILE_READ_ERROR',
97              `GDBM_BAD_MAGIC_NUMBER',                  `GDBM_EMPTY_DATABASE',
98              `GDBM_CANT_BE_READER',                    `GDBM_CANT_BE_WRITER',
99              `GDBM_READER_CANT_DELETE',             `GDBM_READER_CANT_STORE',
100              `GDBM_READER_CANT_REORGANIZE',            `GDBM_UNKNOWN_UPDATE',
101              `GDBM_ITEM_NOT_FOUND',   `GDBM_REORGANIZE_FAILED',    `GDBM_CAN‐
102              NOT_REPLACE',  `GDBM_ILLEGAL_DATA',  `GDBM_OPT_ALREADY_SET', and
103              `GDBM_OPT_ILLEGAL'.
104
105       The function `gdbm_strerror' is used in order to get a  message  string
106       corresponding to an error code.
107
108       char *gdbm_strerror(gdbm_error gdbmerrno);
109              `gdbmerrno'  specifies  an  error code.  The return value is the
110              message string of the error code.   The  region  of  the  return
111              value is not writable.
112
113       The  function  `gdbm_open'  is  used  in order to get a database handle
114       after the fashion of GDBM.
115
116       GDBM_FILE gdbm_open(char *name, int  block_size,  int  read_write,  int
117       mode, void (*fatal_func)(void));
118              `name'  specifies  the  name  of  a  database.   `block_size' is
119              ignored.    `read_write'   specifies   the   connection    mode:
120              `GDBM_READER'  as  a  reader,  `GDBM_WRITER', `GDBM_WRCREAT' and
121              `GDBM_NEWDB' as a writer.  `GDBM_WRCREAT' makes a database  file
122              or  directory  if  it  does not exist.  `GDBM_NEWDB' makes a new
123              database even if it exists.  You can add the following to writer
124              modes  by bitwise or: `GDBM_SYNC', `GDBM_NOLOCK', `GDBM_LOCKNB',
125              `GDBM_FAST', and `GDBM_SPARSE'.  `GDBM_SYNC' means a database is
126              synchronized after every updating method.  `GDBM_NOLOCK' means a
127              database is opened without file  locking.   `GDBM_LOCKNB'  means
128              file  locking  is  performed  without  blocking.  `GDBM_FAST' is
129              ignored.  `GDBM_SPARSE' is an original mode of  QDBM  and  makes
130              database  a  sparse  file.   `mode' specifies mode of a database
131              file as the one of `open' call does.  `fatal_func'  is  ignored.
132              The  return  value is the database handle or `NULL' if it is not
133              successful.
134
135       The function `gdbm_open2' is used in order to  get  a  database  handle
136       after the fashion of QDBM.
137
138       GDBM_FILE  gdbm_open2(char  *name,  int read_write, int mode, int bnum,
139       int dnum, int align);
140              `name' specifies the name of a database.  `read_write' specifies
141              the  connection  mode: `GDBM_READER' as a reader, `GDBM_WRITER',
142              `GDBM_WRCREAT' and `GDBM_NEWDB'  as  a  writer.   `GDBM_WRCREAT'
143              makes  a  database  file  or  directory  if  it  does not exist.
144              `GDBM_NEWDB' makes a new database even if it  exists.   You  can
145              add  the  following  to writer modes by bitwise or: `GDBM_SYNC',
146              `GDBM_NOLOCK', `GDBM_LOCKNB',  `GDBM_FAST',  and  `GDBM_SPARSE'.
147              `GDBM_SYNC'  means a database is synchronized after every updat‐
148              ing method.  `GDBM_NOLOCK' means a database  is  opened  without
149              file  locking.   `GDBM_LOCKNB'  means  file locking is performed
150              without blocking.  `GDBM_FAST' is ignored.  `GDBM_SPARSE' is  an
151              original  mode  of QDBM and makes database sparse files.  `mode'
152              specifies a mode of a database file or a database  directory  as
153              the  one  of  `open' or `mkdir' call does.  `bnum' specifies the
154              number of elements of each bucket array.  If it is not more than
155              0,  the default value is specified.  `dnum' specifies the number
156              of division of the database.  If it is  not  more  than  0,  the
157              returning  handle  is created as a wrapper of Depot, else, it is
158              as a wrapper of Curia.  `align'  specifies  the  basic  size  of
159              alignment.  The return value is the database handle or `NULL' if
160              it is not successful.  If the database already  exists,  whether
161              it is one of Depot or Curia is measured automatically.
162
163       The function `gdbm_close' is used in order to close a database handle.
164
165       void gdbm_close(GDBM_FILE dbf);
166              `dbf'  specifies  a  database handle.  Because the region of the
167              closed handle is released, it becomes impossible to use the han‐
168              dle.
169
170       The function `gdbm_store' is used in order to store a record.
171
172       int gdbm_store(GDBM_FILE dbf, datum key, datum content, int flag);
173              `dbf'  specifies a database handle connected as a writer.  `key'
174              specifies a structure of a key.  `content' specifies a structure
175              of a value.  `flag' specifies behavior when the key overlaps, by
176              the following values: `GDBM_REPLACE', which means the  specified
177              value  overwrites  the  existing one, `GDBM_INSERT', which means
178              the existing value is kept.  The return value is 0 if it is suc‐
179              cessful,  1 if it gives up because of overlaps of the key, -1 if
180              other error occurs.
181
182       The function `gdbm_delete' is used in order to delete a record.
183
184       int gdbm_delete(GDBM_FILE dbf, datum key);
185              `dbf' specifies a database handle connected as a writer.   `key'
186              specifies  a structure of a key.  The return value is 0 if it is
187              successful, -1 if some errors occur.
188
189       The function `gdbm_fetch' is used in order to retrieve a record.
190
191       datum gdbm_fetch(GDBM_FILE dbf, datum key);
192              `dbf' specifies a database handle.  `key' specifies a  structure
193              of  a key.  The return value is a structure of the result.  If a
194              record corresponds, the member `dptr' of the  structure  is  the
195              pointer to the region of the value.  If no record corresponds or
196              some errors occur, `dptr' is `NULL'.  Because the region pointed
197              to  by  `dptr' is allocated with the `malloc' call, it should be
198              released with the `free' call if it is no longer in use.
199
200       The function `gdbm_exists' is used in order to check whether  a  record
201       exists or not.
202
203       int gdbm_exists(GDBM_FILE dbf, datum key);
204              `dbf'  specifies a database handle.  `key' specifies a structure
205              of a key.  The return value is true if a record corresponds  and
206              no error occurs, or false, else, it is false.
207
208       The function `gdbm_firstkey' is used in order to get the first key of a
209       database.
210
211       datum gdbm_firstkey(GDBM_FILE dbf);
212              `dbf' specifies a database handle.  The return value is a struc‐
213              ture  of the result.  If a record corresponds, the member `dptr'
214              of the structure is the pointer to the region of the first  key.
215              If no record corresponds or some errors occur, `dptr' is `NULL'.
216              Because the region pointed to by `dptr' is  allocated  with  the
217              `malloc'  call, it should be released with the `free' call if it
218              is no longer in use.
219
220       The function `gdbm_nextkey' is used in order to get the next key  of  a
221       database.
222
223       datum gdbm_nextkey(GDBM_FILE dbf, datum key);
224              `dbf' specifies a database handle.  The return value is a struc‐
225              ture of the result.  If a record corresponds, the member  `dptr'
226              of  the  structure is the pointer to the region of the next key.
227              If no record corresponds or some errors occur, `dptr' is `NULL'.
228              Because  the  region  pointed to by `dptr' is allocated with the
229              `malloc' call, it should be released with the `free' call if  it
230              is no longer in use.
231
232       The  function `gdbm_sync' is used in order to synchronize updating con‐
233       tents with the file and the device.
234
235       void gdbm_sync(GDBM_FILE dbf);
236              `dbf' specifies a database handle connected as a writer.
237
238       The function `gdbm_reorganize' is used in order to reorganize  a  data‐
239       base.
240
241       int gdbm_reorganize(GDBM_FILE dbf);
242              `dbf'  specifies  a  database  handle connected as a writer.  If
243              successful, the return value is 0, else -1.
244
245       The function `gdbm_fdesc' is used in order to get the  file  descriptor
246       of a database file.
247
248       int gdbm_fdesc(GDBM_FILE dbf);
249              `dbf'  specifies  a  database handle connected as a writer.  The
250              return value is the file descriptor of the  database  file.   If
251              the database is a directory the return value is -1.
252
253       The function `gdbm_setopt' has no effect.
254
255       int gdbm_setopt(GDBM_FILE dbf, int option, int *value, int size);
256              `dbf' specifies a database handle.  `option' is ignored.  `size'
257              is ignored.  The return value is 0.  The function  is  only  for
258              compatibility.
259
260       If  QDBM  was  built  with  POSIX  thread  enabled, the global variable
261       `gdbm_errno' is treated as thread specific data, and functions of Hovel
262       are  reentrant.  In that case, they are thread-safe as long as a handle
263       is not accessed by threads at the same time,  on  the  assumption  that
264       `errno', `malloc', and so on are thread-safe.
265
266

SEE ALSO

268       qdbm(3),  depot(3),  curia(3),  relic(3), cabin(3), villa(3), odeum(3),
269       ndbm(3), gdbm(3)
270
271
272
273Man Page                          2004-04-22                          HOVEL(3)
Impressum