1 /************************************************************************************************* 2 * The B+ tree database API of Tokyo Cabinet 3 * Copyright (C) 2006-2012 FAL Labs 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 *************************************************************************************************/ 15 16 17 #ifndef _TCBDB_H /* duplication check */ 18 #define _TCBDB_H 19 20 #if defined(__cplusplus) 21 #define __TCBDB_CLINKAGEBEGIN extern "C" { 22 #define __TCBDB_CLINKAGEEND } 23 #else 24 #define __TCBDB_CLINKAGEBEGIN 25 #define __TCBDB_CLINKAGEEND 26 #endif 27 __TCBDB_CLINKAGEBEGIN 28 29 30 #include <tcutil.h> 31 #include <tchdb.h> 32 33 34 35 /************************************************************************************************* 36 * API 37 *************************************************************************************************/ 38 39 40 typedef struct { /* type of structure for a B+ tree database */ 41 void *mmtx; /* mutex for method */ 42 void *cmtx; /* mutex for cache */ 43 TCHDB *hdb; /* internal database object */ 44 char *opaque; /* opaque buffer */ 45 bool open; /* whether the internal database is opened */ 46 bool wmode; /* whether to be writable */ 47 uint32_t lmemb; /* number of members in each leaf */ 48 uint32_t nmemb; /* number of members in each node */ 49 uint8_t opts; /* options */ 50 uint64_t root; /* ID number of the root page */ 51 uint64_t first; /* ID number of the first leaf */ 52 uint64_t last; /* ID number of the last leaf */ 53 uint64_t lnum; /* number of leaves */ 54 uint64_t nnum; /* number of nodes */ 55 uint64_t rnum; /* number of records */ 56 TCMAP *leafc; /* cache for leaves */ 57 TCMAP *nodec; /* cache for nodes */ 58 TCCMP cmp; /* pointer to the comparison function */ 59 void *cmpop; /* opaque object for the comparison function */ 60 uint32_t lcnum; /* maximum number of cached leaves */ 61 uint32_t ncnum; /* maximum number of cached nodes */ 62 uint32_t lsmax; /* maximum size of each leaf */ 63 uint32_t lschk; /* counter for leaf size checking */ 64 uint64_t capnum; /* capacity number of records */ 65 uint64_t *hist; /* history array of visited nodes */ 66 int hnum; /* number of element of the history array */ 67 volatile uint64_t hleaf; /* ID number of the leaf referred by the history */ 68 volatile uint64_t lleaf; /* ID number of the last visited leaf */ 69 bool tran; /* whether in the transaction */ 70 char *rbopaque; /* opaque for rollback */ 71 volatile uint64_t clock; /* logical clock */ 72 volatile int64_t cnt_saveleaf; /* tesing counter for leaf save times */ 73 volatile int64_t cnt_loadleaf; /* tesing counter for leaf load times */ 74 volatile int64_t cnt_killleaf; /* tesing counter for leaf kill times */ 75 volatile int64_t cnt_adjleafc; /* tesing counter for node cache adjust times */ 76 volatile int64_t cnt_savenode; /* tesing counter for node save times */ 77 volatile int64_t cnt_loadnode; /* tesing counter for node load times */ 78 volatile int64_t cnt_adjnodec; /* tesing counter for node cache adjust times */ 79 } TCBDB; 80 81 enum { /* enumeration for additional flags */ 82 BDBFOPEN = HDBFOPEN, /* whether opened */ 83 BDBFFATAL = HDBFFATAL /* whether with fatal error */ 84 }; 85 86 enum { /* enumeration for tuning options */ 87 BDBTLARGE = 1 << 0, /* use 64-bit bucket array */ 88 BDBTDEFLATE = 1 << 1, /* compress each page with Deflate */ 89 BDBTBZIP = 1 << 2, /* compress each record with BZIP2 */ 90 BDBTTCBS = 1 << 3, /* compress each page with TCBS */ 91 BDBTEXCODEC = 1 << 4 /* compress each record with outer functions */ 92 }; 93 94 enum { /* enumeration for open modes */ 95 BDBOREADER = 1 << 0, /* open as a reader */ 96 BDBOWRITER = 1 << 1, /* open as a writer */ 97 BDBOCREAT = 1 << 2, /* writer creating */ 98 BDBOTRUNC = 1 << 3, /* writer truncating */ 99 BDBONOLCK = 1 << 4, /* open without locking */ 100 BDBOLCKNB = 1 << 5, /* lock without blocking */ 101 BDBOTSYNC = 1 << 6 /* synchronize every transaction */ 102 }; 103 104 typedef struct { /* type of structure for a B+ tree cursor */ 105 TCBDB *bdb; /* database object */ 106 uint64_t clock; /* logical clock */ 107 uint64_t id; /* ID number of the leaf */ 108 int32_t kidx; /* number of the key */ 109 int32_t vidx; /* number of the value */ 110 } BDBCUR; 111 112 enum { /* enumeration for cursor put mode */ 113 BDBCPCURRENT, /* current */ 114 BDBCPBEFORE, /* before */ 115 BDBCPAFTER /* after */ 116 }; 117 118 119 /* Get the message string corresponding to an error code. 120 `ecode' specifies the error code. 121 The return value is the message string of the error code. */ 122 const char *tcbdberrmsg(int ecode); 123 124 125 /* Create a B+ tree database object. 126 The return value is the new B+ tree database object. */ 127 TCBDB *tcbdbnew(void); 128 129 130 /* Delete a B+ tree database object. 131 `bdb' specifies the B+ tree database object. 132 If the database is not closed, it is closed implicitly. Note that the deleted object and its 133 derivatives can not be used anymore. */ 134 void tcbdbdel(TCBDB *bdb); 135 136 137 /* Get the last happened error code of a B+ tree database object. 138 `bdb' specifies the B+ tree database object. 139 The return value is the last happened error code. 140 The following error codes are defined: `TCESUCCESS' for success, `TCETHREAD' for threading 141 error, `TCEINVALID' for invalid operation, `TCENOFILE' for file not found, `TCENOPERM' for no 142 permission, `TCEMETA' for invalid meta data, `TCERHEAD' for invalid record header, `TCEOPEN' 143 for open error, `TCECLOSE' for close error, `TCETRUNC' for trunc error, `TCESYNC' for sync 144 error, `TCESTAT' for stat error, `TCESEEK' for seek error, `TCEREAD' for read error, 145 `TCEWRITE' for write error, `TCEMMAP' for mmap error, `TCELOCK' for lock error, `TCEUNLINK' 146 for unlink error, `TCERENAME' for rename error, `TCEMKDIR' for mkdir error, `TCERMDIR' for 147 rmdir error, `TCEKEEP' for existing record, `TCENOREC' for no record found, and `TCEMISC' for 148 miscellaneous error. */ 149 int tcbdbecode(TCBDB *bdb); 150 151 152 /* Set mutual exclusion control of a B+ tree database object for threading. 153 `bdb' specifies the B+ tree database object which is not opened. 154 If successful, the return value is true, else, it is false. 155 Note that the mutual exclusion control is needed if the object is shared by plural threads and 156 this function should be called before the database is opened. */ 157 bool tcbdbsetmutex(TCBDB *bdb); 158 159 160 /* Set the custom comparison function of a B+ tree database object. 161 `bdb' specifies the B+ tree database object which is not opened. 162 `cmp' specifies the pointer to the custom comparison function. It receives five parameters. 163 The first parameter is the pointer to the region of one key. The second parameter is the size 164 of the region of one key. The third parameter is the pointer to the region of the other key. 165 The fourth parameter is the size of the region of the other key. The fifth parameter is the 166 pointer to the optional opaque object. It returns positive if the former is big, negative if 167 the latter is big, 0 if both are equivalent. 168 `cmpop' specifies an arbitrary pointer to be given as a parameter of the comparison function. 169 If it is not needed, `NULL' can be specified. 170 If successful, the return value is true, else, it is false. 171 The default comparison function compares keys of two records by lexical order. The functions 172 `tctccmplexical' (dafault), `tctccmpdecimal', `tctccmpint32', and `tctccmpint64' are built-in. 173 Note that the comparison function should be set before the database is opened. Moreover, 174 user-defined comparison functions should be set every time the database is being opened. */ 175 bool tcbdbsetcmpfunc(TCBDB *bdb, TCCMP cmp, void *cmpop); 176 177 178 /* Set the tuning parameters of a B+ tree database object. 179 `bdb' specifies the B+ tree database object which is not opened. 180 `lmemb' specifies the number of members in each leaf page. If it is not more than 0, the 181 default value is specified. The default value is 128. 182 `nmemb' specifies the number of members in each non-leaf page. If it is not more than 0, the 183 default value is specified. The default value is 256. 184 `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the 185 default value is specified. The default value is 32749. Suggested size of the bucket array 186 is about from 1 to 4 times of the number of all pages to be stored. 187 `apow' specifies the size of record alignment by power of 2. If it is negative, the default 188 value is specified. The default value is 8 standing for 2^8=256. 189 `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it 190 is negative, the default value is specified. The default value is 10 standing for 2^10=1024. 191 `opts' specifies options by bitwise-or: `BDBTLARGE' specifies that the size of the database 192 can be larger than 2GB by using 64-bit bucket array, `BDBTDEFLATE' specifies that each page 193 is compressed with Deflate encoding, `BDBTBZIP' specifies that each page is compressed with 194 BZIP2 encoding, `BDBTTCBS' specifies that each page is compressed with TCBS encoding. 195 If successful, the return value is true, else, it is false. 196 Note that the tuning parameters should be set before the database is opened. */ 197 bool tcbdbtune(TCBDB *bdb, int32_t lmemb, int32_t nmemb, 198 int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts); 199 200 201 /* Set the caching parameters of a B+ tree database object. 202 `bdb' specifies the B+ tree database object which is not opened. 203 `lcnum' specifies the maximum number of leaf nodes to be cached. If it is not more than 0, 204 the default value is specified. The default value is 1024. 205 `ncnum' specifies the maximum number of non-leaf nodes to be cached. If it is not more than 0, 206 the default value is specified. The default value is 512. 207 If successful, the return value is true, else, it is false. 208 Note that the caching parameters should be set before the database is opened. */ 209 bool tcbdbsetcache(TCBDB *bdb, int32_t lcnum, int32_t ncnum); 210 211 212 /* Set the size of the extra mapped memory of a B+ tree database object. 213 `bdb' specifies the B+ tree database object which is not opened. 214 `xmsiz' specifies the size of the extra mapped memory. If it is not more than 0, the extra 215 mapped memory is disabled. It is disabled by default. 216 If successful, the return value is true, else, it is false. 217 Note that the mapping parameters should be set before the database is opened. */ 218 bool tcbdbsetxmsiz(TCBDB *bdb, int64_t xmsiz); 219 220 221 /* Set the unit step number of auto defragmentation of a B+ tree database object. 222 `bdb' specifies the B+ tree database object which is not opened. 223 `dfunit' specifie the unit step number. If it is not more than 0, the auto defragmentation 224 is disabled. It is disabled by default. 225 If successful, the return value is true, else, it is false. 226 Note that the defragmentation parameter should be set before the database is opened. */ 227 bool tcbdbsetdfunit(TCBDB *bdb, int32_t dfunit); 228 229 230 /* Open a database file and connect a B+ tree database object. 231 `bdb' specifies the B+ tree database object which is not opened. 232 `path' specifies the path of the database file. 233 `omode' specifies the connection mode: `BDBOWRITER' as a writer, `BDBOREADER' as a reader. 234 If the mode is `BDBOWRITER', the following may be added by bitwise-or: `BDBOCREAT', which 235 means it creates a new database if not exist, `BDBOTRUNC', which means it creates a new 236 database regardless if one exists, `BDBOTSYNC', which means every transaction synchronizes 237 updated contents with the device. Both of `BDBOREADER' and `BDBOWRITER' can be added to by 238 bitwise-or: `BDBONOLCK', which means it opens the database file without file locking, or 239 `BDBOLCKNB', which means locking is performed without blocking. 240 If successful, the return value is true, else, it is false. */ 241 bool tcbdbopen(TCBDB *bdb, const char *path, int omode); 242 243 244 /* Close a B+ tree database object. 245 `bdb' specifies the B+ tree database object. 246 If successful, the return value is true, else, it is false. 247 Update of a database is assured to be written when the database is closed. If a writer opens 248 a database but does not close it appropriately, the database will be broken. */ 249 bool tcbdbclose(TCBDB *bdb); 250 251 252 /* Store a record into a B+ tree database object. 253 `bdb' specifies the B+ tree database object connected as a writer. 254 `kbuf' specifies the pointer to the region of the key. 255 `ksiz' specifies the size of the region of the key. 256 `vbuf' specifies the pointer to the region of the value. 257 `vsiz' specifies the size of the region of the value. 258 If successful, the return value is true, else, it is false. 259 If a record with the same key exists in the database, it is overwritten. */ 260 bool tcbdbput(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz); 261 262 263 /* Store a string record into a B+ tree database object. 264 `bdb' specifies the B+ tree database object connected as a writer. 265 `kstr' specifies the string of the key. 266 `vstr' specifies the string of the value. 267 If successful, the return value is true, else, it is false. 268 If a record with the same key exists in the database, it is overwritten. */ 269 bool tcbdbput2(TCBDB *bdb, const char *kstr, const char *vstr); 270 271 272 /* Store a new record into a B+ tree database object. 273 `bdb' specifies the B+ tree database object connected as a writer. 274 `kbuf' specifies the pointer to the region of the key. 275 `ksiz' specifies the size of the region of the key. 276 `vbuf' specifies the pointer to the region of the value. 277 `vsiz' specifies the size of the region of the value. 278 If successful, the return value is true, else, it is false. 279 If a record with the same key exists in the database, this function has no effect. */ 280 bool tcbdbputkeep(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz); 281 282 283 /* Store a new string record into a B+ tree database object. 284 `bdb' specifies the B+ tree database object connected as a writer. 285 `kstr' specifies the string of the key. 286 `vstr' specifies the string of the value. 287 If successful, the return value is true, else, it is false. 288 If a record with the same key exists in the database, this function has no effect. */ 289 bool tcbdbputkeep2(TCBDB *bdb, const char *kstr, const char *vstr); 290 291 292 /* Concatenate a value at the end of the existing record in a B+ tree database object. 293 `bdb' specifies the B+ tree database object connected as a writer. 294 `kbuf' specifies the pointer to the region of the key. 295 `ksiz' specifies the size of the region of the key. 296 `vbuf' specifies the pointer to the region of the value. 297 `vsiz' specifies the size of the region of the value. 298 If successful, the return value is true, else, it is false. 299 If there is no corresponding record, a new record is created. */ 300 bool tcbdbputcat(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz); 301 302 303 /* Concatenate a string value at the end of the existing record in a B+ tree database object. 304 `bdb' specifies the B+ tree database object connected as a writer. 305 `kstr' specifies the string of the key. 306 `vstr' specifies the string of the value. 307 If successful, the return value is true, else, it is false. 308 If there is no corresponding record, a new record is created. */ 309 bool tcbdbputcat2(TCBDB *bdb, const char *kstr, const char *vstr); 310 311 312 /* Store a record into a B+ tree database object with allowing duplication of keys. 313 `bdb' specifies the B+ tree database object connected as a writer. 314 `kbuf' specifies the pointer to the region of the key. 315 `ksiz' specifies the size of the region of the key. 316 `vbuf' specifies the pointer to the region of the value. 317 `vsiz' specifies the size of the region of the value. 318 If successful, the return value is true, else, it is false. 319 If a record with the same key exists in the database, the new record is placed after the 320 existing one. */ 321 bool tcbdbputdup(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz); 322 323 324 /* Store a string record into a B+ tree database object with allowing duplication of keys. 325 `bdb' specifies the B+ tree database object connected as a writer. 326 `kstr' specifies the string of the key. 327 `vstr' specifies the string of the value. 328 If successful, the return value is true, else, it is false. 329 If a record with the same key exists in the database, the new record is placed after the 330 existing one. */ 331 bool tcbdbputdup2(TCBDB *bdb, const char *kstr, const char *vstr); 332 333 334 /* Store records into a B+ tree database object with allowing duplication of keys. 335 `bdb' specifies the B+ tree database object connected as a writer. 336 `kbuf' specifies the pointer to the region of the common key. 337 `ksiz' specifies the size of the region of the common key. 338 `vals' specifies a list object containing values. 339 If successful, the return value is true, else, it is false. 340 If a record with the same key exists in the database, the new records are placed after the 341 existing one. */ 342 bool tcbdbputdup3(TCBDB *bdb, const void *kbuf, int ksiz, const TCLIST *vals); 343 344 345 /* Remove a record of a B+ tree database object. 346 `bdb' specifies the B+ tree database object connected as a writer. 347 `kbuf' specifies the pointer to the region of the key. 348 `ksiz' specifies the size of the region of the key. 349 If successful, the return value is true, else, it is false. 350 If the key of duplicated records is specified, the first one is selected. */ 351 bool tcbdbout(TCBDB *bdb, const void *kbuf, int ksiz); 352 353 354 /* Remove a string record of a B+ tree database object. 355 `bdb' specifies the B+ tree database object connected as a writer. 356 `kstr' specifies the string of the key. 357 If successful, the return value is true, else, it is false. 358 If the key of duplicated records is specified, the first one is selected. */ 359 bool tcbdbout2(TCBDB *bdb, const char *kstr); 360 361 362 /* Remove records of a B+ tree database object. 363 `bdb' specifies the B+ tree database object connected as a writer. 364 `kbuf' specifies the pointer to the region of the key. 365 `ksiz' specifies the size of the region of the key. 366 If successful, the return value is true, else, it is false. 367 If the key of duplicated records is specified, all of them are removed. */ 368 bool tcbdbout3(TCBDB *bdb, const void *kbuf, int ksiz); 369 370 371 /* Retrieve a record in a B+ tree database object. 372 `bdb' specifies the B+ tree database object. 373 `kbuf' specifies the pointer to the region of the key. 374 `ksiz' specifies the size of the region of the key. 375 `sp' specifies the pointer to the variable into which the size of the region of the return 376 value is assigned. 377 If successful, the return value is the pointer to the region of the value of the corresponding 378 record. `NULL' is returned if no record corresponds. 379 If the key of duplicated records is specified, the first one is selected. Because an 380 additional zero code is appended at the end of the region of the return value, the return 381 value can be treated as a character string. Because the region of the return value is 382 allocated with the `malloc' call, it should be released with the `free' call when it is no 383 longer in use. */ 384 void *tcbdbget(TCBDB *bdb, const void *kbuf, int ksiz, int *sp); 385 386 387 /* Retrieve a string record in a B+ tree database object. 388 `bdb' specifies the B+ tree database object. 389 `kstr' specifies the string of the key. 390 If successful, the return value is the string of the value of the corresponding record. 391 `NULL' is returned if no record corresponds. 392 If the key of duplicated records is specified, the first one is selected. Because the region 393 of the return value is allocated with the `malloc' call, it should be released with the `free' 394 call when it is no longer in use. */ 395 char *tcbdbget2(TCBDB *bdb, const char *kstr); 396 397 398 /* Retrieve a record in a B+ tree database object as a volatile buffer. 399 `bdb' specifies the B+ tree database object. 400 `kbuf' specifies the pointer to the region of the key. 401 `ksiz' specifies the size of the region of the key. 402 `sp' specifies the pointer to the variable into which the size of the region of the return 403 value is assigned. 404 If successful, the return value is the pointer to the region of the value of the corresponding 405 record. `NULL' is returned if no record corresponds. 406 If the key of duplicated records is specified, the first one is selected. Because an 407 additional zero code is appended at the end of the region of the return value, the return 408 value can be treated as a character string. Because the region of the return value is 409 volatile and it may be spoiled by another operation of the database, the data should be copied 410 into another involatile buffer immediately. */ 411 const void *tcbdbget3(TCBDB *bdb, const void *kbuf, int ksiz, int *sp); 412 413 414 /* Retrieve records in a B+ tree database object. 415 `bdb' specifies the B+ tree database object. 416 `kbuf' specifies the pointer to the region of the key. 417 `ksiz' specifies the size of the region of the key. 418 If successful, the return value is a list object of the values of the corresponding records. 419 `NULL' is returned if no record corresponds. 420 Because the object of the return value is created with the function `tclistnew', it should 421 be deleted with the function `tclistdel' when it is no longer in use. */ 422 TCLIST *tcbdbget4(TCBDB *bdb, const void *kbuf, int ksiz); 423 424 425 /* Get the number of records corresponding a key in a B+ tree database object. 426 `bdb' specifies the B+ tree database object. 427 `kbuf' specifies the pointer to the region of the key. 428 `ksiz' specifies the size of the region of the key. 429 If successful, the return value is the number of the corresponding records, else, it is 0. */ 430 int tcbdbvnum(TCBDB *bdb, const void *kbuf, int ksiz); 431 432 433 /* Get the number of records corresponding a string key in a B+ tree database object. 434 `bdb' specifies the B+ tree database object. 435 `kstr' specifies the string of the key. 436 If successful, the return value is the number of the corresponding records, else, it is 0. */ 437 int tcbdbvnum2(TCBDB *bdb, const char *kstr); 438 439 440 /* Get the size of the value of a record in a B+ tree database object. 441 `bdb' specifies the B+ tree database object. 442 `kbuf' specifies the pointer to the region of the key. 443 `ksiz' specifies the size of the region of the key. 444 If successful, the return value is the size of the value of the corresponding record, else, 445 it is -1. 446 If the key of duplicated records is specified, the first one is selected. */ 447 int tcbdbvsiz(TCBDB *bdb, const void *kbuf, int ksiz); 448 449 450 /* Get the size of the value of a string record in a B+ tree database object. 451 `bdb' specifies the B+ tree database object. 452 `kstr' specifies the string of the key. 453 If successful, the return value is the size of the value of the corresponding record, else, 454 it is -1. 455 If the key of duplicated records is specified, the first one is selected. */ 456 int tcbdbvsiz2(TCBDB *bdb, const char *kstr); 457 458 459 /* Get keys of ranged records in a B+ tree database object. 460 `bdb' specifies the B+ tree database object. 461 `bkbuf' specifies the pointer to the region of the key of the beginning border. If it is 462 `NULL', the first record is specified. 463 `bksiz' specifies the size of the region of the beginning key. 464 `binc' specifies whether the beginning border is inclusive or not. 465 `ekbuf' specifies the pointer to the region of the key of the ending border. If it is `NULL', 466 the last record is specified. 467 `eksiz' specifies the size of the region of the ending key. 468 `einc' specifies whether the ending border is inclusive or not. 469 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is 470 specified. 471 The return value is a list object of the keys of the corresponding records. This function 472 does never fail. It returns an empty list even if no record corresponds. 473 Because the object of the return value is created with the function `tclistnew', it should 474 be deleted with the function `tclistdel' when it is no longer in use. */ 475 TCLIST *tcbdbrange(TCBDB *bdb, const void *bkbuf, int bksiz, bool binc, 476 const void *ekbuf, int eksiz, bool einc, int max); 477 478 479 /* Get string keys of ranged records in a B+ tree database object. 480 `bdb' specifies the B+ tree database object. 481 `bkstr' specifies the string of the key of the beginning border. If it is `NULL', the first 482 record is specified. 483 `binc' specifies whether the beginning border is inclusive or not. 484 `ekstr' specifies the string of the key of the ending border. If it is `NULL', the last 485 record is specified. 486 `einc' specifies whether the ending border is inclusive or not. 487 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is 488 specified. 489 The return value is a list object of the keys of the corresponding records. This function 490 does never fail. It returns an empty list even if no record corresponds. 491 Because the object of the return value is created with the function `tclistnew', it should 492 be deleted with the function `tclistdel' when it is no longer in use. */ 493 TCLIST *tcbdbrange2(TCBDB *bdb, const char *bkstr, bool binc, 494 const char *ekstr, bool einc, int max); 495 496 497 /* Get forward matching keys in a B+ tree database object. 498 `bdb' specifies the B+ tree database object. 499 `pbuf' specifies the pointer to the region of the prefix. 500 `psiz' specifies the size of the region of the prefix. 501 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is 502 specified. 503 The return value is a list object of the corresponding keys. This function does never fail. 504 It returns an empty list even if no key corresponds. 505 Because the object of the return value is created with the function `tclistnew', it should be 506 deleted with the function `tclistdel' when it is no longer in use. */ 507 TCLIST *tcbdbfwmkeys(TCBDB *bdb, const void *pbuf, int psiz, int max); 508 509 510 /* Get forward matching string keys in a B+ tree database object. 511 `bdb' specifies the B+ tree database object. 512 `pstr' specifies the string of the prefix. 513 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is 514 specified. 515 The return value is a list object of the corresponding keys. This function does never fail. 516 It returns an empty list even if no key corresponds. 517 Because the object of the return value is created with the function `tclistnew', it should be 518 deleted with the function `tclistdel' when it is no longer in use. */ 519 TCLIST *tcbdbfwmkeys2(TCBDB *bdb, const char *pstr, int max); 520 521 522 /* Add an integer to a record in a B+ tree database object. 523 `bdb' specifies the B+ tree database object connected as a writer. 524 `kbuf' specifies the pointer to the region of the key. 525 `ksiz' specifies the size of the region of the key. 526 `num' specifies the additional value. 527 If successful, the return value is the summation value, else, it is `INT_MIN'. 528 If the corresponding record exists, the value is treated as an integer and is added to. If no 529 record corresponds, a new record of the additional value is stored. */ 530 int tcbdbaddint(TCBDB *bdb, const void *kbuf, int ksiz, int num); 531 532 533 /* Add a real number to a record in a B+ tree database object. 534 `bdb' specifies the B+ tree database object connected as a writer. 535 `kbuf' specifies the pointer to the region of the key. 536 `ksiz' specifies the size of the region of the key. 537 `num' specifies the additional value. 538 If successful, the return value is the summation value, else, it is Not-a-Number. 539 If the corresponding record exists, the value is treated as a real number and is added to. If 540 no record corresponds, a new record of the additional value is stored. */ 541 double tcbdbadddouble(TCBDB *bdb, const void *kbuf, int ksiz, double num); 542 543 544 /* Synchronize updated contents of a B+ tree database object with the file and the device. 545 `bdb' specifies the B+ tree database object connected as a writer. 546 If successful, the return value is true, else, it is false. 547 This function is useful when another process connects to the same database file. */ 548 bool tcbdbsync(TCBDB *bdb); 549 550 551 /* Optimize the file of a B+ tree database object. 552 `bdb' specifies the B+ tree database object connected as a writer. 553 `lmemb' specifies the number of members in each leaf page. If it is not more than 0, the 554 current setting is not changed. 555 `nmemb' specifies the number of members in each non-leaf page. If it is not more than 0, the 556 current setting is not changed. 557 `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the 558 default value is specified. The default value is two times of the number of pages. 559 `apow' specifies the size of record alignment by power of 2. If it is negative, the current 560 setting is not changed. 561 `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it 562 is negative, the current setting is not changed. 563 `opts' specifies options by bitwise-or: `BDBTLARGE' specifies that the size of the database 564 can be larger than 2GB by using 64-bit bucket array, `BDBTDEFLATE' specifies that each record 565 is compressed with Deflate encoding, `BDBTBZIP' specifies that each page is compressed with 566 BZIP2 encoding, `BDBTTCBS' specifies that each page is compressed with TCBS encoding. If it 567 is `UINT8_MAX', the current setting is not changed. 568 If successful, the return value is true, else, it is false. 569 This function is useful to reduce the size of the database file with data fragmentation by 570 successive updating. */ 571 bool tcbdboptimize(TCBDB *bdb, int32_t lmemb, int32_t nmemb, 572 int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts); 573 574 575 /* Remove all records of a B+ tree database object. 576 `bdb' specifies the B+ tree database object connected as a writer. 577 If successful, the return value is true, else, it is false. */ 578 bool tcbdbvanish(TCBDB *bdb); 579 580 581 /* Copy the database file of a B+ tree database object. 582 `bdb' specifies the B+ tree database object. 583 `path' specifies the path of the destination file. If it begins with `@', the trailing 584 substring is executed as a command line. 585 If successful, the return value is true, else, it is false. False is returned if the executed 586 command returns non-zero code. 587 The database file is assured to be kept synchronized and not modified while the copying or 588 executing operation is in progress. So, this function is useful to create a backup file of 589 the database file. */ 590 bool tcbdbcopy(TCBDB *bdb, const char *path); 591 592 593 /* Begin the transaction of a B+ tree database object. 594 `bdb' specifies the B+ tree database object connected as a writer. 595 If successful, the return value is true, else, it is false. 596 The database is locked by the thread while the transaction so that only one transaction can be 597 activated with a database object at the same time. Thus, the serializable isolation level is 598 assumed if every database operation is performed in the transaction. Because all pages are 599 cached on memory while the transaction, the amount of referred records is limited by the 600 memory capacity. If the database is closed during transaction, the transaction is aborted 601 implicitly. */ 602 bool tcbdbtranbegin(TCBDB *bdb); 603 604 605 /* Commit the transaction of a B+ tree database object. 606 `bdb' specifies the B+ tree database object connected as a writer. 607 If successful, the return value is true, else, it is false. 608 Update in the transaction is fixed when it is committed successfully. */ 609 bool tcbdbtrancommit(TCBDB *bdb); 610 611 612 /* Abort the transaction of a B+ tree database object. 613 `bdb' specifies the B+ tree database object connected as a writer. 614 If successful, the return value is true, else, it is false. 615 Update in the transaction is discarded when it is aborted. The state of the database is 616 rollbacked to before transaction. */ 617 bool tcbdbtranabort(TCBDB *bdb); 618 619 620 /* Get the file path of a B+ tree database object. 621 `bdb' specifies the B+ tree database object. 622 The return value is the path of the database file or `NULL' if the object does not connect to 623 any database file. */ 624 const char *tcbdbpath(TCBDB *bdb); 625 626 627 /* Get the number of records of a B+ tree database object. 628 `bdb' specifies the B+ tree database object. 629 The return value is the number of records or 0 if the object does not connect to any database 630 file. */ 631 uint64_t tcbdbrnum(TCBDB *bdb); 632 633 634 /* Get the size of the database file of a B+ tree database object. 635 `bdb' specifies the B+ tree database object. 636 The return value is the size of the database file or 0 if the object does not connect to any 637 database file. */ 638 uint64_t tcbdbfsiz(TCBDB *bdb); 639 640 641 /* Create a cursor object. 642 `bdb' specifies the B+ tree database object. 643 The return value is the new cursor object. 644 Note that the cursor is available only after initialization with the `tcbdbcurfirst' or the 645 `tcbdbcurjump' functions and so on. Moreover, the position of the cursor will be indefinite 646 when the database is updated after the initialization of the cursor. */ 647 BDBCUR *tcbdbcurnew(TCBDB *bdb); 648 649 650 /* Delete a cursor object. 651 `cur' specifies the cursor object. */ 652 void tcbdbcurdel(BDBCUR *cur); 653 654 655 /* Move a cursor object to the first record. 656 `cur' specifies the cursor object. 657 If successful, the return value is true, else, it is false. False is returned if there is 658 no record in the database. */ 659 bool tcbdbcurfirst(BDBCUR *cur); 660 661 662 /* Move a cursor object to the last record. 663 `cur' specifies the cursor object. 664 If successful, the return value is true, else, it is false. False is returned if there is 665 no record in the database. */ 666 bool tcbdbcurlast(BDBCUR *cur); 667 668 669 /* Move a cursor object to the front of records corresponding a key. 670 `cur' specifies the cursor object. 671 `kbuf' specifies the pointer to the region of the key. 672 `ksiz' specifies the size of the region of the key. 673 If successful, the return value is true, else, it is false. False is returned if there is 674 no record corresponding the condition. 675 The cursor is set to the first record corresponding the key or the next substitute if 676 completely matching record does not exist. */ 677 bool tcbdbcurjump(BDBCUR *cur, const void *kbuf, int ksiz); 678 679 680 /* Move a cursor object to the front of records corresponding a key string. 681 `cur' specifies the cursor object. 682 `kstr' specifies the string of the key. 683 If successful, the return value is true, else, it is false. False is returned if there is 684 no record corresponding the condition. 685 The cursor is set to the first record corresponding the key or the next substitute if 686 completely matching record does not exist. */ 687 bool tcbdbcurjump2(BDBCUR *cur, const char *kstr); 688 689 690 /* Move a cursor object to the previous record. 691 `cur' specifies the cursor object. 692 If successful, the return value is true, else, it is false. False is returned if there is 693 no previous record. */ 694 bool tcbdbcurprev(BDBCUR *cur); 695 696 697 /* Move a cursor object to the next record. 698 `cur' specifies the cursor object. 699 If successful, the return value is true, else, it is false. False is returned if there is 700 no next record. */ 701 bool tcbdbcurnext(BDBCUR *cur); 702 703 704 /* Insert a record around a cursor object. 705 `cur' specifies the cursor object of writer connection. 706 `vbuf' specifies the pointer to the region of the value. 707 `vsiz' specifies the size of the region of the value. 708 `cpmode' specifies detail adjustment: `BDBCPCURRENT', which means that the value of the 709 current record is overwritten, `BDBCPBEFORE', which means that the new record is inserted 710 before the current record, `BDBCPAFTER', which means that the new record is inserted after the 711 current record. 712 If successful, the return value is true, else, it is false. False is returned when the cursor 713 is at invalid position. 714 After insertion, the cursor is moved to the inserted record. */ 715 bool tcbdbcurput(BDBCUR *cur, const void *vbuf, int vsiz, int cpmode); 716 717 718 /* Insert a string record around a cursor object. 719 `cur' specifies the cursor object of writer connection. 720 `vstr' specifies the string of the value. 721 `cpmode' specifies detail adjustment: `BDBCPCURRENT', which means that the value of the 722 current record is overwritten, `BDBCPBEFORE', which means that the new record is inserted 723 before the current record, `BDBCPAFTER', which means that the new record is inserted after the 724 current record. 725 If successful, the return value is true, else, it is false. False is returned when the cursor 726 is at invalid position. 727 After insertion, the cursor is moved to the inserted record. */ 728 bool tcbdbcurput2(BDBCUR *cur, const char *vstr, int cpmode); 729 730 731 /* Remove the record where a cursor object is. 732 `cur' specifies the cursor object of writer connection. 733 If successful, the return value is true, else, it is false. False is returned when the cursor 734 is at invalid position. 735 After deletion, the cursor is moved to the next record if possible. */ 736 bool tcbdbcurout(BDBCUR *cur); 737 738 739 /* Get the key of the record where the cursor object is. 740 `cur' specifies the cursor object. 741 `sp' specifies the pointer to the variable into which the size of the region of the return 742 value is assigned. 743 If successful, the return value is the pointer to the region of the key, else, it is `NULL'. 744 `NULL' is returned when the cursor is at invalid position. 745 Because an additional zero code is appended at the end of the region of the return value, 746 the return value can be treated as a character string. Because the region of the return 747 value is allocated with the `malloc' call, it should be released with the `free' call when 748 it is no longer in use. */ 749 void *tcbdbcurkey(BDBCUR *cur, int *sp); 750 751 752 /* Get the key string of the record where the cursor object is. 753 `cur' specifies the cursor object. 754 If successful, the return value is the string of the key, else, it is `NULL'. `NULL' is 755 returned when the cursor is at invalid position. 756 Because the region of the return value is allocated with the `malloc' call, it should be 757 released with the `free' call when it is no longer in use. */ 758 char *tcbdbcurkey2(BDBCUR *cur); 759 760 761 /* Get the key of the record where the cursor object is, as a volatile buffer. 762 `cur' specifies the cursor object. 763 `sp' specifies the pointer to the variable into which the size of the region of the return 764 value is assigned. 765 If successful, the return value is the pointer to the region of the key, else, it is `NULL'. 766 `NULL' is returned when the cursor is at invalid position. 767 Because an additional zero code is appended at the end of the region of the return value, 768 the return value can be treated as a character string. Because the region of the return value 769 is volatile and it may be spoiled by another operation of the database, the data should be 770 copied into another involatile buffer immediately. */ 771 const void *tcbdbcurkey3(BDBCUR *cur, int *sp); 772 773 774 /* Get the value of the record where the cursor object is. 775 `cur' specifies the cursor object. 776 `sp' specifies the pointer to the variable into which the size of the region of the return 777 value is assigned. 778 If successful, the return value is the pointer to the region of the value, else, it is `NULL'. 779 `NULL' is returned when the cursor is at invalid position. 780 Because an additional zero code is appended at the end of the region of the return value, 781 the return value can be treated as a character string. Because the region of the return 782 value is allocated with the `malloc' call, it should be released with the `free' call when 783 it is no longer in use. */ 784 void *tcbdbcurval(BDBCUR *cur, int *sp); 785 786 787 /* Get the value string of the record where the cursor object is. 788 `cur' specifies the cursor object. 789 If successful, the return value is the string of the value, else, it is `NULL'. `NULL' is 790 returned when the cursor is at invalid position. 791 Because the region of the return value is allocated with the `malloc' call, it should be 792 released with the `free' call when it is no longer in use. */ 793 char *tcbdbcurval2(BDBCUR *cur); 794 795 796 /* Get the value of the record where the cursor object is, as a volatile buffer. 797 `cur' specifies the cursor object. 798 `sp' specifies the pointer to the variable into which the size of the region of the return 799 value is assigned. 800 If successful, the return value is the pointer to the region of the value, else, it is `NULL'. 801 `NULL' is returned when the cursor is at invalid position. 802 Because an additional zero code is appended at the end of the region of the return value, 803 the return value can be treated as a character string. Because the region of the return value 804 is volatile and it may be spoiled by another operation of the database, the data should be 805 copied into another involatile buffer immediately. */ 806 const void *tcbdbcurval3(BDBCUR *cur, int *sp); 807 808 809 /* Get the key and the value of the record where the cursor object is. 810 `cur' specifies the cursor object. 811 `kxstr' specifies the object into which the key is wrote down. 812 `vxstr' specifies the object into which the value is wrote down. 813 If successful, the return value is true, else, it is false. False is returned when the cursor 814 is at invalid position. */ 815 bool tcbdbcurrec(BDBCUR *cur, TCXSTR *kxstr, TCXSTR *vxstr); 816 817 818 819 /************************************************************************************************* 820 * features for experts 821 *************************************************************************************************/ 822 823 824 /* Set the error code of a B+ tree database object. 825 `bdb' specifies the B+ tree database object. 826 `ecode' specifies the error code. 827 `file' specifies the file name of the code. 828 `line' specifies the line number of the code. 829 `func' specifies the function name of the code. */ 830 void tcbdbsetecode(TCBDB *bdb, int ecode, const char *filename, int line, const char *func); 831 832 833 /* Set the file descriptor for debugging output. 834 `bdb' specifies the B+ tree database object. 835 `fd' specifies the file descriptor for debugging output. */ 836 void tcbdbsetdbgfd(TCBDB *bdb, int fd); 837 838 839 /* Get the file descriptor for debugging output. 840 `bdb' specifies the B+ tree database object. 841 The return value is the file descriptor for debugging output. */ 842 int tcbdbdbgfd(TCBDB *bdb); 843 844 845 /* Check whether mutual exclusion control is set to a B+ tree database object. 846 `bdb' specifies the B+ tree database object. 847 If mutual exclusion control is set, it is true, else it is false. */ 848 bool tcbdbhasmutex(TCBDB *bdb); 849 850 851 /* Synchronize updating contents on memory of a B+ tree database object. 852 `bdb' specifies the B+ tree database object connected as a writer. 853 `phys' specifies whether to synchronize physically. 854 If successful, the return value is true, else, it is false. */ 855 bool tcbdbmemsync(TCBDB *bdb, bool phys); 856 857 858 /* Get the comparison function of a B+ tree database object. 859 `bdb' specifies the B+ tree database object. 860 The return value is the pointer to the comparison function. */ 861 TCCMP tcbdbcmpfunc(TCBDB *bdb); 862 863 864 /* Get the opaque object for the comparison function of a B+ tree database object. 865 `bdb' specifies the B+ tree database object. 866 The return value is the opaque object for the comparison function. */ 867 void *tcbdbcmpop(TCBDB *bdb); 868 869 870 /* Get the maximum number of cached leaf nodes of a B+ tree database object. 871 `bdb' specifies the B+ tree database object. 872 The return value is the maximum number of cached leaf nodes. */ 873 uint32_t tcbdblmemb(TCBDB *bdb); 874 875 876 /* Get the maximum number of cached non-leaf nodes of a B+ tree database object. 877 `bdb' specifies the B+ tree database object. 878 The return value is the maximum number of cached non-leaf nodes. */ 879 uint32_t tcbdbnmemb(TCBDB *bdb); 880 881 882 /* Get the number of the leaf nodes of B+ tree database object. 883 `bdb' specifies the B+ tree database object. 884 If successful, the return value is the number of the leaf nodes or 0 if the object does not 885 connect to any database file. */ 886 uint64_t tcbdblnum(TCBDB *bdb); 887 888 889 /* Get the number of the non-leaf nodes of B+ tree database object. 890 `bdb' specifies the B+ tree database object. 891 If successful, the return value is the number of the non-leaf nodes or 0 if the object does 892 not connect to any database file. */ 893 uint64_t tcbdbnnum(TCBDB *bdb); 894 895 896 /* Get the number of elements of the bucket array of a B+ tree database object. 897 `bdb' specifies the B+ tree database object. 898 The return value is the number of elements of the bucket array or 0 if the object does not 899 connect to any database file. */ 900 uint64_t tcbdbbnum(TCBDB *bdb); 901 902 903 /* Get the record alignment of a B+ tree database object. 904 `bdb' specifies the B+ tree database object. 905 The return value is the record alignment or 0 if the object does not connect to any database 906 file. */ 907 uint32_t tcbdbalign(TCBDB *bdb); 908 909 910 /* Get the maximum number of the free block pool of a B+ tree database object. 911 `bdb' specifies the B+ tree database object. 912 The return value is the maximum number of the free block pool or 0 if the object does not 913 connect to any database file. */ 914 uint32_t tcbdbfbpmax(TCBDB *bdb); 915 916 917 /* Get the inode number of the database file of a B+ tree database object. 918 `bdb' specifies the B+ tree database object. 919 The return value is the inode number of the database file or 0 if the object does not connect 920 to any database file. */ 921 uint64_t tcbdbinode(TCBDB *bdb); 922 923 924 /* Get the modification time of the database file of a B+ tree database object. 925 `bdb' specifies the B+ tree database object. 926 The return value is the inode number of the database file or 0 if the object does not connect 927 to any database file. */ 928 time_t tcbdbmtime(TCBDB *bdb); 929 930 931 /* Get the additional flags of a B+ tree database object. 932 `bdb' specifies the B+ tree database object. 933 The return value is the additional flags. */ 934 uint8_t tcbdbflags(TCBDB *bdb); 935 936 937 /* Get the options of a B+ tree database object. 938 `bdb' specifies the B+ tree database object. 939 The return value is the options. */ 940 uint8_t tcbdbopts(TCBDB *bdb); 941 942 943 /* Get the pointer to the opaque field of a B+ tree database object. 944 `bdb' specifies the B+ tree database object. 945 The return value is the pointer to the opaque field whose size is 128 bytes. */ 946 char *tcbdbopaque(TCBDB *bdb); 947 948 949 /* Get the number of used elements of the bucket array of a B+ tree database object. 950 `bdb' specifies the B+ tree database object. 951 The return value is the number of used elements of the bucket array or 0 if the object does not 952 connect to any database file. */ 953 uint64_t tcbdbbnumused(TCBDB *bdb); 954 955 956 /* Set the maximum size of each leaf node. 957 `bdb' specifies the B+ tree database object which is not opened. 958 `lsmax' specifies the maximum size of each leaf node. If it is not more than 0, the default 959 value is specified. The default value is 16386. 960 If successful, the return value is true, else, it is false. 961 Note that the tuning parameters of the database should be set before the database is opened. */ 962 bool tcbdbsetlsmax(TCBDB *bdb, uint32_t lsmax); 963 964 965 /* Set the capacity number of records. 966 `bdb' specifies the B+ tree database object which is not opened. 967 `capnum' specifies the capacity number of records. If it is not more than 0, the capacity is 968 unlimited. 969 If successful, the return value is true, else, it is false. 970 When the number of records exceeds the capacity, forehand records are removed implicitly. 971 Note that the tuning parameters of the database should be set before the database is opened. */ 972 bool tcbdbsetcapnum(TCBDB *bdb, uint64_t capnum); 973 974 975 /* Set the custom codec functions of a B+ tree database object. 976 `bdb' specifies the B+ tree database object. 977 `enc' specifies the pointer to the custom encoding function. It receives four parameters. 978 The first parameter is the pointer to the region. The second parameter is the size of the 979 region. The third parameter is the pointer to the variable into which the size of the region 980 of the return value is assigned. The fourth parameter is the pointer to the optional opaque 981 object. It returns the pointer to the result object allocated with `malloc' call if 982 successful, else, it returns `NULL'. 983 `encop' specifies an arbitrary pointer to be given as a parameter of the encoding function. 984 If it is not needed, `NULL' can be specified. 985 `dec' specifies the pointer to the custom decoding function. 986 `decop' specifies an arbitrary pointer to be given as a parameter of the decoding function. 987 If it is not needed, `NULL' can be specified. 988 If successful, the return value is true, else, it is false. 989 Note that the custom codec functions should be set before the database is opened and should be 990 set every time the database is being opened. */ 991 bool tcbdbsetcodecfunc(TCBDB *bdb, TCCODEC enc, void *encop, TCCODEC dec, void *decop); 992 993 994 /* Get the unit step number of auto defragmentation of a B+ tree database object. 995 `bdb' specifies the B+ tree database object. 996 The return value is the unit step number of auto defragmentation. */ 997 uint32_t tcbdbdfunit(TCBDB *bdb); 998 999 1000 /* Perform dynamic defragmentation of a B+ tree database object. 1001 `bdb' specifies the B+ tree database object connected as a writer. 1002 `step' specifie the number of steps. If it is not more than 0, the whole file is defragmented 1003 gradually without keeping a continuous lock. 1004 If successful, the return value is true, else, it is false. */ 1005 bool tcbdbdefrag(TCBDB *bdb, int64_t step); 1006 1007 1008 /* Clear the cache of a B+ tree database object. 1009 `bdb' specifies the B+ tree database object. 1010 If successful, the return value is true, else, it is false. */ 1011 bool tcbdbcacheclear(TCBDB *bdb); 1012 1013 1014 /* Store a new record into a B+ tree database object with backward duplication. 1015 `bdb' specifies the B+ tree database object connected as a writer. 1016 `kbuf' specifies the pointer to the region of the key. 1017 `ksiz' specifies the size of the region of the key. 1018 `vbuf' specifies the pointer to the region of the value. 1019 `vsiz' specifies the size of the region of the value. 1020 If successful, the return value is true, else, it is false. 1021 If a record with the same key exists in the database, the new record is placed after the 1022 existing one. */ 1023 bool tcbdbputdupback(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz); 1024 1025 1026 /* Store a new string record into a B+ tree database object with backward duplication. 1027 `bdb' specifies the B+ tree database object connected as a writer. 1028 `kstr' specifies the string of the key. 1029 `vstr' specifies the string of the value. 1030 If successful, the return value is true, else, it is false. 1031 If a record with the same key exists in the database, the new record is placed after the 1032 existing one. */ 1033 bool tcbdbputdupback2(TCBDB *bdb, const char *kstr, const char *vstr); 1034 1035 1036 /* Store a record into a B+ tree database object with a duplication handler. 1037 `bdb' specifies the B+ tree database object connected as a writer. 1038 `kbuf' specifies the pointer to the region of the key. 1039 `ksiz' specifies the size of the region of the key. 1040 `vbuf' specifies the pointer to the region of the value. `NULL' means that record addition is 1041 ommited if there is no corresponding record. 1042 `vsiz' specifies the size of the region of the value. 1043 `proc' specifies the pointer to the callback function to process duplication. It receives 1044 four parameters. The first parameter is the pointer to the region of the value. The second 1045 parameter is the size of the region of the value. The third parameter is the pointer to the 1046 variable into which the size of the region of the return value is assigned. The fourth 1047 parameter is the pointer to the optional opaque object. It returns the pointer to the result 1048 object allocated with `malloc'. It is released by the caller. If it is `NULL', the record is 1049 not modified. If it is `(void *)-1', the record is removed. 1050 `op' specifies an arbitrary pointer to be given as a parameter of the callback function. If 1051 it is not needed, `NULL' can be specified. 1052 If successful, the return value is true, else, it is false. 1053 Note that the callback function can not perform any database operation because the function 1054 is called in the critical section guarded by the same locks of database operations. */ 1055 bool tcbdbputproc(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz, 1056 TCPDPROC proc, void *op); 1057 1058 1059 /* Move a cursor object to the rear of records corresponding a key. 1060 `cur' specifies the cursor object. 1061 `kbuf' specifies the pointer to the region of the key. 1062 `ksiz' specifies the size of the region of the key. 1063 If successful, the return value is true, else, it is false. False is returned if there is 1064 no record corresponding the condition. 1065 The cursor is set to the last record corresponding the key or the previous substitute if 1066 completely matching record does not exist. */ 1067 bool tcbdbcurjumpback(BDBCUR *cur, const void *kbuf, int ksiz); 1068 1069 1070 /* Move a cursor object to the rear of records corresponding a key string. 1071 `cur' specifies the cursor object. 1072 `kstr' specifies the string of the key. 1073 If successful, the return value is true, else, it is false. False is returned if there is 1074 no record corresponding the condition. 1075 The cursor is set to the last record corresponding the key or the previous substitute if 1076 completely matching record does not exist. */ 1077 bool tcbdbcurjumpback2(BDBCUR *cur, const char *kstr); 1078 1079 1080 /* Process each record atomically of a B+ tree database object. 1081 `bdb' specifies the B+ tree database object. 1082 `iter' specifies the pointer to the iterator function called for each record. It receives 1083 five parameters. The first parameter is the pointer to the region of the key. The second 1084 parameter is the size of the region of the key. The third parameter is the pointer to the 1085 region of the value. The fourth parameter is the size of the region of the value. The fifth 1086 parameter is the pointer to the optional opaque object. It returns true to continue iteration 1087 or false to stop iteration. 1088 `op' specifies an arbitrary pointer to be given as a parameter of the iterator function. If 1089 it is not needed, `NULL' can be specified. 1090 If successful, the return value is true, else, it is false. 1091 Note that the callback function can not perform any database operation because the function 1092 is called in the critical section guarded by the same locks of database operations. */ 1093 bool tcbdbforeach(TCBDB *bdb, TCITER iter, void *op); 1094 1095 1096 1097 __TCBDB_CLINKAGEEND 1098 #endif /* duplication check */ 1099 1100 1101 /* END OF FILE */ 1102