hamsterdb.h

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

 *              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 environment 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_env_create(ham_env_t *env, const char *filename,
        ham_u32_t flags, ham_u32_t mode);

/**
 * Creates a database environment - extended version.
 *
 * @param env A valid environment handle.
 * @param filename The filename of the environment file. If the file already
 *          exists, it is overwritten. Can be NULL if you create an
 *          in-memory environment.
 * @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_IN_MEMORY_DB</li> Creates an in-memory environment. No 
 *            file will be created, and the database contents are lost after
 *            the environment 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.
 *      </ul>
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a env pointer is NULL or an
 *              invalid combination of flags or parameters 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 environment 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_env_create_ex(ham_env_t *env, const char *filename,
        ham_u32_t flags, ham_u32_t mode, ham_parameter_t *param);

/**
 * Opens an existing database environment.
 *
 * @param env A valid environment handle.
 * @param filename The filename of the environment file.
 * @param flags Optional flags for opening the environment, combined with
 *        bitwise OR. See the documentation of @a ham_env_open_ex
 *        for the allowed flags.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a env 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_env_open(ham_env_t *env, const char *filename, ham_u32_t flags);

/**
 * Opens an existing database environment - extended version.
 *
 * @param env A valid environment handle.
 * @param filename The filename of the environment file.
 * @param flags Optional flags for opening the environment, combined with
 *        bitwise OR. Possible flags are:
 *      <ul>
 *       <li>@a HAM_READ_ONLY</li> Opens the file for reading only.
 *            Operations that 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_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 env pointer is NULL, an
 *              invalid combination of flags was specified or if
 *              the database name is invalid (i.e. 0 or in the reserved
 *              range, see above).
 * @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_env_open_ex(ham_env_t *env, const char *filename,
        ham_u32_t flags, ham_parameter_t *param);

/**
 * Creates a new database in a database environment.
 *
 * @param env A valid environment handle.
 * @param env A valid database handle, which will point to the created
 *          database. To close the handle, use @see ham_close.
 * @param name The name of the database. If a database with this name 
 *          already exists, the function will fail with 
 *          @a HAM_DATABASE_ALREADY_EXISTS. Database names from 0xf000 to
 *          0xffff and 0 are reserved.
 * @param flags Optional flags for creating the database, combined with
 *        bitwise OR. Possible flags are:
 *
 *      <ul>
 *       <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,
 *            like 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.
 *      </ul>
 *
 * @param param An array of ham_parameter_t structures. The following
 *        parameters are available:
 *      <ul>
 *        <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 env pointer is NULL or an
 *              invalid combination of flags was specified.
 * @return @a HAM_DATABASE_ALREADY_EXISTS if a database with this @a name
 *              already exists in this environment.
 * @return @a HAM_OUT_OF_MEMORY if memory could not be
 *              allocated.
 * @return @a HAM_ENV_FULL if the maximum number of databases per 
 *              environment was already created
 */
HAM_EXPORT ham_status_t
ham_env_create_db(ham_env_t *env, ham_db_t *db,
        ham_u16_t name, ham_u32_t flags, ham_parameter_t *params);

/**
 * Opens a database in a database environment.
 *
 * @param env A valid environment handle.
 * @param env A valid database handle, which will point to the created
 *          database. To close the handle, use @see ham_close.
 * @param name The name of the database. If a database with this name 
 *          does not exist, the function will fail with 
 *          @a HAM_DATABASE_NOT_FOUND.
 * @param flags Optional flags for opening the database, combined with
 *        bitwise OR. Possible flags are:
 *     <ul>
 *       <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.
 *     </ul>
 * @param param An array of ham_parameter_t structures. Unused, set 
 *        to NULL.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a env pointer is NULL or an
 *              invalid combination of flags was specified.
 * @return @a HAM_DATABASE_NOT_FOUND if a database with this @a name
 *              does not exist in this environment.
 * @return @a HAM_DATABASE_ALREADY_OPEN if this database was already
 *              opened
 * @return @a HAM_OUT_OF_MEMORY if memory could not be allocated.
 *
 */
HAM_EXPORT ham_status_t
ham_env_open_db(ham_env_t *env, ham_db_t *db,
        ham_u16_t name, ham_u32_t flags, ham_parameter_t *params);

/**
 * Renames a database in an environment.
 *
 * @param env A valid environment handle.
 * @param oldname The old name of the existing database. If a database 
 *          with this name does not exist, the function will fail with 
 *          @a HAM_DATABASE_NOT_FOUND.
 * @param newname The new name of this database. If a database 
 *          with this name already exists, the function will fail with 
 *          @a HAM_DATABASE_ALREADY_EXISTS.
 * @param flags Optional flags for renaming the database, combined with
 *        bitwise OR. Unused, set to 0.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a env pointer is NULL or if
 *              the new database name is reserved.
 * @return @a HAM_DATABASE_NOT_FOUND if a database with this @a name
 *              does not exist in this environment.
 * @return @a HAM_DATABASE_ALREADY_EXISTS if a database with the new name
 *              already exists
 * @return @a HAM_OUT_OF_MEMORY if memory could not be allocated.
 * @return @a HAM_NOT_READY if the environment @env was not initialized
 *              correctly (i.e. not yet opened or created)
 */
HAM_EXPORT ham_status_t
ham_env_rename_db(ham_env_t *env, ham_u16_t oldname, 
                ham_u16_t newname, ham_u32_t flags);

/**
 * Deletes a database from an environment.
 *
 * @param env A valid environment handle.
 * @param name The name of the database, which is deleted. If a database 
 *          with this name does not exist, the function will fail with 
 *          @a HAM_DATABASE_NOT_FOUND. If the database was already opened,
 *          the function will fail with @a HAM_DATABASE_ALREADY_OPEN.
 * @param flags Optional flags for renaming the database, combined with
 *        bitwise OR. Unused, set to 0.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if the @a env pointer is NULL or if
 *              the new database name is reserved.
 * @return @a HAM_DATABASE_NOT_FOUND if a database with this @a name
 *              does not exists in this environment.
 * @return @a HAM_DATABASE_ALREADY_OPEN if a database with this name is
 *              still open.
 */
HAM_EXPORT ham_status_t
ham_env_erase_db(ham_env_t *env, ham_u16_t name, ham_u32_t flags);

/**
 * Closes the database environment.
 *
 * This function closes the database environment. It does not free the 
 * memory resources allocated in the @a env handle - use @a ham_env_delete 
 * to free @a env.
 *
 * The application must close all databases before closing
 * the environment, or this function will fail (@see ham_close).
 *
 * @param env A valid environment handle.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_INV_PARAMETER if @a env is NULL.
 * @return @a HAM_ENV_NOT_EMPTY if there are still databases open.
 */
HAM_EXPORT ham_status_t
ham_env_close(ham_env_t *env);

/**
 * @}
 */

/**
 * @defgroup ham_db hamsterdb Database Functions
 * @{
 */

/**
 * Allocates a ham_db_t handle.
 *
 * @param db Pointer to the pointer which is allocated.
 *
 * @return @a HAM_SUCCESS upon success.
 * @return @a HAM_OUT_OF_MEMORY if memory allocation failed.
 */
HAM_EXPORT ham_status_t