hamsterdb.h

About: hamsterdb is a database engine written in ANSI C. It supports a B+Tree index structure, uses

ham_new(ham_db_t **db);

/**
 * Deletes a ham_db_t handle.
 *
 * Frees the ham_db_t structure, but does not close the
 * database. Call this function <b>AFTER</b> you have closed the
 * database using @a ham_close, or you will lose your data!
 *
 * @param db A valid database handle.
 *
 * @return This function always returns @a HAM_SUCCESS.
 */
HAM_EXPORT ham_status_t
ham_delete(ham_db_t *db);

/**
 * Creates a database.
 *
 * @param db A valid database handle.
 * @param 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.
 * @param flags Optional flags for opening the database, combined with
 *        bitwise OR. For allowed flags, see @a ham_create_ex.
 * @param mode File access rights for the new file. This is the @a mode
 *        parameter for creat(2). Ignored on Microsoft Windows.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a db pointer is NULL or an
 *              invalid combination of flags was specified.
 * @return @a HAM_IO_ERROR if the file could not be opened or
 *              reading/writing failed.
 * @return @a HAM_INV_FILE_VERSION if the database version is not
 *              compatible with the library version.
 * @return @a HAM_OUT_OF_MEMORY if memory could not be allocated.
 * @return @a HAM_WOULD_BLOCK if another process has locked the file
 *
 */
HAM_EXPORT ham_status_t
ham_create(ham_db_t *db, const char *filename,
        ham_u32_t flags, ham_u32_t mode);

/**
 * Creates a database - extended version.
 *
 * @param db A valid database handle.
 * @param 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.
 * @param flags Optional flags for opening the database, combined with
 *        bitwise OR. Possible flags are:
 *
 *      <ul>
 *       <li>@a HAM_WRITE_THROUGH</li> 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.
 *       <li>@a HAM_USE_BTREE</li> 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.
 *       <li>@a HAM_DISABLE_VAR_KEYLEN</li> Do not allow the use of variable
 *            length keys. Inserting a key, which is larger than the
 *            B+Tree index key size, returns @a HAM_INV_KEYSIZE.
 *       <li>@a HAM_IN_MEMORY_DB</li> Creates an in-memory database. No file
 *            will be created, and the database contents are lost after
 *            the database is closed. The @a filename parameter can
 *            be NULL. Do <b>NOT</b> use in combination with
 *            @a HAM_CACHE_STRICT and do <b>NOT</b> specify @a cachesize
 *            other than 0.
 *       <li>@a HAM_DISABLE_MMAP</li> 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.
 *       <li>@a HAM_CACHE_STRICT</li> Do not allow the cache to grow larger
 *            than @a cachesize. If a database operation needs to resize the
 *            cache, it will return @a 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.
 *       <li>@a HAM_DISABLE_FREELIST_FLUSH</li> Do not immediately write back
 *            modified freelist pages. Using this flag leads to small
 *            performance improvements, but may prove to be risky
 *            in case of a system crash or program crash.
 *       <li>@a HAM_LOCK_EXCLUSIVE</li> Place an exclusive lock on the
 *            file. Only one process may hold an exclusive lock for
 *            a given file at a given time. This flag will block the
 *            operation if the lock is held by another process.
 *      </ul>
 *
 * @param mode File access rights for the new file. This is the @a mode
 *        parameter for creat(2). Ignored on Microsoft Windows.
 * @param param An array of ham_parameter_t structures. The following
 *        parameters are available:
 *      <ul>
 *        <li>HAM_PARAM_CACHESIZE</li> The size of the database cache,
 *            in bytes. The default size is defined in src/config.h
 *            as HAM_DEFAULT_CACHESIZE - usually 256kb.
 *        <li>HAM_PARAM_PAGESIZE</li> The size of the file page, in
 *            bytes. It is recommended not to change the default size. The
 *            default size depends on your hardware and operating system.
 *            Page sizes must be a multiple of 1024.
 *        <li>HAM_PARAM_KEYSIZE</li> The size of the keys in the B+Tree
 *            index. The default size is 21 bytes.
 *      </ul>
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a db pointer is NULL or an
 *              invalid combination of flags was specified.
 * @return @a HAM_IO_ERROR if the file could not be opened or
 *              reading/writing failed.
 * @return @a HAM_INV_FILE_VERSION if the database version is not
 *              compatible with the library version.
 * @return @a HAM_OUT_OF_MEMORY if memory could not be allocated.
 * @return @a HAM_INV_PAGESIZE if @a pagesize is not a multiple of 1024.
 * @return @a HAM_INV_KEYSIZE if @a keysize is too large (at least 4
 *              keys must fit in a page).
 * @return @a HAM_WOULD_BLOCK if another process has locked the file
 *
 */
