1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * Permission to use, copy, modify, and/or distribute this software for any 5 * purpose with or without fee is hereby granted, provided that the above 6 * copyright notice and this permission notice appear in all copies. 7 * 8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 14 * PERFORMANCE OF THIS SOFTWARE. 15 */ 16 17 /* $Id: symtab.h,v 1.4 2020/09/14 08:40:44 florian Exp $ */ 18 19 #ifndef ISC_SYMTAB_H 20 #define ISC_SYMTAB_H 1 21 22 /***** 23 ***** Module Info 24 *****/ 25 26 /*! \file isc/symtab.h 27 * \brief Provides a simple memory-based symbol table. 28 * 29 * Keys are C strings, and key comparisons are case-insensitive. A type may 30 * be specified when looking up, defining, or undefining. A type value of 31 * 0 means "match any type"; any other value will only match the given 32 * type. 33 * 34 * It's possible that a client will attempt to define a <key, type, value> 35 * tuple when a tuple with the given key and type already exists in the table. 36 * What to do in this case is specified by the client. Possible policies are: 37 * 38 *\li #isc_symexists_reject Disallow the define, returning #ISC_R_EXISTS 39 *\li #isc_symexists_replace Replace the old value with the new. The 40 * undefine action (if provided) will be called 41 * with the old <key, type, value> tuple. 42 *\li #isc_symexists_add Add the new tuple, leaving the old tuple in 43 * the table. Subsequent lookups will retrieve 44 * the most-recently-defined tuple. 45 * 46 * A lookup of a key using type 0 will return the most-recently defined 47 * symbol with that key. An undefine of a key using type 0 will undefine the 48 * most-recently defined symbol with that key. Trying to define a key with 49 * type 0 is illegal. 50 * 51 * The symbol table library does not make a copy the key field, so the 52 * caller must ensure that any key it passes to isc_symtab_define() will not 53 * change until it calls isc_symtab_destroy(). 54 * 55 * A user-specified action will be called (if provided) when a symbol is 56 * undefined. It can be used to free memory associated with keys and/or 57 * values. 58 * 59 * A symbol table is implemented as a hash table of lists; the size of the 60 * hash table is set by the 'size' parameter to isc_symtbl_create(). When 61 * the number of entries in the symbol table reaches three quarters of this 62 * value, the hash table is reallocated with size doubled, in order to 63 * optimize lookup performance. This has a negative effect on insertion 64 * performance, which can be mitigated by sizing the table appropriately 65 * when creating it. 66 * 67 * \li MP: 68 * The callers of this module must ensure any required synchronization. 69 * 70 * \li Reliability: 71 * No anticipated impact. 72 * 73 * \li Resources: 74 * TBS 75 * 76 * \li Security: 77 * No anticipated impact. 78 * 79 * \li Standards: 80 * None. 81 */ 82 83 /*** 84 *** Imports. 85 ***/ 86 87 #include <isc/types.h> 88 89 /* 90 *** Symbol Tables. 91 ***/ 92 /*% Symbol table value. */ 93 typedef union isc_symvalue { 94 void * as_pointer; 95 const void * as_cpointer; 96 int as_integer; 97 unsigned int as_uinteger; 98 } isc_symvalue_t; 99 100 typedef void (*isc_symtabaction_t)(char *key, unsigned int type, 101 isc_symvalue_t value, void *userarg); 102 /*% Symbol table exists. */ 103 typedef enum { 104 isc_symexists_reject = 0, /*%< Disallow the define */ 105 isc_symexists_replace = 1, /*%< Replace the old value with the new */ 106 isc_symexists_add = 2 /*%< Add the new tuple */ 107 } isc_symexists_t; 108 109 /*% Create a symbol table. */ 110 isc_result_t 111 isc_symtab_create(unsigned int size, 112 isc_symtabaction_t undefine_action, void *undefine_arg, 113 int case_sensitive, isc_symtab_t **symtabp); 114 115 /*% Destroy a symbol table. */ 116 void 117 isc_symtab_destroy(isc_symtab_t **symtabp); 118 119 /*% Lookup a symbol table. */ 120 isc_result_t 121 isc_symtab_lookup(isc_symtab_t *symtab, const char *key, unsigned int type, 122 isc_symvalue_t *value); 123 124 /*% Define a symbol table. */ 125 isc_result_t 126 isc_symtab_define(isc_symtab_t *symtab, const char *key, unsigned int type, 127 isc_symvalue_t value, isc_symexists_t exists_policy); 128 129 #endif /* ISC_SYMTAB_H */ 130