diff options
Diffstat (limited to 'support/dktools/dk4dbi.h')
| -rw-r--r-- | support/dktools/dk4dbi.h | 588 |
1 files changed, 588 insertions, 0 deletions
diff --git a/support/dktools/dk4dbi.h b/support/dktools/dk4dbi.h new file mode 100644 index 0000000000..2c1dd43d6a --- /dev/null +++ b/support/dktools/dk4dbi.h @@ -0,0 +1,588 @@ +/* + 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 <unistd.h> +#define UNISTD_H_INCLUDED 1 +#endif +#endif + +#if DK4_HAVE_SYS_TYPES_H +#ifndef SYS_TYPES_H_INCLUDED +#include <sys/types.h> +#define SYS_TYPES_H_INCLUDED 1 +#endif +#endif + +#if DK4_HAVE_DB_H && (DK4_CHAR_SIZE == 1) +#include <db.h> +#endif + +#if DK4_HAVE_NDBM_H && (DK4_CHAR_SIZE == 1) +#if DK4_HAVE_FCNTL_H +#ifndef FCNTL_H_INCLUDED +#include <fcntl.h> +#define FCNTL_H_INCLUDED 1 +#endif +#endif +#ifndef NDBM_H_INCLUDED +#include <ndbm.h> +#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<br> + if fn is NULL or tp contains an invalid type number, + - DK4_E_NOT_SUPPORTED<br> + if the database type is not supported, + - DK4_E_MATH_OVERFLOW<br> + on numeric overflow when calculating size, + - DK4_E_MEMORY_ALLOCATION_FAILED<br> + with mem.elsize and mem.nelem + set if there is not enough memory available, + - DK4_E_SYNTAX<br> + 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<br> + with failed check id in iDetails1 if access is denied by additional + security checks, + - DK4_E_MEMORY_ALLOCATION_FAILED<br> + with mem.elsize and mem.nelem + set if there is not enough memory available, + - DK4_E_OPEN_READ_FAILED<br> + if fopen() or fread() failed, + - DK4_E_OPEN_WRITE_FAILED<br> + if fopen() or fwrite() failed, + - DK4_E_CLOSE_FAILED<br> + 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<br> + if fn is NULL or tp contains an invalid type number, + - DK4_E_NOT_SUPPORTED<br> + if the database type is not supported, + - DK4_E_MATH_OVERFLOW<br> + on numeric overflow when calculating size, + - DK4_E_MEMORY_ALLOCATION_FAILED<br> + with mem.elsize and mem.nelem + set if there is not enough memory available, + - DK4_E_SYNTAX<br> + 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<br> + with failed check id in iDetails1 if access is denied by additional + security checks, + - DK4_E_MEMORY_ALLOCATION_FAILED<br> + with mem.elsize and mem.nelem + set if there is not enough memory available, + - DK4_E_OPEN_READ_FAILED<br> + if fopen() or fread() failed, + - DK4_E_OPEN_WRITE_FAILED<br> + if fopen() or fwrite() failed, + - DK4_E_CLOSE_FAILED<br> + 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<br> + if db is NULL, + - DK4_E_NOT_SUPPORTED<br> + if db indicates an unsupported backend type, + - DK4_E_SYNTAX<br> + if the database file name does not refer to a regular file, + - DK4_E_SEC_CHECK<br> + with failed check id in iDetails1 if access is denied by additional + security checks, + - DK4_E_OPEN_WRITE_FAILED<br> + with errno value in iDetails1 if fopen() or fwrite() failed, + - DK4_E_CLOSE_FAILED<br> + 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<br> + 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<br> + 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<br> + if db or kp is NULL or ks is 0, + - DK4_E_SYNTAX<br> + if the database was opened read-only or ks or vs + exceeds a size limit, + - DK4_E_NOT_SUPPORTED<br> + if db indicates an unsupported backend, + - DK4_E_NOT_FOUND<br> + if no record to delete was found, + - DK4_E_MEMORY_ALLOCATION_FAILED<br> + with mem.elsize and mem.nelem + set if there is not enough memory available, + - DK4_E_WRITE_FAILED<br> + 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<br> + if db or a backend component is NULL, + - DK4_E_NOT_SUPPORTED<br> + if db indicates an unsupported backend, + - DK4_E_SYNTAX<br> + if the database file name does not refer to a regular file, + - DK4_E_SEC_CHECK<br> + with failed check id in iDetails1 if access is denied by additional + security checks, + - DK4_E_OPEN_WRITE_FAILED<br> + with errno value in iDetails1 if fopen() or fwrite() failed, + - DK4_E_WRITE_FAILED<br> + if the backend failed to write to a database, + - DK4_E_CLOSE_FAILED<br> + 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<br> + 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<br> + if db indicates an unsupported backend, + - DK4_E_NOT_FOUND<br> + if no record was found for the key, + - DK4_E_BUFFER_TOO_SMALL<br> + 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<br> + if db or kp is NULL or ks is 0, + - DK4_E_SYNTAX<br> + if the database is opened read-only or ks exceeds the + key size limit, + - DK4_E_NOT_SUPPORTED<br> + if db indicates an unsupported backend, + - DK4_E_WRITE_FAILED<br> + if modification of the database failed, + - DK4_E_NOT_FOUND<br> + 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<br> + if db is NULL, + - DK4_E_NOT_SUPPORTED<br> + if db indicates an unsupported backend, + - DK4_E_SYSTEM<br> + with errno value in iDetails1 if a chown or chmod + system call failed, + - DK4_E_MATH_OVERFLOW<br> + if a mathematical overflow occured in size calculation, + - DK4_E_BUFFER_TOO_SMALL<br> + 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 |