hamsterdb API Documentation
hamsterdb.h File Reference
#include <ham/types.h>Go to the source code of this file.
Define Documentation
| #define HAM_AUTO_CLEANUP 1 |
Flag for ham_close, ham_env_close
Definition at line 1493 of file hamsterdb.h.
| #define HAM_AUTO_RECOVERY 0x00010000 |
Flag for ham_open_ex, ham_env_open_ex
Definition at line 1149 of file hamsterdb.h.
| #define HAM_CACHE_STRICT 0x00000400 |
Flag for ham_open, ham_open_ex, ham_create, ham_create_ex
Definition at line 1129 of file hamsterdb.h.
| #define HAM_DISABLE_FREELIST_FLUSH 0x00000800 |
Definition at line 1133 of file hamsterdb.h.
| #define HAM_DISABLE_MMAP 0x00000200 |
Flag for ham_open, ham_open_ex, ham_create, ham_create_ex
Definition at line 1126 of file hamsterdb.h.
| #define HAM_DISABLE_VAR_KEYLEN 0x00000040 |
Flag for ham_create, ham_create_ex
Definition at line 1118 of file hamsterdb.h.
| #define HAM_DONT_CLEAR_LOG 2 |
Definition at line 1496 of file hamsterdb.h.
| #define HAM_DUPLICATE 2 |
Flag for ham_insert and ham_cursor_insert
Definition at line 1398 of file hamsterdb.h.
| #define HAM_DUPLICATE_INSERT_AFTER 8 |
Flag for ham_cursor_insert
Definition at line 1404 of file hamsterdb.h.
| #define HAM_DUPLICATE_INSERT_BEFORE 4 |
Flag for ham_cursor_insert
Definition at line 1401 of file hamsterdb.h.
| #define HAM_DUPLICATE_INSERT_FIRST 16 |
Flag for ham_cursor_insert
Definition at line 1407 of file hamsterdb.h.
| #define HAM_DUPLICATE_INSERT_LAST 32 |
Flag for ham_cursor_insert
Definition at line 1410 of file hamsterdb.h.
| #define HAM_ENABLE_DUPLICATES 0x00004000 |
Flag for ham_create, ham_create_ex
Definition at line 1142 of file hamsterdb.h.
| #define HAM_ENABLE_RECOVERY 0x00008000 |
Flag for ham_create_ex, ham_open_ex, ham_env_create_ex, ham_env_open_ex
Definition at line 1146 of file hamsterdb.h.
| #define HAM_ENABLE_TRANSACTIONS 0x00020000 |
Flag for ham_create_ex, ham_open_ex, ham_env_create_ex, ham_env_open_ex
Definition at line 1153 of file hamsterdb.h.
| #define HAM_IN_MEMORY_DB 0x00000080 |
Flag for ham_create, ham_create_ex
Definition at line 1121 of file hamsterdb.h.
| #define HAM_KEY_USER_ALLOC 1 |
Flag for ham_key_t (only in combination with ham_cursor_move)
Definition at line 131 of file hamsterdb.h.
| #define HAM_LOCK_EXCLUSIVE 0x00001000 |
Flag for ham_open, ham_open_ex, ham_create, ham_create_ex
Definition at line 1136 of file hamsterdb.h.
| #define HAM_OVERWRITE 1 |
Flag for ham_insert and ham_cursor_insert
Definition at line 1395 of file hamsterdb.h.
| #define HAM_PARAM_CACHESIZE 0x00000100 |
Parameter name for ham_open_ex, ham_create_ex; sets the cache size
Definition at line 1157 of file hamsterdb.h.
| #define HAM_PARAM_KEYSIZE 0x00000102 |
Parameter name for ham_create_ex; sets the key size
Definition at line 1164 of file hamsterdb.h.
| #define HAM_PARAM_MAX_ENV_DATABASES 0x00000103 |
Parameter name for ham_env_create_ex; sets the number of maximum Databases
Definition at line 1168 of file hamsterdb.h.
| #define HAM_PARAM_PAGESIZE 0x00000101 |
Parameter name for ham_open_ex, ham_create_ex; sets the page size
Definition at line 1161 of file hamsterdb.h.
| #define HAM_READ_ONLY 0x00000004 |
Flag for ham_open, ham_open_ex
Definition at line 1108 of file hamsterdb.h.
| #define HAM_RECORD_NUMBER 0x00002000 |
Flag for ham_create, ham_create_ex, ham_env_create_db
Definition at line 1139 of file hamsterdb.h.
| #define HAM_RECORD_USER_ALLOC 1 |
Flag for ham_record_t
Definition at line 94 of file hamsterdb.h.
| #define HAM_TXN_AUTO_ABORT 4 |
Automatically abort all open Transactions (the default)
Definition at line 1499 of file hamsterdb.h.
| #define HAM_TXN_AUTO_COMMIT 8 |
Automatically commit all open Transactions
Definition at line 1502 of file hamsterdb.h.
| #define HAM_USE_BTREE 0x00000010 |
Flag for ham_create, ham_create_ex
Definition at line 1113 of file hamsterdb.h.
| #define HAM_WRITE_THROUGH 0x00000001 |
Flag for ham_open, ham_open_ex, ham_create, ham_create_ex
Definition at line 1105 of file hamsterdb.h.
Typedef Documentation
| typedef int(* ham_compare_func_t)(ham_db_t *db, const ham_u8_t *lhs, ham_size_t lhs_length, const ham_u8_t *rhs, ham_size_t rhs_length) |
Typedef for a comparison function
- Remarks:
- This function compares two index keys. It returns -1, if lhs ("left-hand side", the paramter on the left side) is smaller than rhs ("right-hand side"), 0 if both keys are equal, and 1 if lhs is larger than rhs.
Definition at line 1237 of file hamsterdb.h.
| typedef struct ham_cursor_t ham_cursor_t |
Definition at line 55 of file hamsterdb.h.
Definition at line 34 of file hamsterdb.h.
Definition at line 43 of file hamsterdb.h.
| typedef int(* ham_prefix_compare_func_t)(ham_db_t *db, const ham_u8_t *lhs, ham_size_t lhs_length, ham_size_t lhs_real_length, const ham_u8_t *rhs, ham_size_t rhs_length, ham_size_t rhs_real_length) |
Typedef for a prefix comparison function
- Remarks:
- This function compares two index keys. It returns -1 if lhs ("left-hand side", the paramter on the left side) is smaller than rhs ("right-hand side"), 0 if both keys are equal, and 1 if lhs is larger than rhs.
If one of the keys is only partially loaded, but the comparison function needs the full key, the return value should be HAM_PREFIX_REQUEST_FULLKEY.
Definition at line 1205 of file hamsterdb.h.
Function Documentation
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_close | ( | ham_db_t * | db, | |
| ham_u32_t | flags | |||
| ) |
Closes the Database
This function flushes the Database and then closes the file handle. It does not free the memory resources allocated in the db handle - use ham_delete to free db.
If the flag HAM_AUTO_CLEANUP is specified, hamsterdb automatically calls ham_cursor_close on all open Cursors. This invalidates the ham_cursor_t handle!
If the flag is not specified, the application must close all Database Cursors with ham_cursor_close to prevent memory leaks.
This function removes all file-level filters installed with ham_add_file_filter.
This function also aborts all Transactions which were not yet committed, and therefore renders all Transaction handles invalid. If the flag HAM_TXN_AUTO_COMMIT is specified, all Transactions will be committed.
- Parameters:
-
db A valid Database handle flags Optional flags for closing the Database. Possible values are: - HAM_AUTO_CLEANUP. Automatically closes all open Cursors
- HAM_TXN_AUTO_COMMIT. Automatically commit all open Transactions
- HAM_TXN_AUTO_ABORT. Automatically abort all open Transactions; this is the default behaviour
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if db is NULL
Referenced by ham::db::close().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_create | ( | ham_db_t * | db, | |
| const char * | filename, | |||
| ham_u32_t | flags, | |||
| ham_u32_t | mode | |||
| ) |
Creates a Database
- Parameters:
-
db A valid Database handle filename The filename of the Database file. If the file already exists, it is overwritten. Can be NULL if you create an In-Memory Database flags Optional flags for opening the Database, combined with bitwise OR. For allowed flags, see ham_create_ex. mode File access rights for the new file. This is the mode parameter for creat(2). Ignored on Microsoft Windows.
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if the db pointer is NULL or an invalid combination of flags was specified
HAM_IO_ERROR if the file could not be opened or reading/writing failed
HAM_INV_FILE_VERSION if the Database version is not compatible with the library version
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_WOULD_BLOCK if another process has locked the file
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_create_ex | ( | ham_db_t * | db, | |
| const char * | filename, | |||
| ham_u32_t | flags, | |||
| ham_u32_t | mode, | |||
| ham_parameter_t * | param | |||
| ) |
Creates a Database - extended version
- Parameters:
-
db A valid Database handle filename The filename of the Database file. If the file already exists, it will be overwritten. Can be NULL if you create an In-Memory Database flags Optional flags for opening the Database, combined with bitwise OR. Possible flags are: - HAM_WRITE_THROUGH Immediately write modified pages to the disk. This slows down all Database operations, but may save the Database integrity in case of a system crash.
- HAM_USE_BTREE Use a B+Tree for the index structure. Currently enabled by default, but future releases of hamsterdb will offer additional index structures, i.e. hash tables.
- HAM_DISABLE_VAR_KEYLEN Do not allow the use of variable length keys. Inserting a key, which is larger than the B+Tree index key size, returns HAM_INV_KEYSIZE.
- HAM_IN_MEMORY_DB Creates an In-Memory Database. No file will be created, and the Database contents are lost after the Database is closed. The filename parameter can be NULL. Do NOT use in combination with HAM_CACHE_STRICT and do NOT specify cachesize other than 0.
- HAM_RECORD_NUMBER Creates an "auto-increment" Database. Keys in Record Number Databases are automatically assigned an incrementing 64bit value. If key->data is not NULL (and key->flags is HAM_KEY_USER_ALLOC and key->size is 8), the value of the current key is returned in key (a host-endian 64bit number of type ham_u64_t). If key-data is NULL and key->size is 0, key->data is temporarily allocated by hamsterdb.
- HAM_ENABLE_DUPLICATES Enable duplicate keys for this Database. By default, duplicate keys are disabled.
- HAM_DISABLE_MMAP Do not use memory mapped files for I/O. By default, hamsterdb checks if it can use mmap, since mmap is faster than read/write. For performance reasons, this flag should not be used.
- HAM_CACHE_STRICT Do not allow the cache to grow larger than cachesize. If a Database operation needs to resize the cache, it will return HAM_CACHE_FULL. If the flag is not set, the cache is allowed to allocate more pages than the maximum cache size, but only if it's necessary and only for a short time.
- HAM_DISABLE_FREELIST_FLUSH This flag is deprecated.
- HAM_LOCK_EXCLUSIVE Place an exclusive lock on the file. Only one process may hold an exclusive lock for a given file at a given time.
- HAM_ENABLE_RECOVERY Enables logging/recovery for this Database. Not allowed in combination with HAM_IN_MEMORY_DB, HAM_DISABLE_FREELIST_FLUSH and HAM_WRITE_THROUGH.
-
HAM_ENABLE_TRANSACTIONS Enables Transactions for this Database. Remark Transactions were introduced in hamsterdb 1.0.4, but with certain limitations (which will be removed in later version). Please read the README file and the Release Notes for details.
This flag imples HAM_ENABLE_RECOVERY.
mode File access rights for the new file. This is the mode parameter for creat(2). Ignored on Microsoft Windows. param An array of ham_parameter_t structures. The following parameters are available: - HAM_PARAM_CACHESIZE The size of the Database cache, in bytes. The default size is defined in src/config.h as HAM_DEFAULT_CACHESIZE - usually 256kb.
- HAM_PARAM_PAGESIZE The size of a file page, in bytes. It is recommended not to change the default size. The default size depends on hardware and operating system. Page sizes must be a multiple of 1024.
- HAM_PARAM_KEYSIZE The size of the keys in the B+Tree index. The default size is 21 bytes.
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if the db pointer is NULL or an invalid combination of flags was specified
HAM_IO_ERROR if the file could not be opened or reading/writing failed
HAM_INV_FILE_VERSION if the Database version is not compatible with the library version
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_INV_PAGESIZE if pagesize is not a multiple of 1024
HAM_INV_KEYSIZE if keysize is too large (at least 4 keys must fit in a page)
HAM_WOULD_BLOCK if another process has locked the file
Referenced by ham::db::create().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_delete | ( | ham_db_t * | db | ) |
Frees a ham_db_t handle
Frees the memory and resources of a ham_db_t structure, but does not close the Database. Call this function AFTER you have closed the Database using ham_close, or you will lose your data!
- Parameters:
-
db A valid Database handle
- Returns:
- This function always returns HAM_SUCCESS
Referenced by ham::db::close(), ham::env::create_db(), and ham::env::open_db().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_enable_compression | ( | ham_db_t * | db, | |
| ham_u32_t | level, | |||
| ham_u32_t | flags | |||
| ) |
Enables zlib compression for all inserted records
This function enables zlib compression for all inserted Database records.
The compression will be active till ham_close is called. If the Database handle is reused after calling ham_close, the compression is no longer active. ham_enable_compression should be called immediately after ham_create[_ex] or ham_open[_ex].
Note that zlib usually has an overhead and often is not effective if the records are small (i.e. < 128byte), but this highly depends on the data that is inserted.
The zlib compression filter does not allow queries (i.e. with ham_find) with user-allocated records and the flag HAM_RECORD_USER_ALLOC. In this case, the query-function will return HAM_INV_PARAMETER.
- Parameters:
-
db A valid Database handle level The compression level. 0 for the zlib default, 1 for best speed and 9 for minimum size flags Optional flags for the compression; unused, set to 0
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if db is NULL or level is not between 0 and 9
HAM_NOT_IMPLEMENTED if hamsterdb was compiled without support for compression
Referenced by ham::db::enable_compression().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_erase | ( | ham_db_t * | db, | |
| ham_txn_t * | txn, | |||
| ham_key_t * | key, | |||
| ham_u32_t | flags | |||
| ) |
Erases a Database item
This function erases a Database item. If the item key does not exist, HAM_KEY_NOT_FOUND is returned.
Note that ham_erase can not erase a single duplicate key. If the key has multiple duplicates, all duplicates of this key will be erased. Use ham_cursor_erase to erase a specific duplicate key.
- Parameters:
-
db A valid Database handle txn A Transaction handle, or NULL key The key to delete flags Optional flags for erasing; unused, set to 0
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if db or key is NULL
HAM_DB_READ_ONLY if you tried to erase a key from a read-only Database
HAM_KEY_NOT_FOUND if key was not found
Referenced by ham::db::erase().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_find | ( | ham_db_t * | db, | |
| ham_txn_t * | txn, | |||
| ham_key_t * | key, | |||
| ham_record_t * | record, | |||
| ham_u32_t | flags | |||
| ) |
Searches an item in the Database
This function searches the Database for key. If the key is found, record will receive the record of this item and HAM_SUCCESS is returned. If the key is not found, the function returns HAM_KEY_NOT_FOUND.
A ham_record_t structure should be initialized with zeroes before it is being used. This can be done with the C library routines memset(3) or bzero(2).
If the function completes successfully, the record pointer is initialized with the size of the record (in record.size) and the actual record data (in record.data). If the record is empty, size is 0 and data points to NULL.
The data pointer is a temporary pointer and will be overwritten by subsequent hamsterdb API calls. You can alter this behaviour by allocating the data pointer in the application and setting record.flags to HAM_RECORD_USER_ALLOC. Make sure that the allocated buffer is large enough.
ham_find can not search for duplicate keys. If key has multiple duplicates, only the first duplicate is returned.
- Parameters:
-
db A valid Database handle txn A Transaction handle, or NULL key The key of the item record The record of the item flags Optional flags for searching; unused, set to 0
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if db, key or record is NULL
HAM_KEY_NOT_FOUND if the key does not exist
Referenced by ham::db::find().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_flush | ( | ham_db_t * | db, | |
| ham_u32_t | flags | |||
| ) |
Flushes the Database
This function flushes the Database cache and writes the whole file to disk. If this Database was opened in an Environment, all other Databases of this Environment are flushed as well.
Since In-Memory Databases do not have a file on disk, the function will have no effect and will return HAM_SUCCESS.
- Parameters:
-
db A valid Database handle flags Optional flags for flushing; unused, set to 0
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if db is NULL
Referenced by ham::db::flush().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_get_error | ( | ham_db_t * | db | ) |
Returns the last error code
- Parameters:
-
db A valid Database handle
- Returns:
- The last error code which was returned by one of the hamsterdb API functions. Use ham_strerror to translate this code to a descriptive string
Referenced by ham::db::get_error().
Returns the flags which were specified when the Database was created or opened
- Parameters:
-
db A valid Database handle
- Returns:
- The Database flags
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_insert | ( | ham_db_t * | db, | |
| ham_txn_t * | txn, | |||
| ham_key_t * | key, | |||
| ham_record_t * | record, | |||
| ham_u32_t | flags | |||
| ) |
Inserts a Database item
This function inserts a key/record pair as a new Database item.
If the key already exists in the Database, error HAM_DUPLICATE_KEY is returned.
If you wish to overwrite an existing entry specify the flag HAM_OVERWRITE.
If you wish to insert a duplicate key specify the flag HAM_DUPLICATE. (Note that the Database has to be created with HAM_ENABLE_DUPLICATES in order to use duplicate keys.) The duplicate key is inserted after all other duplicate keys (see HAM_DUPLICATE_INSERT_LAST).
Record Number Databases (created with HAM_RECORD_NUMBER) expect either an empty key (with a size of 0 and data pointing to NULL), or a user-supplied key (with key.flag HAM_KEY_USER_ALLOC, a size of 8 and a valid data pointer). If key.size is 0 and key.data is NULL, hamsterdb will temporarily allocate memory for key->data, which will then point to an 8-byte unsigned integer in host-endian.
- Parameters:
-
db A valid Database handle txn A Transaction handle, or NULL key The key of the new item record The record of the new item flags Optional flags for inserting. Possible flags are: - HAM_OVERWRITE. If the key already exists, the record is overwritten. Otherwise, the key is inserted.
- HAM_DUPLICATE. If the key already exists, a duplicate key is inserted. The key is inserted before the already existing key.
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if db, key or record is NULL
HAM_INV_PARAMETER if the Database is a Record Number Database and the key is invalid (see above)
HAM_INV_PARAMETER if the flags HAM_OVERWRITE and HAM_DUPLICATE were specified, or if HAM_DUPLICATE was specified, but the Database was not created with flag HAM_ENABLE_DUPLICATES.
HAM_DB_READ_ONLY if you tried to insert a key in a read-only Database
HAM_INV_KEYSIZE if the key size is larger than the keysize parameter specified for ham_create_ex and variable key sizes are disabled (see HAM_DISABLE_VAR_KEYLEN) OR if the keysize parameter specified for ham_create_ex is smaller than 8
Referenced by ham::db::insert().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_new | ( | ham_db_t ** | db | ) |
Allocates a ham_db_t handle
- Parameters:
-
db Pointer to the pointer which is allocated
- Returns:
- HAM_SUCCESS upon success
HAM_OUT_OF_MEMORY if memory allocation failed
Referenced by ham::db::create(), ham::env::create_db(), ham::db::open(), and ham::env::open_db().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_open | ( | ham_db_t * | db, | |
| const char * | filename, | |||
| ham_u32_t | flags | |||
| ) |
Opens an existing Database
- Parameters:
-
db A valid Database handle filename The filename of the Database file flags Optional flags for opening the Database, combined with bitwise OR. See the documentation of ham_open_ex for the allowed flags
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if the db pointer is NULL or an invalid combination of flags was specified
HAM_FILE_NOT_FOUND if the file does not exist
HAM_IO_ERROR if the file could not be opened or reading failed
HAM_INV_FILE_VERSION if the Database version is not compatible with the library version
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_WOULD_BLOCK if another process has locked the file
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_open_ex | ( | ham_db_t * | db, | |
| const char * | filename, | |||
| ham_u32_t | flags, | |||
| ham_parameter_t * | param | |||
| ) |
Opens an existing Database - extended version
- Parameters:
-
db A valid Database handle filename The filename of the Database file flags Optional flags for opening the Database, combined with bitwise OR. Possible flags are: - HAM_READ_ONLY Opens the file for reading only. Operations which need write access (i.e. ham_insert) will return HAM_DB_READ_ONLY.
- HAM_WRITE_THROUGH Immediately write modified pages to the disk. This slows down all Database operations, but could save the Database integrity in case of a system crash.
- HAM_DISABLE_VAR_KEYLEN Do not allow the use of variable length keys. Inserting a key, which is larger than the B+Tree index key size, returns HAM_INV_KEYSIZE.
- HAM_DISABLE_MMAP Do not use memory mapped files for I/O. By default, hamsterdb checks if it can use mmap, since mmap is faster than read/write. For performance reasons, this flag should not be used.
- HAM_CACHE_STRICT Do not allow the cache to grow larger than cachesize. If a Database operation needs to resize the cache, it will return HAM_CACHE_FULL. If the flag is not set, the cache is allowed to allocate more pages than the maximum cache size, but only if it's necessary and only for a short time.
- HAM_DISABLE_FREELIST_FLUSH This flag is deprecated.
- HAM_LOCK_EXCLUSIVE Place an exclusive lock on the file. Only one process may hold an exclusive lock for a given file at a given time.
- HAM_ENABLE_RECOVERY Enables logging/recovery for this Database. Will return HAM_NEED_RECOVERY, if the Database is in an inconsistent state. Not allowed in combination with HAM_IN_MEMORY_DB, HAM_DISABLE_FREELIST_FLUSH and HAM_WRITE_THROUGH.
- HAM_AUTO_RECOVERY Automatically recover the Database, if necessary. This flag implies HAM_ENABLE_RECOVERY.
-
HAM_ENABLE_TRANSACTIONS Enables Transactions for this Database. Remark Transactions were introduced in hamsterdb 1.0.4, but with certain limitations (which will be removed in later version). Please read the README file and the Release Notes for details.
This flag imples HAM_ENABLE_RECOVERY.
param An array of ham_parameter_t structures. The following parameters are available: - HAM_PARAM_CACHESIZE The size of the Database cache, in bytes. The default size is defined in src/config.h as HAM_DEFAULT_CACHESIZE - usually 256kb.
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if the db pointer is NULL or an invalid combination of flags was specified
HAM_FILE_NOT_FOUND if the file does not exist
HAM_IO_ERROR if the file could not be opened or reading failed
HAM_INV_FILE_VERSION if the Database version is not compatible with the library version
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_WOULD_BLOCK if another process has locked the file
HAM_NEED_RECOVERY if the Database is in an inconsistent state
HAM_LOG_INV_FILE_HEADER if the logfile is corrupt
Referenced by ham::db::open().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_set_compare_func | ( | ham_db_t * | db, | |
| ham_compare_func_t | foo | |||
| ) |
Sets the comparison function
The comparison function compares two index keys. It returns -1 if the first key is smaller, +1 if the second key is smaller or 0 if both keys are equal.
If foo is NULL, hamsterdb will use the default compare function (which is based on memcmp(3)).
Note that if you use a custom comparison routine in combination with extended keys, it might be useful to disable the prefix comparison, which is based on memcmp(3). See
- See also:
- ham_set_prefix_compare_func for details.
- Parameters:
-
db A valid Database handle foo A pointer to the compare function
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if one of the parameters is NULL
Referenced by ham::db::set_compare_func().
| HAM_EXPORT ham_status_t HAM_CALLCONV ham_set_prefix_compare_func | ( | ham_db_t * | db, | |
| ham_prefix_compare_func_t | foo | |||
| ) |
Sets the prefix comparison function
The prefix comparison function is called when an index uses keys with variable length and at least one of the two keys is loaded only partially.
If foo is NULL, hamsterdb will not use any prefix comparison.
- Parameters:
-
db A valid Database handle foo A pointer to the prefix compare function
- Returns:
- HAM_SUCCESS upon success
HAM_INV_PARAMETER if the db parameter is NULL
Referenced by ham::db::set_prefix_compare_func().