From 8daa83a594a2e98f39d764422bfbdbc62c9efd44 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 19:20:00 +0200 Subject: Adding upstream version 2:4.20.0+dfsg. Signed-off-by: Daniel Baumann --- lib/tdb/include/tdb.h | 1038 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1038 insertions(+) create mode 100644 lib/tdb/include/tdb.h (limited to 'lib/tdb/include') diff --git a/lib/tdb/include/tdb.h b/lib/tdb/include/tdb.h new file mode 100644 index 0000000..884171c --- /dev/null +++ b/lib/tdb/include/tdb.h @@ -0,0 +1,1038 @@ +#ifndef __TDB_H__ +#define __TDB_H__ + +/* + Unix SMB/CIFS implementation. + + trivial database library + + Copyright (C) Andrew Tridgell 1999-2004 + + ** NOTE! The following LGPL license applies to the tdb + ** library. This does NOT imply that all of Samba is released + ** under the LGPL + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 3 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, see . +*/ + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include + +/* for old gcc releases that don't have the feature test macro __has_attribute */ +#ifndef __has_attribute +#define __has_attribute(x) 0 +#endif + +#ifndef _PUBLIC_ +#if __has_attribute(visibility) +#define _PUBLIC_ __attribute__((visibility("default"))) +#else +#define _PUBLIC_ +#endif +#endif + +/** + * @defgroup tdb The tdb API + * + * tdb is a Trivial database. In concept, it is very much like GDBM, and BSD's + * DB except that it allows multiple simultaneous writers and uses locking + * internally to keep writers from trampling on each other. tdb is also + * extremely small. + * + * @section tdb_interface Interface + * + * The interface is very similar to gdbm except for the following: + * + *
    + *
  • different open interface. The tdb_open call is more similar to a + * traditional open()
    • + *
  • no tdbm_reorganise() function
    • + *
  • no tdbm_sync() function. No operations are cached in the library + * anyway
    • + *
  • added a tdb_traverse() function for traversing the whole database
    • + *
  • added transactions support
    • + *
