1 /************************************************************************************************* 2 * The GDBM-compatible API of QDBM 3 * Copyright (C) 2000-2006 Mikio Hirabayashi 4 * This file is part of QDBM, Quick Database Manager. 5 * QDBM is free software; you can redistribute it and/or modify it under the terms of the GNU 6 * Lesser General Public License as published by the Free Software Foundation; either version 7 * 2.1 of the License or any later version. QDBM is distributed in the hope that it will be 8 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 9 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 10 * details. 11 * You should have received a copy of the GNU Lesser General Public License along with QDBM; if 12 * not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 13 * 02111-1307 USA. 14 *************************************************************************************************/ 15 16 17 #ifndef _HOVEL_H /* duplication check */ 18 #define _HOVEL_H 19 20 #if defined(__cplusplus) /* export for C++ */ 21 extern "C" { 22 #endif 23 24 25 #include <depot.h> 26 #include <curia.h> 27 #include <stdlib.h> 28 #include <sys/types.h> 29 #include <sys/stat.h> 30 31 32 #if defined(_MSC_VER) && !defined(QDBM_INTERNAL) && !defined(QDBM_STATIC) 33 #define MYEXTERN extern __declspec(dllimport) 34 #else 35 #define MYEXTERN extern 36 #endif 37 38 39 40 /************************************************************************************************* 41 * API 42 *************************************************************************************************/ 43 44 45 enum { /* enumeration for error codes */ 46 GDBM_NO_ERROR, /* no error */ 47 GDBM_MALLOC_ERROR, /* malloc error */ 48 GDBM_BLOCK_SIZE_ERROR, /* block size error */ 49 GDBM_FILE_OPEN_ERROR, /* file open error */ 50 GDBM_FILE_WRITE_ERROR, /* file write error */ 51 GDBM_FILE_SEEK_ERROR, /* file seek error */ 52 GDBM_FILE_READ_ERROR, /* file read error */ 53 GDBM_BAD_MAGIC_NUMBER, /* bad magic number */ 54 GDBM_EMPTY_DATABASE, /* empty database */ 55 GDBM_CANT_BE_READER, /* can't be reader */ 56 GDBM_CANT_BE_WRITER, /* can't be writer */ 57 GDBM_READER_CANT_DELETE, /* reader can't delete */ 58 GDBM_READER_CANT_STORE, /* reader can't store */ 59 GDBM_READER_CANT_REORGANIZE, /* reader can't reorganize */ 60 GDBM_UNKNOWN_UPDATE, /* unknown update */ 61 GDBM_ITEM_NOT_FOUND, /* item not found */ 62 GDBM_REORGANIZE_FAILED, /* reorganize failed */ 63 GDBM_CANNOT_REPLACE, /* cannot replace */ 64 GDBM_ILLEGAL_DATA, /* illegal data */ 65 GDBM_OPT_ALREADY_SET, /* option already set */ 66 GDBM_OPT_ILLEGAL /* option illegal */ 67 }; 68 69 typedef int gdbm_error; /* type of error codes */ 70 71 typedef struct { /* type of structure for a database handle */ 72 DEPOT *depot; /* internal database handle of Depot */ 73 CURIA *curia; /* internal database handle of Curia */ 74 int syncmode; /* whether to be besyncronous mode */ 75 } GDBM; 76 77 typedef GDBM *GDBM_FILE; /* type of pointer to a database handle */ 78 79 typedef struct { /* type of structure for a key or a value */ 80 char *dptr; /* pointer to the region */ 81 size_t dsize; /* size of the region */ 82 } datum; 83 84 enum { /* enumeration for open modes */ 85 GDBM_READER = 1 << 0, /* open as a reader */ 86 GDBM_WRITER = 1 << 1, /* open as a writer */ 87 GDBM_WRCREAT = 1 << 2, /* a writer creating */ 88 GDBM_NEWDB = 1 << 3, /* a writer creating and truncating */ 89 GDBM_SYNC = 1 << 4, /* syncronous mode */ 90 GDBM_NOLOCK = 1 << 5, /* no lock mode */ 91 GDBM_LOCKNB = 1 << 6, /* non-blocking lock mode */ 92 GDBM_FAST = 1 << 7, /* fast mode */ 93 GDBM_SPARSE = 1 << 8 /* create as sparse file */ 94 }; 95 96 enum { /* enumeration for write modes */ 97 GDBM_INSERT, /* keep an existing value */ 98 GDBM_REPLACE /* overwrite an existing value */ 99 }; 100 101 enum { /* enumeration for options */ 102 GDBM_CACHESIZE, /* set cache size */ 103 GDBM_FASTMODE, /* set fast mode */ 104 GDBM_SYNCMODE, /* set syncronous mode */ 105 GDBM_CENTFREE, /* set free block pool */ 106 GDBM_COALESCEBLKS /* set free block marging */ 107 }; 108 109 110 /* String containing the version information. */ 111 MYEXTERN char *gdbm_version; 112 113 114 /* Last happened error code. */ 115 #define gdbm_errno (*gdbm_errnoptr()) 116 117 118 /* Get a message string corresponding to an error code. 119 `gdbmerrno' specifies an error code. 120 The return value is the message string of the error code. The region of the return value 121 is not writable. */ 122 char *gdbm_strerror(gdbm_error gdbmerrno); 123 124 125 /* Get a database handle after the fashion of GDBM. 126 `name' specifies a name of a database. 127 `read_write' specifies the connection mode: `GDBM_READER' as a reader, `GDBM_WRITER', 128 `GDBM_WRCREAT' and `GDBM_NEWDB' as a writer. `GDBM_WRCREAT' makes a database file or 129 directory if it does not exist. `GDBM_NEWDB' makes a new database even if it exists. 130 You can add the following to writer modes by bitwise or: `GDBM_SYNC', `GDBM_NOLOCK', 131 `GDBM_LCKNB', `GDBM_FAST', and `GDBM_SPARSE'. `GDBM_SYNC' means a database is synchronized 132 after every updating method. `GDBM_NOLOCK' means a database is opened without file locking. 133 `GDBM_LOCKNB' means file locking is performed without blocking. `GDBM_FAST' is ignored. 134 `GDBM_SPARSE' is an original mode of QDBM and makes database a sparse file. 135 `mode' specifies a mode of a database file or a database directory as the one of `open' 136 or `mkdir' call does. 137 `bnum' specifies the number of elements of each bucket array. If it is not more than 0, 138 the default value is specified. 139 `dnum' specifies the number of division of the database. If it is not more than 0, the 140 returning handle is created as a wrapper of Depot, else, it is as a wrapper of Curia. 141 The return value is the database handle or `NULL' if it is not successful. 142 If the database already exists, whether it is one of Depot or Curia is measured 143 automatically. */ 144 GDBM_FILE gdbm_open(char *name, int block_size, int read_write, int mode, 145 void (*fatal_func)(void)); 146 147 148 /* Get a database handle after the fashion of QDBM. 149 `name' specifies a name of a database. 150 `read_write' specifies the connection mode: `GDBM_READER' as a reader, `GDBM_WRITER', 151 `GDBM_WRCREAT' and `GDBM_NEWDB' as a writer. `GDBM_WRCREAT' makes a database file or 152 directory if it does not exist. `GDBM_NEWDB' makes a new database even if it exists. 153 You can add the following to writer modes by bitwise or: `GDBM_SYNC', `GDBM_NOLOCK', 154 `GDBM_LOCKNB', `GDBM_FAST', and `GDBM_SPARSE'. `GDBM_SYNC' means a database is synchronized 155 after every updating method. `GDBM_NOLOCK' means a database is opened without file locking. 156 `GDBM_LOCKNB' means file locking is performed without blocking. `GDBM_FAST' is ignored. 157 `GDBM_SPARSE' is an original mode of QDBM and makes database sparse files. 158 `mode' specifies a mode of a database file as the one of `open' or `mkdir' call does. 159 `bnum' specifies the number of elements of each bucket array. If it is not more than 0, 160 the default value is specified. 161 `dnum' specifies the number of division of the database. If it is not more than 0, the 162 returning handle is created as a wrapper of Depot, else, it is as a wrapper of Curia. 163 `align' specifies the basic size of alignment. 164 The return value is the database handle or `NULL' if it is not successful. */ 165 GDBM_FILE gdbm_open2(char *name, int read_write, int mode, int bnum, int dnum, int align); 166 167 168 /* Close a database handle. 169 `dbf' specifies a database handle. 170 Because the region of the closed handle is released, it becomes impossible to use the 171 handle. */ 172 void gdbm_close(GDBM_FILE dbf); 173 174 175 /* Store a record. 176 `dbf' specifies a database handle connected as a writer. 177 `key' specifies a structure of a key. `content' specifies a structure of a value. 178 `flag' specifies behavior when the key overlaps, by the following values: `GDBM_REPLACE', 179 which means the specified value overwrites the existing one, `GDBM_INSERT', which means 180 the existing value is kept. 181 The return value is 0 if it is successful, 1 if it gives up because of overlaps of the key, 182 -1 if other error occurs. */ 183 int gdbm_store(GDBM_FILE dbf, datum key, datum content, int flag); 184 185 186 /* Delete a record. 187 `dbf' specifies a database handle connected as a writer. 188 `key' specifies a structure of a key. 189 The return value is 0 if it is successful, -1 if some errors occur. */ 190 int gdbm_delete(GDBM_FILE dbf, datum key); 191 192 193 /* Retrieve a record. 194 `dbf' specifies a database handle. 195 `key' specifies a structure of a key. 196 The return value is a structure of the result. 197 If a record corresponds, the member `dptr' of the structure is the pointer to the region 198 of the value. If no record corresponds or some errors occur, `dptr' is `NULL'. Because 199 the region pointed to by `dptr' is allocated with the `malloc' call, it should be 200 released with the `free' call if it is no longer in use. */ 201 datum gdbm_fetch(GDBM_FILE dbf, datum key); 202 203 204 /* Check whether a record exists or not. 205 `dbf' specifies a database handle. 206 `key' specifies a structure of a key. 207 The return value is true if a record corresponds and no error occurs, or false, else, 208 it is false. */ 209 int gdbm_exists(GDBM_FILE dbf, datum key); 210 211 212 /* Get the first key of a database. 213 `dbf' specifies a database handle. 214 The return value is a structure of the result. 215 If a record corresponds, the member `dptr' of the structure is the pointer to the region 216 of the first key. If no record corresponds or some errors occur, `dptr' is `NULL'. 217 Because the region pointed to by `dptr' is allocated with the `malloc' call, it should 218 be released with the `free' call if it is no longer in use. */ 219 datum gdbm_firstkey(GDBM_FILE dbf); 220 221 222 /* Get the next key of a database. 223 `dbf' specifies a database handle. 224 The return value is a structure of the result. 225 If a record corresponds, the member `dptr' of the structure is the pointer to the region 226 of the next key. If no record corresponds or some errors occur, `dptr' is `NULL'. 227 Because the region pointed to by `dptr' is allocated with the `malloc' call, it should 228 be released with the `free' call if it is no longer in use. */ 229 datum gdbm_nextkey(GDBM_FILE dbf, datum key); 230 231 232 /* Synchronize updating contents with the file and the device. 233 `dbf' specifies a database handle connected as a writer. */ 234 void gdbm_sync(GDBM_FILE dbf); 235 236 237 /* Reorganize a database. 238 `dbf' specifies a database handle connected as a writer. 239 If successful, the return value is 0, else -1. */ 240 int gdbm_reorganize(GDBM_FILE dbf); 241 242 243 /* Get the file descriptor of a database file. 244 `dbf' specifies a database handle connected as a writer. 245 The return value is the file descriptor of the database file. 246 If the database is a directory the return value is -1. */ 247 int gdbm_fdesc(GDBM_FILE dbf); 248 249 250 /* No effect. 251 `dbf' specifies a database handle. 252 `option' is ignored. `size' is ignored. 253 The return value is 0. 254 The function is only for compatibility. */ 255 int gdbm_setopt(GDBM_FILE dbf, int option, int *value, int size); 256 257 258 259 /************************************************************************************************* 260 * features for experts 261 *************************************************************************************************/ 262 263 264 /* Get the pointer of the last happened error code. */ 265 int *gdbm_errnoptr(void); 266 267 268 269 #undef MYEXTERN 270 271 #if defined(__cplusplus) /* export for C++ */ 272 } 273 #endif 274 275 #endif /* duplication check */ 276 277 278 /* END OF FILE */ 279