upscaledb  2.1.13
upscaledb.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2005-2016 Christoph Rupp (chris@crupp.de).
3  * All Rights Reserved.
4  *
5  * This program is free software: you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation, either version 3 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  * GNU General Public License for more details.
14  *
15  * See the file COPYING for License information.
16  */
17 
110 #ifndef UPS_UPSCALEDB_H
111 #define UPS_UPSCALEDB_H
112 
113 #include <ups/types.h>
114 
115 #ifdef __cplusplus
116 extern "C" {
117 #endif
118 
119 /* deprecated */
120 #define UPS_API_REVISION 3
121 
142 #define UPS_VERSION_MAJ 2
143 #define UPS_VERSION_MIN 1
144 #define UPS_VERSION_REV 13
145 #define UPS_FILE_VERSION 5
146 
153 struct ups_db_t;
154 typedef struct ups_db_t ups_db_t;
155 
162 struct ups_env_t;
163 typedef struct ups_env_t ups_env_t;
164 
174 struct ups_cursor_t;
175 typedef struct ups_cursor_t ups_cursor_t;
176 
200 typedef struct {
203 
205  void *data;
206 
209 
212 
215 
216 } ups_record_t;
217 
221 #define UPS_RECORD_USER_ALLOC 1
222 
229 #define ups_make_record(PTR, SIZE) { SIZE, PTR, 0 }
230 
257 typedef struct {
260 
262  void *data;
263 
266 
269 
270 } ups_key_t;
271 
278 #define ups_make_key(PTR, SIZE) { SIZE, PTR, 0 }
279 
283 #define UPS_KEY_USER_ALLOC 1
284 
302 typedef struct {
305 
308 
310 
311 
318 #define UPS_TYPE_BINARY 0
319 
320 #define UPS_TYPE_CUSTOM 1
321 
322 #define UPS_TYPE_UINT8 3
323 
324 #define UPS_TYPE_UINT16 5
325 
326 #define UPS_TYPE_UINT32 7
327 
328 #define UPS_TYPE_UINT64 9
329 
330 #define UPS_TYPE_REAL32 11
331 
332 #define UPS_TYPE_REAL64 12
333 
345 #define UPS_SUCCESS ( 0)
346 
347 #define UPS_INV_RECORD_SIZE ( -2)
348 
349 #define UPS_INV_KEY_SIZE ( -3)
350 /* deprecated */
351 #define UPS_INV_KEYSIZE UPS_INV_KEY_SIZE
352 
353 #define UPS_INV_PAGE_SIZE ( -4)
354 /* deprecated */
355 #define UPS_INV_PAGESIZE UPS_INV_PAGE_SIZE
356 
357 #define UPS_OUT_OF_MEMORY ( -6)
358 
359 #define UPS_INV_PARAMETER ( -8)
360 
361 #define UPS_INV_FILE_HEADER ( -9)
362 
363 #define UPS_INV_FILE_VERSION (-10)
364 
365 #define UPS_KEY_NOT_FOUND (-11)
366 
367 #define UPS_DUPLICATE_KEY (-12)
368 
369 #define UPS_INTEGRITY_VIOLATED (-13)
370 
371 #define UPS_INTERNAL_ERROR (-14)
372 
373 #define UPS_WRITE_PROTECTED (-15)
374 
375 #define UPS_BLOB_NOT_FOUND (-16)
376 
377 #define UPS_IO_ERROR (-18)
378 
379 #define UPS_NOT_IMPLEMENTED (-20)
380 
381 #define UPS_FILE_NOT_FOUND (-21)
382 
383 #define UPS_WOULD_BLOCK (-22)
384 
385 #define UPS_NOT_READY (-23)
386 
387 #define UPS_LIMITS_REACHED (-24)
388 
389 #define UPS_ALREADY_INITIALIZED (-27)
390 
391 #define UPS_NEED_RECOVERY (-28)
392 
393 #define UPS_CURSOR_STILL_OPEN (-29)
394 
395 #define UPS_FILTER_NOT_FOUND (-30)
396 
397 #define UPS_TXN_CONFLICT (-31)
398 /* internal use: key was erased in a Transaction */
399 #define UPS_KEY_ERASED_IN_TXN (-32)
400 
401 #define UPS_TXN_STILL_OPEN (-33)
402 
403 #define UPS_CURSOR_IS_NIL (-100)
404 
405 #define UPS_DATABASE_NOT_FOUND (-200)
406 
407 #define UPS_DATABASE_ALREADY_EXISTS (-201)
408 
409 #define UPS_DATABASE_ALREADY_OPEN (-202)
410 
411 #define UPS_ENVIRONMENT_ALREADY_OPEN (-203)
412 
413 #define UPS_LOG_INV_FILE_HEADER (-300)
414 
415 #define UPS_NETWORK_ERROR (-400)
416 
444 typedef void UPS_CALLCONV (*ups_error_handler_fun)(int level, const char *message);
445 
447 #define UPS_DEBUG_LEVEL_DEBUG 0
448 
450 #define UPS_DEBUG_LEVEL_NORMAL 1
451 
453 #define UPS_DEBUG_LEVEL_FATAL 3
454 
472 
480 UPS_EXPORT const char * UPS_CALLCONV
481 ups_strerror(ups_status_t status);
482 
491 ups_get_version(uint32_t *major, uint32_t *minor,
492  uint32_t *revision);
493 
635 ups_env_create(ups_env_t **env, const char *filename,
636  uint32_t flags, uint32_t mode, const ups_parameter_t *param);
637 
741 ups_env_open(ups_env_t **env, const char *filename,
742  uint32_t flags, const ups_parameter_t *param);
743 
778 
936  uint16_t name, uint32_t flags, const ups_parameter_t *params);
937 
989  uint16_t name, uint32_t flags, const ups_parameter_t *params);
990 
1016 ups_env_rename_db(ups_env_t *env, uint16_t oldname,
1017  uint16_t newname, uint32_t flags);
1018 
1038 ups_env_erase_db(ups_env_t *env, uint16_t name, uint32_t flags);
1039 
1040 /* internal flag - only flush committed transactions, not the btree pages */
1041 #define UPS_FLUSH_COMMITTED_TRANSACTIONS 1
1042 
1059 ups_env_flush(ups_env_t *env, uint32_t flags);
1060 
1061 /* internal use only - don't lock mutex */
1062 #define UPS_DONT_LOCK 0xf0000000
1063 
1088  uint32_t *count);
1089 
1128 ups_env_close(ups_env_t *env, uint32_t flags);
1129 
1146 struct ups_txn_t;
1147 typedef struct ups_txn_t ups_txn_t;
1148 
1178 ups_txn_begin(ups_txn_t **txn, ups_env_t *env, const char *name,
1179  void *reserved, uint32_t flags);
1180 
1182 #define UPS_TXN_READ_ONLY 1
1183 
1184 /* Internal flag for @ref ups_txn_begin */
1185 #define UPS_TXN_TEMPORARY 2
1186 
1192 UPS_EXPORT const char *
1194 
1214 ups_txn_commit(ups_txn_t *txn, uint32_t flags);
1215 
1235 ups_txn_abort(ups_txn_t *txn, uint32_t flags);
1236 
1249 #define UPS_ENABLE_FSYNC 0x00000001
1250 
1251 /* unused 0x00000002 */
1252 
1255 #define UPS_READ_ONLY 0x00000004
1256 
1257 /* unused 0x00000008 */
1258 
1259 /* unused 0x00000010 */
1260 
1261 /* reserved 0x00000020 */
1262 
1263 /* unused 0x00000040 */
1264 
1267 #define UPS_IN_MEMORY 0x00000080
1268 
1269 /* reserved: DB_USE_MMAP (not persistent) 0x00000100 */
1270 
1273 #define UPS_DISABLE_MMAP 0x00000200
1274 
1275 /* deprecated */
1276 #define UPS_RECORD_NUMBER UPS_RECORD_NUMBER64
1277 
1280 #define UPS_RECORD_NUMBER32 0x00001000
1281 
1284 #define UPS_RECORD_NUMBER64 0x00002000
1285 
1288 #define UPS_ENABLE_DUPLICATE_KEYS 0x00004000
1289 /* deprecated */
1290 #define UPS_ENABLE_DUPLICATES UPS_ENABLE_DUPLICATE_KEYS
1291 
1292 /* deprecated */
1293 #define UPS_ENABLE_RECOVERY UPS_ENABLE_TRANSACTIONS
1294 
1297 #define UPS_AUTO_RECOVERY 0x00010000
1298 
1301 #define UPS_ENABLE_TRANSACTIONS 0x00020000
1302 
1305 #define UPS_CACHE_UNLIMITED 0x00040000
1306 
1309 #define UPS_DISABLE_RECOVERY 0x00080000
1310 
1311 /* internal use only! (not persistent) */
1312 #define UPS_IS_REMOTE_INTERNAL 0x00200000
1313 
1314 /* internal use only! (not persistent) */
1315 #define UPS_DISABLE_RECLAIM_INTERNAL 0x00400000
1316 
1317 /* internal use only! (persistent) */
1318 #define UPS_FORCE_RECORDS_INLINE 0x00800000
1319 
1320 /* deprecated */
1321 #define UPS_FLUSH_WHEN_COMMITTED 0x01000000
1322 
1325 #define UPS_ENABLE_CRC32 0x02000000
1326 
1327 /* internal use only! (not persistent) */
1328 #define UPS_DONT_FLUSH_TRANSACTIONS 0x04000000
1329 
1339  const uint8_t *lhs, uint32_t lhs_length,
1340  const uint8_t *rhs, uint32_t rhs_length);
1341 
1364 ups_register_compare(const char *name, ups_compare_func_t func);
1365 
1366 /* deprecated */
1369 
1491 ups_db_find(ups_db_t *db, ups_txn_t *txn, ups_key_t *key,
1492  ups_record_t *record, uint32_t flags);
1493 
1575 ups_db_insert(ups_db_t *db, ups_txn_t *txn, ups_key_t *key,
1576  ups_record_t *record, uint32_t flags);
1577 
1589 #define UPS_OVERWRITE 0x0001
1590 
1592 #define UPS_DUPLICATE 0x0002
1593 
1595 #define UPS_DUPLICATE_INSERT_BEFORE 0x0004
1596 
1598 #define UPS_DUPLICATE_INSERT_AFTER 0x0008
1599 
1601 #define UPS_DUPLICATE_INSERT_FIRST 0x0010
1602 
1604 #define UPS_DUPLICATE_INSERT_LAST 0x0020
1605 
1607 #define UPS_DIRECT_ACCESS 0x0040
1608 
1611 #define UPS_PARTIAL 0x0080
1612 
1613 /* Internal flag for @ref ups_db_find, @ref ups_cursor_find,
1614  * @ref ups_cursor_move */
1615 #define UPS_FORCE_DEEP_COPY 0x0100
1616 
1629 #define UPS_HINT_APPEND 0x00080000
1630 
1643 #define UPS_HINT_PREPEND 0x00100000
1644 
1649 #define UPS_HINTS_MASK 0x001F0000
1650 
1675 ups_db_erase(ups_db_t *db, ups_txn_t *txn, ups_key_t *key, uint32_t flags);
1676 
1677 /* internal flag for ups_db_erase() - do not use */
1678 #define UPS_ERASE_ALL_DUPLICATES 1
1679 
1702 ups_db_count(ups_db_t *db, ups_txn_t *txn, uint32_t flags,
1703  uint64_t *count);
1704 
1742 
1746 #define UPS_PARAM_JOURNAL_SWITCH_THRESHOLD 0x00001
1747 
1750 #define UPS_PARAM_CACHE_SIZE 0x00000100
1751 /* deprecated */
1752 #define UPS_PARAM_CACHESIZE UPS_PARAM_CACHE_SIZE
1753 
1755 #define UPS_PARAM_PAGE_SIZE 0x00000101
1756 /* deprecated */
1757 #define UPS_PARAM_PAGESIZE UPS_PARAM_PAGE_SIZE
1758 
1760 #define UPS_PARAM_KEY_SIZE 0x00000102
1761 /* deprecated */
1762 #define UPS_PARAM_KEYSIZE UPS_PARAM_KEY_SIZE
1763 
1766 #define UPS_PARAM_MAX_DATABASES 0x00000103
1767 
1769 #define UPS_PARAM_KEY_TYPE 0x00000104
1770 
1773 #define UPS_PARAM_LOG_DIRECTORY 0x00000105
1774 
1777 #define UPS_PARAM_ENCRYPTION_KEY 0x00000106
1778 
1781 #define UPS_PARAM_NETWORK_TIMEOUT_SEC 0x00000107
1782 
1784 #define UPS_PARAM_RECORD_SIZE 0x00000108
1785 
1788 #define UPS_PARAM_FILE_SIZE_LIMIT 0x00000109
1789 
1792 #define UPS_PARAM_POSIX_FADVISE 0x00000110
1793 
1795 #define UPS_PARAM_CUSTOM_COMPARE_NAME 0x00000111
1796 
1798 #define UPS_POSIX_FADVICE_NORMAL 0
1799 
1801 #define UPS_POSIX_FADVICE_RANDOM 1
1802 
1804 #define UPS_RECORD_SIZE_UNLIMITED ((uint32_t)-1)
1805 
1807 #define UPS_KEY_SIZE_UNLIMITED ((uint16_t)-1)
1808 
1811 #define UPS_PARAM_FLAGS 0x00000200
1812 
1815 #define UPS_PARAM_FILEMODE 0x00000201
1816 
1824 #define UPS_PARAM_FILENAME 0x00000202
1825 
1830 #define UPS_PARAM_DATABASE_NAME 0x00000203
1831 
1837 #define UPS_PARAM_MAX_KEYS_PER_PAGE 0x00000204
1838 
1843 #define UPS_PARAM_JOURNAL_COMPRESSION 0x00001000
1844 
1850 #define UPS_PARAM_RECORD_COMPRESSION 0x00001001
1851 
1857 #define UPS_PARAM_KEY_COMPRESSION 0x00001002
1858 
1860 #define UPS_COMPRESSOR_NONE 0
1861 
1866 #define UPS_COMPRESSOR_ZLIB 1
1867 
1872 #define UPS_COMPRESSOR_SNAPPY 2
1873 
1878 #define UPS_COMPRESSOR_LZF 3
1879 
1884 #define UPS_COMPRESSOR_UINT32_VARBYTE 5
1885 
1889 #define UPS_COMPRESSOR_UINT32_SIMDCOMP 6
1890 
1894 #define UPS_COMPRESSOR_UINT32_GROUPVARINT 7
1895 
1899 #define UPS_COMPRESSOR_UINT32_STREAMVBYTE 8
1900 
1904 #define UPS_COMPRESSOR_UINT32_MASKEDVBYTE 9
1905 
1909 #define UPS_COMPRESSOR_UINT32_FOR 10
1910 
1914 #define UPS_COMPRESSOR_UINT32_SIMDFOR 11
1915 
1925 
1953 ups_db_close(ups_db_t *db, uint32_t flags);
1954 
1956 #define UPS_AUTO_CLEANUP 1
1957 
1959 #define UPS_DONT_CLEAR_LOG 2
1960 
1962 #define UPS_TXN_AUTO_ABORT 4
1963 
1965 #define UPS_TXN_AUTO_COMMIT 8
1966 
2005 ups_cursor_create(ups_cursor_t **cursor, ups_db_t *db, ups_txn_t *txn,
2006  uint32_t flags);
2007 
2028 
2145 ups_cursor_move(ups_cursor_t *cursor, ups_key_t *key,
2146  ups_record_t *record, uint32_t flags);
2147 
2149 #define UPS_CURSOR_FIRST 0x0001
2150 
2152 #define UPS_CURSOR_LAST 0x0002
2153 
2155 #define UPS_CURSOR_NEXT 0x0004
2156 
2158 #define UPS_CURSOR_PREVIOUS 0x0008
2159 
2161 #define UPS_SKIP_DUPLICATES 0x0010
2162 
2164 #define UPS_ONLY_DUPLICATES 0x0020
2165 
2183  uint32_t flags);
2184 
2310 ups_cursor_find(ups_cursor_t *cursor, ups_key_t *key,
2311  ups_record_t *record, uint32_t flags);
2312 
2313 /* internal flag */
2314 #define UPS_FIND_EQ_MATCH 0x4000
2315 
2320 #define UPS_FIND_LT_MATCH 0x1000
2321 
2326 #define UPS_FIND_GT_MATCH 0x2000
2327 
2335 #define UPS_FIND_LEQ_MATCH (UPS_FIND_LT_MATCH | UPS_FIND_EQ_MATCH)
2336 
2344 #define UPS_FIND_GEQ_MATCH (UPS_FIND_GT_MATCH | UPS_FIND_EQ_MATCH)
2345 
2359 #define UPS_FIND_NEAR_MATCH (UPS_FIND_LT_MATCH | UPS_FIND_GT_MATCH \
2360  | UPS_FIND_EQ_MATCH)
2361 
2476  ups_record_t *record, uint32_t flags);
2477 
2500 ups_cursor_erase(ups_cursor_t *cursor, uint32_t flags);
2501 
2521  uint32_t *count, uint32_t flags);
2522 
2538  uint32_t *position);
2539 
2554 
2571 
2576 #ifdef __cplusplus
2577 } // extern "C"
2578 #endif
2579 
2580 #endif /* UPS_UPSCALEDB_H */
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_get_parameters(ups_env_t *env, ups_parameter_t *param)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_get_duplicate_count(ups_cursor_t *cursor, uint32_t *count, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_get_database_names(ups_env_t *env, uint16_t *names, uint32_t *count)
struct ups_txn_t ups_txn_t
Definition: upscaledb.h:1147
uint32_t flags
Definition: upscaledb.h:208
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_open(ups_env_t **env, const char *filename, uint32_t flags, const ups_parameter_t *param)
UPS_EXPORT const char *UPS_CALLCONV ups_strerror(ups_status_t status)
Portable typedefs for upscaledb.
unsigned short uint16_t
Definition: msstdint.h:84
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_close(ups_env_t *env, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_erase(ups_db_t *db, ups_txn_t *txn, ups_key_t *key, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_insert(ups_db_t *db, ups_txn_t *txn, ups_key_t *key, ups_record_t *record, uint32_t flags)
unsigned __int64 uint64_t
Definition: msstdint.h:95
unsigned char uint8_t
Definition: msstdint.h:83
uint32_t partial_size
Definition: upscaledb.h:214
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_clone(ups_cursor_t *src, ups_cursor_t **dest)
int UPS_CALLCONV(* ups_compare_func_t)(ups_db_t *db, const uint8_t *lhs, uint32_t lhs_length, const uint8_t *rhs, uint32_t rhs_length)
Definition: upscaledb.h:1338
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_find(ups_db_t *db, ups_txn_t *txn, ups_key_t *key, ups_record_t *record, uint32_t flags)
void UPS_CALLCONV(* ups_error_handler_fun)(int level, const char *message)
Definition: upscaledb.h:444
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_move(ups_cursor_t *cursor, ups_key_t *key, ups_record_t *record, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_erase_db(ups_env_t *env, uint16_t name, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_rename_db(ups_env_t *env, uint16_t oldname, uint16_t newname, uint32_t flags)
unsigned int uint32_t
Definition: msstdint.h:85
uint32_t name
Definition: upscaledb.h:304
uint32_t partial_offset
Definition: upscaledb.h:211
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_get_duplicate_position(ups_cursor_t *cursor, uint32_t *position)
uint16_t size
Definition: upscaledb.h:259
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_find(ups_cursor_t *cursor, ups_key_t *key, ups_record_t *record, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_get_record_size(ups_cursor_t *cursor, uint64_t *size)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_count(ups_db_t *db, ups_txn_t *txn, uint32_t flags, uint64_t *count)
uint32_t flags
Definition: upscaledb.h:265
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_get_parameters(ups_db_t *db, ups_parameter_t *param)
UPS_EXPORT const char * ups_txn_get_name(ups_txn_t *txn)
struct ups_db_t ups_db_t
Definition: upscaledb.h:154
struct ups_cursor_t ups_cursor_t
Definition: upscaledb.h:175
uint64_t value
Definition: upscaledb.h:307
#define UPS_CALLCONV
Definition: types.h:97
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_flush(ups_env_t *env, uint32_t flags)
uint32_t _flags
Definition: upscaledb.h:268
UPS_EXPORT ups_status_t UPS_CALLCONV ups_register_compare(const char *name, ups_compare_func_t func)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_close(ups_cursor_t *cursor)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_overwrite(ups_cursor_t *cursor, ups_record_t *record, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_open_db(ups_env_t *env, ups_db_t **db, uint16_t name, uint32_t flags, const ups_parameter_t *params)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_create(ups_env_t **env, const char *filename, uint32_t flags, uint32_t mode, const ups_parameter_t *param)
void * data
Definition: upscaledb.h:262
UPS_EXPORT ups_status_t ups_txn_begin(ups_txn_t **txn, ups_env_t *env, const char *name, void *reserved, uint32_t flags)
UPS_EXPORT ups_status_t ups_txn_commit(ups_txn_t *txn, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_insert(ups_cursor_t *cursor, ups_key_t *key, ups_record_t *record, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_erase(ups_cursor_t *cursor, uint32_t flags)
UPS_EXPORT ups_status_t ups_txn_abort(ups_txn_t *txn, uint32_t flags)
UPS_EXPORT void UPS_CALLCONV ups_set_error_handler(ups_error_handler_fun f)
void * data
Definition: upscaledb.h:205
#define UPS_EXPORT
Definition: types.h:89
uint32_t size
Definition: upscaledb.h:202
int ups_status_t
Definition: types.h:138
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_set_compare_func(ups_db_t *db, ups_compare_func_t foo)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_env_create_db(ups_env_t *env, ups_db_t **db, uint16_t name, uint32_t flags, const ups_parameter_t *params)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_cursor_create(ups_cursor_t **cursor, ups_db_t *db, ups_txn_t *txn, uint32_t flags)
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_close(ups_db_t *db, uint32_t flags)
UPS_EXPORT ups_env_t *UPS_CALLCONV ups_db_get_env(ups_db_t *db)
UPS_EXPORT void UPS_CALLCONV ups_get_version(uint32_t *major, uint32_t *minor, uint32_t *revision)
struct ups_env_t ups_env_t
Definition: upscaledb.h:163