+ * + * A general rule for using tdb is that the caller frees any returned TDB_DATA + * structures. Just call free(p.dptr) to free a TDB_DATA return value called p. + * This is the same as gdbm. + * + * @{ + */ + +/** Flags to tdb_store() */ +#define TDB_REPLACE 1 /** Unused */ +#define TDB_INSERT 2 /** Don't overwrite an existing entry */ +#define TDB_MODIFY 3 /** Don't create an existing entry */ + +/** Flags for tdb_open() */ +#define TDB_DEFAULT 0 /** just a readability place holder */ +#define TDB_CLEAR_IF_FIRST 1 /** If this is the first open, wipe the db */ +#define TDB_INTERNAL 2 /** Don't store on disk */ +#define TDB_NOLOCK 4 /** Don't do any locking */ +#define TDB_NOMMAP 8 /** Don't use mmap */ +#define TDB_CONVERT 16 /** Convert endian (internal use) */ +#define TDB_BIGENDIAN 32 /** Header is big-endian (internal use) */ +#define TDB_NOSYNC 64 /** Don't use synchronous transactions */ +#define TDB_SEQNUM 128 /** Maintain a sequence number */ +#define TDB_VOLATILE 256 /** Activate the per-hashchain freelist, default 5 */ +#define TDB_ALLOW_NESTING 512 /** Allow transactions to nest */ +#define TDB_DISALLOW_NESTING 1024 /** Disallow transactions to nest */ +#define TDB_INCOMPATIBLE_HASH 2048 /** Better hashing: can't be opened by tdb < 1.2.6. */ +#define TDB_MUTEX_LOCKING 4096 /** optimized locking using robust mutexes if supported, + only with tdb >= 1.3.0 and TDB_CLEAR_IF_FIRST + after checking tdb_runtime_check_for_robust_mutexes() */ + +/** The tdb error codes */ +enum TDB_ERROR {TDB_SUCCESS=0, TDB_ERR_CORRUPT, TDB_ERR_IO, TDB_ERR_LOCK, + TDB_ERR_OOM, TDB_ERR_EXISTS, TDB_ERR_NOLOCK, TDB_ERR_LOCK_TIMEOUT, + TDB_ERR_NOEXIST, TDB_ERR_EINVAL, TDB_ERR_RDONLY, + TDB_ERR_NESTING}; + +/** Debugging uses one of the following levels */ +enum tdb_debug_level {TDB_DEBUG_FATAL = 0, TDB_DEBUG_ERROR, + TDB_DEBUG_WARNING, TDB_DEBUG_TRACE}; + +/** The tdb data structure */ +typedef struct TDB_DATA { + unsigned char *dptr; + size_t dsize; +} TDB_DATA; + +#ifndef PRINTF_ATTRIBUTE +#if __has_attribute(format) || (__GNUC__ >= 3) +/** Use gcc attribute to check printf fns. a1 is the 1-based index of + * the parameter containing the format, and a2 the index of the first + * argument. Note that some gcc 2.x versions don't handle this + * properly **/ +#define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2))) +#else +#define PRINTF_ATTRIBUTE(a1, a2) +#endif +#endif + +/** This is the context structure that is returned from a db open. */ +typedef struct tdb_context TDB_CONTEXT; + +typedef int (*tdb_traverse_func)(struct tdb_context *, TDB_DATA, TDB_DATA, void *); +typedef void (*tdb_log_func)(struct tdb_context *, enum tdb_debug_level, const char *, ...) PRINTF_ATTRIBUTE(3, 4); +typedef unsigned int (*tdb_hash_func)(TDB_DATA *key); + +struct tdb_logging_context { + tdb_log_func log_fn; + void *log_private; +}; + +/** + * @brief Open the database and creating it if necessary. + * + * @param[in] name The name of the db to open. + * + * @param[in] hash_size The hash size is advisory, use zero for a default + * value. + * + * @param[in] tdb_flags The flags to use to open the db:\n\n + * TDB_CLEAR_IF_FIRST - Clear database if we are the + * only one with it open\n + * TDB_INTERNAL - Don't use a file, instead store the + * data in memory. The filename is + * ignored in this case.\n + * TDB_NOLOCK - Don't do any locking\n + * TDB_NOMMAP - Don't use mmap\n + * TDB_NOSYNC - Don't synchronise transactions to disk\n + * TDB_SEQNUM - Maintain a sequence number\n + * TDB_VOLATILE - activate the per-hashchain freelist, + * default 5.\n + * TDB_ALLOW_NESTING - Allow transactions to nest.\n + * TDB_DISALLOW_NESTING - Disallow transactions to nest.\n + * TDB_INCOMPATIBLE_HASH - Better hashing: can't be opened by tdb < 1.2.6.\n + * TDB_MUTEX_LOCKING - Optimized locking using robust mutexes if supported, + * can't be opened by tdb < 1.3.0. + * Only valid in combination with TDB_CLEAR_IF_FIRST + * after checking tdb_runtime_check_for_robust_mutexes()\n + * + * @param[in] open_flags Flags for the open(2) function. + * + * @param[in] mode The mode for the open(2) function. + * + * @return A tdb context structure, NULL on error. + */ +_PUBLIC_ struct tdb_context *tdb_open(const char *name, int hash_size, int tdb_flags, + int open_flags, mode_t mode); + +/** + * @brief Open the database and creating it if necessary. + * + * This is like tdb_open(), but allows you to pass an initial logging and + * hash function. Be careful when passing a hash function - all users of the + * database must use the same hash function or you will get data corruption. + * + * @param[in] name The name of the db to open. + * + * @param[in] hash_size The hash size is advisory, use zero for a default + * value. + * + * @param[in] tdb_flags The flags to use to open the db:\n\n + * TDB_CLEAR_IF_FIRST - Clear database if we are the + * only one with it open\n + * TDB_INTERNAL - Don't use a file, instead store the + * data in memory. The filename is + * ignored in this case.\n + * TDB_NOLOCK - Don't do any locking\n + * TDB_NOMMAP - Don't use mmap\n + * TDB_NOSYNC - Don't synchronise transactions to disk\n + * TDB_SEQNUM - Maintain a sequence number\n + * TDB_VOLATILE - activate the per-hashchain freelist, + * default 5.\n + * TDB_ALLOW_NESTING - Allow transactions to nest.\n + * TDB_DISALLOW_NESTING - Disallow transactions to nest.\n + * TDB_INCOMPATIBLE_HASH - Better hashing: can't be opened by tdb < 1.2.6.\n + * TDB_MUTEX_LOCKING - Optimized locking using robust mutexes if supported, + * can't be opened by tdb < 1.3.0. + * Only valid in combination with TDB_CLEAR_IF_FIRST + * after checking tdb_runtime_check_for_robust_mutexes()\n + * + * @param[in] open_flags Flags for the open(2) function. + * + * @param[in] mode The mode for the open(2) function. + * + * @param[in] log_ctx The logging function to use. + * + * @param[in] hash_fn The hash function you want to use. + * + * @return A tdb context structure, NULL on error. + * + * @see tdb_open() + */ +_PUBLIC_ struct tdb_context *tdb_open_ex(const char *name, int hash_size, int tdb_flags, + int open_flags, mode_t mode, + const struct tdb_logging_context *log_ctx, + tdb_hash_func hash_fn); + +/** + * @brief Set the maximum number of dead records per hash chain. + * + * @param[in] tdb The database handle to set the maximum. + * + * @param[in] max_dead The maximum number of dead records per hash chain. + */ +_PUBLIC_ void tdb_set_max_dead(struct tdb_context *tdb, int max_dead); + +/** + * @brief Reopen a tdb. + * + * This can be used after a fork to ensure that we have an independent seek + * pointer from our parent and to re-establish locks. + * + * @param[in] tdb The database to reopen. It will be free'd on error! + * + * @return 0 on success, -1 on error. + * + * @note Don't call tdb_error() after this function cause the tdb context will + * be freed on error. + */ +_PUBLIC_ int tdb_reopen(struct tdb_context *tdb); + +/** + * @brief Reopen all tdb's + * + * If the parent is longlived (ie. a parent daemon architecture), we know it + * will keep it's active lock on a tdb opened with CLEAR_IF_FIRST. Thus for + * child processes we don't have to add an active lock. This is essential to + * improve performance on systems that keep POSIX locks as a non-scalable data + * structure in the kernel. + * + * @param[in] parent_longlived Whether the parent is longlived or not. + * + * @return 0 on success, -1 on error. + */ +_PUBLIC_ int tdb_reopen_all(int parent_longlived); + +/** + * @brief Set a different tdb logging function. + * + * @param[in] tdb The tdb to set the logging function. + * + * @param[in] log_ctx The logging function to set. + */ +_PUBLIC_ void tdb_set_logging_function(struct tdb_context *tdb, const struct tdb_logging_context *log_ctx); + +/** + * @brief Get the tdb last error code. + * + * @param[in] tdb The tdb to get the error code from. + * + * @return A TDB_ERROR code. + * + * @see TDB_ERROR + */ +_PUBLIC_ enum TDB_ERROR tdb_error(struct tdb_context *tdb); + +/** + * @brief Get a error string for the last tdb error + * + * @param[in] tdb The tdb to get the error code from. + * + * @return An error string. + */ +_PUBLIC_ const char *tdb_errorstr(struct tdb_context *tdb); + +/** + * @brief Fetch an entry in the database given a key. + * + * The caller must free the resulting data. + * + * @param[in] tdb The tdb to fetch the key. + * + * @param[in] key The key to fetch. + * + * @return The key entry found in the database, NULL on error with + * TDB_ERROR set. + * + * @see tdb_error() + * @see tdb_errorstr() + */ +_PUBLIC_ TDB_DATA tdb_fetch(struct tdb_context *tdb, TDB_DATA key); + +/** + * @brief Hand a record to a parser function without allocating it. + * + * This function is meant as a fast tdb_fetch alternative for large records + * that are frequently read. The "key" and "data" arguments point directly + * into the tdb shared memory, they are not aligned at any boundary. + * + * @warning The parser is called while tdb holds a lock on the record. DO NOT + * call other tdb routines from within the parser. Also, for good performance + * you should make the parser fast to allow parallel operations. + * + * @param[in] tdb The tdb to parse the record. + * + * @param[in] key The key to parse. + * + * @param[in] parser The parser to use to parse the data. + * + * @param[in] private_data A private data pointer which is passed to the parser + * function. + * + * @return -1 if the record was not found. If the record was found, + * the return value of "parser" is passed up to the caller. + */ +_PUBLIC_ int tdb_parse_record(struct tdb_context *tdb, TDB_DATA key, + int (*parser)(TDB_DATA key, TDB_DATA data, + void *private_data), + void *private_data); + +/** + * @brief Delete an entry in the database given a key. + * + * @param[in] tdb The tdb to delete the key. + * + * @param[in] key The key to delete. + * + * @return 0 on success, -1 if the key doesn't exist. + */ +_PUBLIC_ int tdb_delete(struct tdb_context *tdb, TDB_DATA key); + +/** + * @brief Store an element in the database. + * + * This replaces any existing element with the same key. + * + * @param[in] tdb The tdb to store the entry. + * + * @param[in] key The key to use to store the entry. + * + * @param[in] dbuf The data to store under the key. + * + * @param[in] flag The flags to store the key:\n\n + * TDB_INSERT: Don't overwrite an existing entry.\n + * TDB_MODIFY: Don't create a new entry\n + * + * @return 0 on success, -1 on error with error code set. + * + * @see tdb_error() + * @see tdb_errorstr() + */ +_PUBLIC_ int tdb_store(struct tdb_context *tdb, TDB_DATA key, TDB_DATA dbuf, int flag); + + +/** + * @brief Store an element in the database. + * + * This replaces any existing element with the same key. + * + * @param[in] tdb The tdb to store the entry. + * + * @param[in] key The key to use to store the entry. + * + * @param[in] dbufs A vector of memory chunks to write + * + * @param[in] num_dbufs Length of the dbufs vector + * + * @param[in] flag The flags to store the key:\n\n + * TDB_INSERT: Don't overwrite an existing entry.\n + * TDB_MODIFY: Don't create a new entry\n + * + * @return 0 on success, -1 on error with error code set. + * + * @see tdb_error() + * @see tdb_errorstr() + */ +_PUBLIC_ int tdb_storev(struct tdb_context *tdb, TDB_DATA key, + const TDB_DATA *dbufs, int num_dbufs, int flag); + +/** + * @brief Append data to an entry. + * + * If the entry doesn't exist, it will create a new one. + * + * @param[in] tdb The database to use. + * + * @param[in] key The key to append the data. + * + * @param[in] new_dbuf The data to append to the key. + * + * @return 0 on success, -1 on error with error code set. + * + * @see tdb_error() + * @see tdb_errorstr() + */ +_PUBLIC_ int tdb_append(struct tdb_context *tdb, TDB_DATA key, TDB_DATA new_dbuf); + +/** + * @brief Close a database. + * + * @param[in] tdb The database to close. The context will be free'd. + * + * @return 0 for success, -1 on error. + * + * @note Don't call tdb_error() after this function cause the tdb context will + * be freed on error. + */ +_PUBLIC_ int tdb_close(struct tdb_context *tdb); + +/** + * @brief Find the first entry in the database and return its key. + * + * The caller must free the returned data. + * + * @param[in] tdb The database to use. + * + * @return The first entry of the database, an empty TDB_DATA entry + * if the database is empty. + */ +_PUBLIC_ TDB_DATA tdb_firstkey(struct tdb_context *tdb); + +/** + * @brief Find the next entry in the database, returning its key. + * + * The caller must free the returned data. + * + * @param[in] tdb The database to use. + * + * @param[in] key The key from which you want the next key. + * + * @return The next entry of the current key, an empty TDB_DATA + * entry if there is no entry. + */ +_PUBLIC_ TDB_DATA tdb_nextkey(struct tdb_context *tdb, TDB_DATA key); + +/** + * @brief Traverse the entire database. + * + * While traversing the function fn(tdb, key, data, state) is called on each + * element. If fn is NULL then it is not called. A non-zero return value from + * fn() indicates that the traversal should stop. Traversal callbacks may not + * start transactions. + * + * @warning The data buffer given to the callback fn does NOT meet the alignment + * restrictions malloc gives you. + * + * @param[in] tdb The database to traverse. + * + * @param[in] fn The function to call on each entry. + * + * @param[in] private_data The private data which should be passed to the + * traversing function. + * + * @return The record count traversed, -1 on error. + */ +_PUBLIC_ int tdb_traverse(struct tdb_context *tdb, tdb_traverse_func fn, void *private_data); + +/** + * @brief Traverse the entire database. + * + * While traversing the database the function fn(tdb, key, data, state) is + * called on each element, but marking the database read only during the + * traversal, so any write operations will fail. This allows tdb to use read + * locks, which increases the parallelism possible during the traversal. + * + * @param[in] tdb The database to traverse. + * + * @param[in] fn The function to call on each entry. + * + * @param[in] private_data The private data which should be passed to the + * traversing function. + * + * @return The record count traversed, -1 on error. + */ +_PUBLIC_ int tdb_traverse_read(struct tdb_context *tdb, tdb_traverse_func fn, void *private_data); + +/** + * @brief Traverse a single hash chain + * + * Traverse a single hash chain under a single lock operation. No + * database modification is possible in the callback. + * + * This exists for background cleanup of databases. In normal + * operations, traversing a complete database can be much too + * expensive. Databases can have many chains, which will all have to + * be looked at before tdb_traverse finishes. Also tdb_traverse does a + * lot of fcntl activity to protect against concurrent record deletes. + * + * With this you can walk a fraction of the whole tdb, collect the + * entries you want to prune, leave the traverse, and then modify or + * delete the records in a subsequent step. + * + * To walk the entire database, call this function tdb_hash_size() + * times, with 0<=chain