HAM_EXPORT ham_status_t
ham_create_ex(ham_db_t *db, const char *filename,
        ham_u32_t flags, ham_u32_t mode, ham_parameter_t *param);

/**
 * Opens an existing database.
 *
 * @param db A valid database handle.
 * @param filename The filename of the database file.
 * @param flags Optional flags for opening the database, combined with
 *        bitwise OR. See the documentation of @a ham_open_ex
 *        for the allowed flags.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a db pointer is NULL or an
 *              invalid combination of flags was specified.
 * @return @a HAM_FILE_NOT_FOUND if the file does not exist.
 * @return @a HAM_IO_ERROR if the file could not be opened or reading failed.
 * @return @a HAM_INV_FILE_VERSION if the database version is not
 *              compatible with the library version.
 * @return @a HAM_OUT_OF_MEMORY if memory could not be allocated.
 * @return @a HAM_WOULD_BLOCK if another process has locked the file
 */
HAM_EXPORT ham_status_t
ham_open(ham_db_t *db, const char *filename, ham_u32_t flags);

/**
 * Opens an existing database - extended version.
 *
 * @param db A valid database handle.
 * @param filename The filename of the database file.
 * @param flags Optional flags for opening the database, combined with
 *        bitwise OR. Possible flags are:
 *      <ul>
 *       <li>@a HAM_READ_ONLY</li> Opens the file for reading only.
 *            Operations which need write access (i.e. @a ham_insert) will
 *            return @a HAM_DB_READ_ONLY.
 *       <li>@a HAM_WRITE_THROUGH</li> 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.
 *       <li>@a HAM_DISABLE_VAR_KEYLEN</li> Do not allow the use of variable
 *            length keys. Inserting a key, which is larger than the
 *            B+Tree index key size, returns @a HAM_INV_KEYSIZE.
 *       <li>@a HAM_DISABLE_MMAP</li> 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.
 *       <li>@a HAM_CACHE_STRICT</li> Do not allow the cache to grow larger
 *            than @a cachesize. If a database operation needs to resize the
 *            cache, it will return @a 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.
 *       <li>@a HAM_DISABLE_FREELIST_FLUSH</li> Do not immediately write back
 *            modified freelist pages. Using this flag leads to small
 *            performance improvements, but may prove to be risky
 *            in case of a system crash or program crash.
 *       <li>@a HAM_LOCK_EXCLUSIVE</li> Place an exclusive lock on the
 *            file. Only one process may hold an exclusive lock for
 *            a given file at a given time. This flag will block the
 *            operation if the lock is held by another process.
 *      </ul>
 *
 * @param param An array of ham_parameter_t structures. The following
 *        parameters are available:
 *      <ul>
 *        <li>HAM_PARAM_CACHESIZE</li> The size of the database cache,
 *            in bytes. The default size is defined in src/config.h
 *            as HAM_DEFAULT_CACHESIZE - usually 256kb.
 *      </ul>
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a db pointer is NULL or an
 *              invalid combination of flags was specified.
 * @return @a HAM_FILE_NOT_FOUND if the file does not exist.
 * @return @a HAM_IO_ERROR if the file could not be opened or reading failed.
 * @return @a HAM_INV_FILE_VERSION if the database version is not
 *              compatible with the library version.
 * @return @a HAM_OUT_OF_MEMORY if memory could not be allocated.
 * @return @a HAM_WOULD_BLOCK if another process has locked the file
 */
