1HOVEL(3) Quick Database Manager HOVEL(3)
2
6 Hovel - the GDBM-compatible API of QDBM
7
10 #include <hovel.h>
11 #include <stdlib.h>
12 #include <sys/types.h>
13 #include <sys/stat.h>
14 typedef struct { char *dptr; size_t dsize; } datum;
16 extern char *gdbm_version;
18 extern gdbm_error gdbm_errno;
20 char *gdbm_strerror(gdbm_error gdbmerrno);
22 GDBM_FILE gdbm_open(char *name, int block_size, int read_write, int
24 mode, void (*fatal_func)(void));
25 GDBM_FILE gdbm_open2(char *name, int read_write, int mode, int bnum,
27 int dnum, int align);
28 void gdbm_close(GDBM_FILE dbf);
30 int gdbm_store(GDBM_FILE dbf, datum key, datum content, int flag);
32 int gdbm_delete(GDBM_FILE dbf, datum key);
34 datum gdbm_fetch(GDBM_FILE dbf, datum key);
36 int gdbm_exists(GDBM_FILE dbf, datum key);
38 datum gdbm_firstkey(GDBM_FILE dbf);
40 datum gdbm_nextkey(GDBM_FILE dbf, datum key);
42 void gdbm_sync(GDBM_FILE dbf);
44 int gdbm_reorganize(GDBM_FILE dbf);
46 int gdbm_fdesc(GDBM_FILE dbf);
48 int gdbm_setopt(GDBM_FILE dbf, int option, int *value, int size);
50
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 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 #include <hovel.h>
65 #include <stdlib.h>
66 #include <sys/types.h>
67 #include <sys/stat.h>
68 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 Structures of `datum' type is used in order to give and receive data of
78 keys and values with functions of Hovel.
79 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 The external variable `gdbm_version' is the string containing the ver‐
85 sion information.
86 extern char *gdbm_version;
88 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 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 The function `gdbm_strerror' is used in order to get a message string
106 corresponding to an error code.
107 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 The function `gdbm_open' is used in order to get a database handle
114 after the fashion of GDBM.
115 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 The function `gdbm_open2' is used in order to get a database handle
136 after the fashion of QDBM.
137 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 The function `gdbm_close' is used in order to close a database handle.
164 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 The function `gdbm_store' is used in order to store a record.
171 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 The function `gdbm_delete' is used in order to delete a record.
183 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 The function `gdbm_fetch' is used in order to retrieve a record.
190 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 The function `gdbm_exists' is used in order to check whether a record
201 exists or not.
202 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 The function `gdbm_firstkey' is used in order to get the first key of a
209 database.
210 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 The function `gdbm_nextkey' is used in order to get the next key of a
221 database.
222 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 The function `gdbm_sync' is used in order to synchronize updating con‐
233 tents with the file and the device.
234 void gdbm_sync(GDBM_FILE dbf);
236 `dbf' specifies a database handle connected as a writer.
237 The function `gdbm_reorganize' is used in order to reorganize a data‐
239 base.
240 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 The function `gdbm_fdesc' is used in order to get the file descriptor
246 of a database file.
247 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 The function `gdbm_setopt' has no effect.
254 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 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
268 qdbm(3), depot(3), curia(3), relic(3), cabin(3), villa(3), odeum(3),
269 ndbm(3), gdbm(3)
270Man Page 2004-04-22 HOVEL(3)