1 /*************************************************************************************************
2 * The abstract database API of Tokyo Cabinet
3 * Copyright (C) 2006-2008 Mikio Hirabayashi
4 * This file is part of Tokyo Cabinet.
5 * Tokyo Cabinet is free software; you can redistribute it and/or modify it under the terms of
6 * the GNU Lesser General Public License as published by the Free Software Foundation; either
7 * version 2.1 of the License or any later version. Tokyo Cabinet is distributed in the hope
8 * that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
10 * License for more details.
11 * You should have received a copy of the GNU Lesser General Public License along with Tokyo
12 * Cabinet; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
13 * Boston, MA 02111-1307 USA.
14 *************************************************************************************************/
17 #ifndef _TCADB_H /* duplication check */
20 #if defined(__cplusplus)
21 #define __TCADB_CLINKAGEBEGIN extern "C" {
22 #define __TCADB_CLINKAGEEND }
24 #define __TCADB_CLINKAGEBEGIN
25 #define __TCADB_CLINKAGEEND
40 /*************************************************************************************************
42 *************************************************************************************************/
45 typedef struct { /* type of structure for an abstract database */
46 char *name; /* name of the database */
47 TCMDB *mdb; /* on-memory database object */
48 TCHDB *hdb; /* hash database object */
49 TCBDB *bdb; /* B+ tree database object */
50 int64_t capnum; /* capacity number of records */
51 int64_t capsiz; /* capacity size of using memory */
52 uint32_t capcnt; /* count for capacity check */
53 BDBCUR *cur; /* cursor of B+ tree */
57 /* Create an abstract database object.
58 The return value is the new abstract database object. */
59 TCADB *tcadbnew(void);
62 /* Delete an abstract database object.
63 `adb' specifies the abstract database object. */
64 void tcadbdel(TCADB *adb);
67 /* Open an abstract database.
68 `adb' specifies the abstract database object.
69 `name' specifies the name of the database. If it is "*", the database will be an on-memory
70 database. If its suffix is ".tch", the database will be a hash database. If its suffix is
71 ".tcb", the database will be a B+ tree database. Otherwise, this function fails. Tuning
72 parameters can trail the name, separated by "#". Each parameter is composed of the name and
73 the number, separated by "=". On-memory database supports "bnum", "capnum", and "capsiz".
74 Hash database supports "mode", "bnum", "apow", "fpow", "opts", and "rcnum". B+ tree database
75 supports "mode", "lmemb", "nmemb", "bnum", "apow", "fpow", "opts", "lcnum", and "ncnum".
76 "capnum" specifies the capacity number of records. "capsiz" specifies the capacity size of
77 using memory. Records spilled the capacity are removed by the storing order. "mode" can
78 contain "w" of writer, "r" of reader, "c" of creating, "t" of truncating, "e" of no locking,
79 and "f" of non-blocking lock. The default mode is relevant to "wc". "opts" can contains "l"
80 of large option, "d" of Deflate option, and "b" of TCBS option. For example,
81 "casket.tch#bnum=1000000#opts=ld" means that the name of the database file is "casket.tch",
82 and the bucket number is 1000000, and the options are large and Deflate.
83 If successful, the return value is true, else, it is false. */
84 bool tcadbopen(TCADB *adb, const char *name);
87 /* Close an abstract database object.
88 `adb' specifies the abstract database object.
89 If successful, the return value is true, else, it is false.
90 Update of a database is assured to be written when the database is closed. If a writer opens
91 a database but does not close it appropriately, the database will be broken. */
92 bool tcadbclose(TCADB *adb);
95 /* Store a record into an abstract database object.
96 `adb' specifies the abstract database object.
97 `kbuf' specifies the pointer to the region of the key.
98 `ksiz' specifies the size of the region of the key.
99 `vbuf' specifies the pointer to the region of the value.
100 `vsiz' specifies the size of the region of the value.
101 If successful, the return value is true, else, it is false.
102 If a record with the same key exists in the database, it is overwritten. */
103 bool tcadbput(TCADB *adb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
106 /* Store a string record into an abstract object.
107 `adb' specifies the abstract database object.
108 `kstr' specifies the string of the key.
109 `vstr' specifies the string of the value.
110 If successful, the return value is true, else, it is false.
111 If a record with the same key exists in the database, it is overwritten. */
112 bool tcadbput2(TCADB *adb, const char *kstr, const char *vstr);
115 /* Store a new record into an abstract database object.
116 `adb' specifies the abstract database object.
117 `kbuf' specifies the pointer to the region of the key.
118 `ksiz' specifies the size of the region of the key.
119 `vbuf' specifies the pointer to the region of the value.
120 `vsiz' specifies the size of the region of the value.
121 If successful, the return value is true, else, it is false.
122 If a record with the same key exists in the database, this function has no effect. */
123 bool tcadbputkeep(TCADB *adb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
126 /* Store a new string record into an abstract database object.
127 `adb' specifies the abstract database object.
128 `kstr' specifies the string of the key.
129 `vstr' specifies the string of the value.
130 If successful, the return value is true, else, it is false.
131 If a record with the same key exists in the database, this function has no effect. */
132 bool tcadbputkeep2(TCADB *adb, const char *kstr, const char *vstr);
135 /* Concatenate a value at the end of the existing record in an abstract database object.
136 `adb' specifies the abstract database object.
137 `kbuf' specifies the pointer to the region of the key.
138 `ksiz' specifies the size of the region of the key.
139 `vbuf' specifies the pointer to the region of the value.
140 `vsiz' specifies the size of the region of the value.
141 If successful, the return value is true, else, it is false.
142 If there is no corresponding record, a new record is created. */
143 bool tcadbputcat(TCADB *adb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
146 /* Concatenate a string value at the end of the existing record in an abstract database object.
147 `adb' specifies the abstract database object.
148 `kstr' specifies the string of the key.
149 `vstr' specifies the string of the value.
150 If successful, the return value is true, else, it is false.
151 If there is no corresponding record, a new record is created. */
152 bool tcadbputcat2(TCADB *adb, const char *kstr, const char *vstr);
155 /* Remove a record of an abstract database object.
156 `adb' specifies the abstract database object.
157 `kbuf' specifies the pointer to the region of the key.
158 `ksiz' specifies the size of the region of the key.
159 If successful, the return value is true, else, it is false. */
160 bool tcadbout(TCADB *adb, const void *kbuf, int ksiz);
163 /* Remove a string record of an abstract database object.
164 `adb' specifies the abstract database object.
165 `kstr' specifies the string of the key.
166 If successful, the return value is true, else, it is false. */
167 bool tcadbout2(TCADB *adb, const char *kstr);
170 /* Retrieve a record in an abstract database object.
171 `adb' specifies the abstract database object.
172 `kbuf' specifies the pointer to the region of the key.
173 `ksiz' specifies the size of the region of the key.
174 `sp' specifies the pointer to the variable into which the size of the region of the return
176 If successful, the return value is the pointer to the region of the value of the corresponding
177 record. `NULL' is returned if no record corresponds.
178 Because an additional zero code is appended at the end of the region of the return value,
179 the return value can be treated as a character string. Because the region of the return
180 value is allocated with the `malloc' call, it should be released with the `free' call when
181 it is no longer in use. */
182 void *tcadbget(TCADB *adb, const void *kbuf, int ksiz, int *sp);
185 /* Retrieve a string record in an abstract database object.
186 `adb' specifies the abstract database object.
187 `kstr' specifies the string of the key.
188 If successful, the return value is the string of the value of the corresponding record.
189 `NULL' is returned if no record corresponds.
190 Because the region of the return value is allocated with the `malloc' call, it should be
191 released with the `free' call when it is no longer in use. */
192 char *tcadbget2(TCADB *adb, const char *kstr);
195 /* Get the size of the value of a record in an abstract database object.
196 `adb' specifies the abstract database object.
197 `kbuf' specifies the pointer to the region of the key.
198 `ksiz' specifies the size of the region of the key.
199 If successful, the return value is the size of the value of the corresponding record, else,
201 int tcadbvsiz(TCADB *adb, const void *kbuf, int ksiz);
204 /* Get the size of the value of a string record in an abstract database object.
205 `adb' specifies the abstract database object.
206 `kstr' specifies the string of the key.
207 If successful, the return value is the size of the value of the corresponding record, else,
209 int tcadbvsiz2(TCADB *adb, const char *kstr);
212 /* Initialize the iterator of an abstract database object.
213 `adb' specifies the abstract database object.
214 If successful, the return value is true, else, it is false.
215 The iterator is used in order to access the key of every record stored in a database. */
216 bool tcadbiterinit(TCADB *adb);
219 /* Get the next key of the iterator of an abstract database object.
220 `adb' specifies the abstract database object.
221 `sp' specifies the pointer to the variable into which the size of the region of the return
223 If successful, the return value is the pointer to the region of the next key, else, it is
224 `NULL'. `NULL' is returned when no record is to be get out of the iterator.
225 Because an additional zero code is appended at the end of the region of the return value, the
226 return value can be treated as a character string. Because the region of the return value is
227 allocated with the `malloc' call, it should be released with the `free' call when it is no
228 longer in use. It is possible to access every record by iteration of calling this function.
229 It is allowed to update or remove records whose keys are fetched while the iteration.
230 However, it is not assured if updating the database is occurred while the iteration. Besides,
231 the order of this traversal access method is arbitrary, so it is not assured that the order of
232 storing matches the one of the traversal access. */
233 void *tcadbiternext(TCADB *adb, int *sp);
236 /* Get the next key string of the iterator of an abstract database object.
237 `adb' specifies the abstract database object.
238 If successful, the return value is the string of the next key, else, it is `NULL'. `NULL' is
239 returned when no record is to be get out of the iterator.
240 Because the region of the return value is allocated with the `malloc' call, it should be
241 released with the `free' call when it is no longer in use. It is possible to access every
242 record by iteration of calling this function. However, it is not assured if updating the
243 database is occurred while the iteration. Besides, the order of this traversal access method
244 is arbitrary, so it is not assured that the order of storing matches the one of the traversal
246 char *tcadbiternext2(TCADB *adb);
249 /* Get forward matching keys in an abstract database object.
250 `adb' specifies the abstract database object.
251 `pbuf' specifies the pointer to the region of the prefix.
252 `psiz' specifies the size of the region of the prefix.
253 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is
255 The return value is a list object of the corresponding keys. This function does never fail
256 and return an empty list even if no key corresponds.
257 Because the object of the return value is created with the function `tclistnew', it should be
258 deleted with the function `tclistdel' when it is no longer in use. Note that this function
259 may be very slow because every key in the database is scanned. */
260 TCLIST *tcadbfwmkeys(TCADB *adb, const void *pbuf, int psiz, int max);
263 /* Get forward matching string keys in an abstract database object.
264 `adb' specifies the abstract database object.
265 `pstr' specifies the string of the prefix.
266 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is
268 The return value is a list object of the corresponding keys. This function does never fail
269 and return an empty list even if no key corresponds.
270 Because the object of the return value is created with the function `tclistnew', it should be
271 deleted with the function `tclistdel' when it is no longer in use. Note that this function
272 may be very slow because every key in the database is scanned. */
273 TCLIST *tcadbfwmkeys2(TCADB *adb, const char *pstr, int max);
276 /* Synchronize updated contents of an abstract database object with the file and the device.
277 `adb' specifies the abstract database object.
278 If successful, the return value is true, else, it is false.
279 This function fails and has no effect for on-memory database. */
280 bool tcadbsync(TCADB *adb);
283 /* Remove all records of an abstract database object.
284 `adb' specifies the abstract database object.
285 If successful, the return value is true, else, it is false. */
286 bool tcadbvanish(TCADB *adb);
289 /* Copy the database file of an abstract database object.
290 `adb' specifies the abstract database object.
291 `path' specifies the path of the destination file. If it begins with `@', the trailing
292 substring is executed as a command line.
293 If successful, the return value is true, else, it is false. False is returned if the executed
294 command returns non-zero code.
295 The database file is assured to be kept synchronized and not modified while the copying or
296 executing operation is in progress. So, this function is useful to create a backup file of
297 the database file. This function fails and has no effect for on-memory database. */
298 bool tcadbcopy(TCADB *adb, const char *path);
301 /* Get the number of records of an abstract database object.
302 `adb' specifies the abstract database object.
303 The return value is the number of records or 0 if the object does not connect to any database
305 uint64_t tcadbrnum(TCADB *adb);
308 /* Get the size of the database of an abstract database object.
309 `adb' specifies the abstract database object.
310 The return value is the size of the database or 0 if the object does not connect to any
311 database instance. */
312 uint64_t tcadbsize(TCADB *adb);
317 #endif /* duplication check */