HAM_EXPORT ham_status_t
ham_open_ex(ham_db_t *db, const char *filename,
        ham_u32_t flags, ham_parameter_t *param);

/** Flag for @a ham_open, @a ham_open_ex, @a ham_create, @a ham_create_ex */
#define HAM_WRITE_THROUGH            0x00000001

/** Flag for @a ham_open, @a ham_open_ex */
#define HAM_READ_ONLY                0x00000004

/* unused                            0x00000008 */

/** Flag for @a ham_create, @a ham_create_ex */
#define HAM_USE_BTREE                0x00000010

/* Use a hash database as the index structure
#define HAM_USE_HASH                 0x00000020
 */

/** Flag for @a ham_create, @a ham_create_ex */
#define HAM_DISABLE_VAR_KEYLEN       0x00000040

/** Flag for @a ham_create, @a ham_create_ex */
#define HAM_IN_MEMORY_DB             0x00000080

/* 0x100 is a reserved value         0x00000100 */

/** Flag for @a ham_open, @a ham_open_ex, @a ham_create, @a ham_create_ex */
#define HAM_DISABLE_MMAP             0x00000200

/** Flag for @a ham_open, @a ham_open_ex, @a ham_create, @a ham_create_ex */
#define HAM_CACHE_STRICT             0x00000400

/** Flag for @a ham_open, @a ham_open_ex, @a ham_create, @a ham_create_ex */
#define HAM_DISABLE_FREELIST_FLUSH   0x00000800

/** Flag for @a ham_open, @a ham_open_ex, @a ham_create, @a ham_create_ex */
#define HAM_LOCK_EXCLUSIVE           0x00001000

/** Parameter name for @a ham_open_ex, @a ham_create_ex; sets the cache
 * size*/
#define HAM_PARAM_CACHESIZE          0x00000100

/** Parameter name for @a ham_open_ex, @a ham_create_ex; sets the page
 * size*/
#define HAM_PARAM_PAGESIZE           0x00000101

/** Parameter name for @a ham_open_ex, @a ham_create_ex; sets the key
 * size*/
#define HAM_PARAM_KEYSIZE            0x00000102

/**
 * Returns the last error code.
 *
 * @param db A valid database handle.
 *
 * @return The last error code which was returned by one of the
 *         hamsterdb API functions. Use @a ham_strerror to translate
 *         this code to a descriptive string.
 */
HAM_EXPORT ham_status_t
ham_get_error(ham_db_t *db);

/**
 * Sets the prefix comparison function.
 *
 * The prefix comparison function is called when an index uses
 * keys with variable length, and one of the two keys is loaded only
 * partially.
 *
 * @param db A valid database handle.
 * @param foo A pointer to the prefix compare function.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if one of the parameters is NULL.
 */
HAM_EXPORT ham_status_t
ham_set_prefix_compare_func(ham_db_t *db, ham_prefix_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
 * keys are equal.
 *
 * The default comparison function uses memcmp to compare the keys.
 *
 * @param db A valid database handle.
 * @param foo A pointer to the compare function.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if one of the parameters is NULL.
 */
HAM_EXPORT ham_status_t
ham_set_compare_func(ham_db_t *db, ham_compare_func_t foo);

/**
 * Searches an item in the database.
 *
 * This function searches the database for @a key. If the key
 * is found, @a record will hold the record of this item and
 * @a HAM_SUCCESS is returned. If the key is not found, the function
 * returns with @a 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 @a record pointer is
 * initialized with the size of the record (in @a record.size) and a
 * pointer to the actual record data (in @a record.data). If the record
 * is empty, @a size is 0 and @a data is NULL.
 *
 * The @a data pointer is a temporary pointer and will be overwritten
 * by subsequent hamsterdb API calls. You can alter this behaviour by
 * allocating the @a data pointer in the application and setting
 * @a record.flags to @a HAM_RECORD_USER_ALLOC. Make sure that the allocated
 * buffer is large enough.
 *
 * @param db A valid database handle.
 * @param reserved A reserved value; set to NULL.
 * @param key The key of the item.
 * @param record The record of the item.
 * @param flags Search flags; unused, set to 0.