/* WARNING: This file was generated by dkct. Changes you make here will be lost if dkct is run again! You should modify the original source and run dkct on it. Original source: dk4dbi.ctr */ /* Copyright (C) 2015-2017, Dirk Krause Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above opyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the author nor the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #ifndef DK4DBI_H_INCLUDED /** Avoid multiple inclusions. */ #define DK4DBI_H_INCLUDED 1 #line 10 "dk4dbi.ctr" /** @file dk4dbi.h Interface to databases. */ #ifndef DK4CONF_H_INCLUDED #include "dk4conf.h" #endif #ifndef DK4TYPES_H_INCLUDED #include "dk4types.h" #endif #if DK4_HAVE_UNISTD_H #ifndef UNISTD_H_INCLUDED #include #define UNISTD_H_INCLUDED 1 #endif #endif #if DK4_HAVE_SYS_TYPES_H #ifndef SYS_TYPES_H_INCLUDED #include #define SYS_TYPES_H_INCLUDED 1 #endif #endif #if DK4_HAVE_DB_H && (DK4_CHAR_SIZE == 1) #include #endif #if DK4_HAVE_NDBM_H && (DK4_CHAR_SIZE == 1) #if DK4_HAVE_FCNTL_H #ifndef FCNTL_H_INCLUDED #include #define FCNTL_H_INCLUDED 1 #endif #endif #ifndef NDBM_H_INCLUDED #include #define NDBM_H_INCLUDED 1 #endif #endif #ifndef DK4TYPES_H_INCLUDED #include "dk4types.h" #endif #ifndef DK4ERROR_H_INCLUDED #include "dk4error.h" #endif #ifndef DK4STO_H_INCLUDED #include "dk4sto.h" #endif /** Backend types. */ enum { /** No backend specified yet. */ DK4_DB_BE_UNKNOWN = -1 , /** In-memory database. */ DK4_DB_BE_MEMORY = 0 , /** Berkeley DB. */ DK4_DB_BE_BDB = 1 , /** NDBM. */ DK4_DB_BE_NDBM = 2 }; /** Options. */ enum { /** Reset key data before releasing memory. */ DK4_DB_OPT_RESET_KEY = 1 , /** Reset value data before releasing memory. */ DK4_DB_OPT_RESET_VALUE = 2 , }; /** Details for an in-memory database. */ typedef struct { dk4_sto_t *s; /**< Storage container. */ dk4_sto_it_t *i; /**< Storage iterator. */ } dk4_dbi_mem_t; #if DK4_HAVE_DB_H && (DK4_CHAR_SIZE == 1) /** Details for a Berkeley DB database. */ typedef struct { DB *db; /**< DB structure. */ } dk4_dbi_bdb_t; #endif #if DK4_HAVE_NDBM_H && (DK4_CHAR_SIZE == 1) /** Details for an NDBM database. */ typedef struct { DBM *dbm; /**< NDBM structure. */ } dk4_dbi_ndbm_t; #endif /** Details for one backend. */ typedef union { dk4_dbi_mem_t mem; /**< Details for in-memory database. */ #if DK4_HAVE_DB_H && (DK4_CHAR_SIZE == 1) dk4_dbi_bdb_t bdb; /**< Details for Berkeley DB. */ #endif #if DK4_HAVE_NDBM_H && (DK4_CHAR_SIZE == 1) dk4_dbi_ndbm_t ndbm; /**< Details for NDBM. */ #endif int dummy; /**< Just to have a second component. */ } dk4_dbi_det_t; /** Database structure. */ typedef struct { dk4_dbi_det_t dt; /**< Backend-specific details. */ dkChar *fn; /**< File name. */ size_t km; /**< Maximum key size. */ size_t vm; /**< Maximum value size. */ int tp; /**< Backend type. */ int op; /**< Options. */ int wa; /**< Flag: Write access. */ int uc; /**< Flag: Have unsynchronized changes. */ } dk4_dbi_t; /** Function to traverse a simple database. The function must check the kb, ks, vb and vs arguments for validity, they are passed as found by the backend functions (this means pointers may be NULL, sizes may be 0). @param Object modified during traversal, may be NULL. @param kb Key data. @param ks Key size. @param vb Value data. @param vs Value size. @return 1 on success, 0 on error (can continue), -1 on error (abort). */ typedef int dk4dbi_traverse_fct_t( void *obj, const void *kb, size_t ks, const void *vb, size_t vs ); #ifdef __cplusplus extern "C" { #endif /** Open database. @param fn File name. @param tp Backend type. @param wa Flag: Write access required. @param tr Flag: Truncate existing database (only in conjunction with wa). @param km Maximum key size (0 for unlimited). @param vm Maximum value size (0 for unlimited). The limits are used on all backends for writing, on in-memory databases also for reading. @param erp Error report, may be NULL. @return Pointer to new database structure on success, NULL on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if fn is NULL or tp contains an invalid type number, - DK4_E_NOT_SUPPORTED
if the database type is not supported, - DK4_E_MATH_OVERFLOW
on numeric overflow when calculating size, - DK4_E_MEMORY_ALLOCATION_FAILED
with mem.elsize and mem.nelem set if there is not enough memory available, - DK4_E_SYNTAX
if - the database file name does not refer to a regular file - or the file contents is not an in-memory database - or key/value sizes in the file are in conflict with restrictions, - DK4_E_SEC_CHECK
with failed check id in iDetails1 if access is denied by additional security checks, - DK4_E_MEMORY_ALLOCATION_FAILED
with mem.elsize and mem.nelem set if there is not enough memory available, - DK4_E_OPEN_READ_FAILED
if fopen() or fread() failed, - DK4_E_OPEN_WRITE_FAILED
if fopen() or fwrite() failed, - DK4_E_CLOSE_FAILED
with errno value in iDetails1 if fclose() failed. */ dk4_dbi_t * dk4dbi_open_with_type( const dkChar *fn, int tp, int wa, int tr, size_t km, size_t vm, dk4_er_t *erp ); /** Open database. @param fn Database type and file name. The database type is one from "mem", "bdb" or "ndbm". Database type and file name are separated by two colons "::". @param wa Flag: Write access required. @param tr Flag: Truncate existing database (only in conjunction with wa). @param km Maximum key size (0 for unlimited). @param vm Maximum value size (0 for unlimited). @param erp Error report, may be NULL. @return Pointer to new database structure on success, NULL on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if fn is NULL or tp contains an invalid type number, - DK4_E_NOT_SUPPORTED
if the database type is not supported, - DK4_E_MATH_OVERFLOW
on numeric overflow when calculating size, - DK4_E_MEMORY_ALLOCATION_FAILED
with mem.elsize and mem.nelem set if there is not enough memory available, - DK4_E_SYNTAX
if - the specification contains an invalid backend type - the database file name does not refer to a regular file - or the file contents is not an in-memory database - or key/value sizes in the file are in conflict with restrictions - or an invalid database type was specified, - DK4_E_SEC_CHECK
with failed check id in iDetails1 if access is denied by additional security checks, - DK4_E_MEMORY_ALLOCATION_FAILED
with mem.elsize and mem.nelem set if there is not enough memory available, - DK4_E_OPEN_READ_FAILED
if fopen() or fread() failed, - DK4_E_OPEN_WRITE_FAILED
if fopen() or fwrite() failed, - DK4_E_CLOSE_FAILED
with errno value in iDetails1 if fclose() failed. */ dk4_dbi_t * dk4dbi_open( const dkChar *fn, int wa, int tr, size_t km, size_t vm, dk4_er_t *erp ); /** Find file name part from combined type/name. @param filename Combined database type and file name. @return Valid pointer to file name part on success, NULL on error. */ const dkChar * dk4dbi_filename_part(const dkChar *filename); /** Close database, release resources. @param db Database to close. @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if db is NULL, - DK4_E_NOT_SUPPORTED
if db indicates an unsupported backend type, - DK4_E_SYNTAX
if the database file name does not refer to a regular file, - DK4_E_SEC_CHECK
with failed check id in iDetails1 if access is denied by additional security checks, - DK4_E_OPEN_WRITE_FAILED
with errno value in iDetails1 if fopen() or fwrite() failed, - DK4_E_CLOSE_FAILED
with errno value in iDetails1 if fclose() failed. */ int dk4dbi_close( dk4_dbi_t *db, dk4_er_t *erp ); /** Set or reset option. @param db Database. @param opt Option. @param val New value (1 or 0). @return 1 on success, 0 on error (unknown option). */ int dk4dbi_set_option( dk4_dbi_t *db, int opt, int val ); /** Retrieve maximum key size. @param db Database to query. @param erp Error report, may be NULL. @return Value on success (0 means unlimited), 0 with erp set on error. Error code: - DK4_E_INVALID_ARGUMENTS
if db is NULL. */ size_t dk4dbi_get_key_max( const dk4_dbi_t *db, dk4_er_t *erp ); /** Retrieve maximum value size. @param db Database to query. @param erp Error report, may be NULL. @return Value on success (0 means unlimited), 0 with erp set on error. Error code: - DK4_E_INVALID_ARGUMENTS
if db is NULL. */ size_t dk4dbi_get_val_max( const dk4_dbi_t *db, dk4_er_t *erp ); /** Set or overwrite record. @param db Database. @param kp Pointer to key data. @param ks Key data size (number of bytes). @param vp Pointer to value data. Use NULL to delete a record. @param vs Value data size (number of bytes). @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if db or kp is NULL or ks is 0, - DK4_E_SYNTAX
if the database was opened read-only or ks or vs exceeds a size limit, - DK4_E_NOT_SUPPORTED
if db indicates an unsupported backend, - DK4_E_NOT_FOUND
if no record to delete was found, - DK4_E_MEMORY_ALLOCATION_FAILED
with mem.elsize and mem.nelem set if there is not enough memory available, - DK4_E_WRITE_FAILED
if modification of the database failed. */ int dk4dbi_set( dk4_dbi_t *db, const void *kp, size_t ks, const void *vp, size_t vs, dk4_er_t *erp ); /** Synchronize changes to file if supported by backend. @param db Database. @param erp error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if db or a backend component is NULL, - DK4_E_NOT_SUPPORTED
if db indicates an unsupported backend, - DK4_E_SYNTAX
if the database file name does not refer to a regular file, - DK4_E_SEC_CHECK
with failed check id in iDetails1 if access is denied by additional security checks, - DK4_E_OPEN_WRITE_FAILED
with errno value in iDetails1 if fopen() or fwrite() failed, - DK4_E_WRITE_FAILED
if the backend failed to write to a database, - DK4_E_CLOSE_FAILED
with errno value in iDetails1 if fclose() failed. */ int dk4dbi_sync( dk4_dbi_t *db, dk4_er_t *erp ); /** Retrieve record. @param db Database. @param kp Pointer to key data. @param ks Key data size (number of bytes). @param vp Address of result buffer. @param vs Pointer to buffer size variable (in: size, out: used). @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if db, kp, vp or vs is NULL or ks is 0 or *vs is 0 or ks exceeds the key size limit, - DK4_E_NOT_SUPPORTED
if db indicates an unsupported backend, - DK4_E_NOT_FOUND
if no record was found for the key, - DK4_E_BUFFER_TOO_SMALL
if the destination buffer is too small. */ int dk4dbi_get( dk4_dbi_t *db, const void *kp, size_t ks, void *vp, size_t *vs, dk4_er_t *erp ); /** Delete one record. @param db Database. @param kp Pointer to key data. @param ks Key data size (number of bytes). @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if db or kp is NULL or ks is 0, - DK4_E_SYNTAX
if the database is opened read-only or ks exceeds the key size limit, - DK4_E_NOT_SUPPORTED
if db indicates an unsupported backend, - DK4_E_WRITE_FAILED
if modification of the database failed, - DK4_E_NOT_FOUND
if no record for the specified key is in the database. */ int dk4dbi_delete( dk4_dbi_t *db, const void *kp, size_t ks, dk4_er_t *erp ); /** Traverse database. @param db Database to traverse. @param obj Object to modify during traversal, may be NULL. @param fct Function to execute for all records. @return 1 on success, 0 on error (database traversed), -1 on error (traversal aborted). */ int dk4dbi_traverse( dk4_dbi_t *db, void *obj, dk4dbi_traverse_fct_t *fct ); /** Retrieve backend type. @param db Database to check. @return Backend type. */ int dk4dbi_get_type(const dk4_dbi_t *db); #if !DK4_ON_WINDOWS #if DK4_CHAR_SIZE == 1 #if DK4_HAVE_CHOWN && DK4_HAVE_CHMOD /** Change owner and mode for a database. @param db Database to modify. @param user New owner. @param group New owner group. @param mode New file permissions. @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if db is NULL, - DK4_E_NOT_SUPPORTED
if db indicates an unsupported backend, - DK4_E_SYSTEM
with errno value in iDetails1 if a chown or chmod system call failed, - DK4_E_MATH_OVERFLOW
if a mathematical overflow occured in size calculation, - DK4_E_BUFFER_TOO_SMALL
if the file name is too large for an internal buffer. */ int dk4dbi_change_owner_and_mode( dk4_dbi_t *db, uid_t user, gid_t group, mode_t mode, dk4_er_t *erp ); #endif /* if DK4_HAVE_CHOWN && DK4_HAVE_CHMOD */ #endif /* if DK4_CHAR_SIZE == 1 */ #endif /* if !DK4_ON_WINDOWS */ #ifdef __cplusplus } #endif #endif