1 /* $NetBSD: symtab.h,v 1.8 2025/01/26 16:25:44 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * SPDX-License-Identifier: MPL-2.0 AND ISC 7 * 8 * This Source Code Form is subject to the terms of the Mozilla Public 9 * License, v. 2.0. If a copy of the MPL was not distributed with this 10 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11 * 12 * See the COPYRIGHT file distributed with this work for additional 13 * information regarding copyright ownership. 14 */ 15 16 /* 17 * Copyright (C) 2001 Nominum, Inc. 18 * 19 * Permission to use, copy, modify, and/or distribute this software for any 20 * purpose with or without fee is hereby granted, provided that the above 21 * copyright notice and this permission notice appear in all copies. 22 * 23 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC AND NOMINUM DISCLAIMS ALL 24 * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES 25 * OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY 26 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 27 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 28 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 29 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 30 */ 31 32 #pragma once 33 34 /***** 35 ***** Module Info 36 *****/ 37 38 /*! \file isccc/symtab.h 39 * \brief 40 * Provides a simple memory-based symbol table. 41 * 42 * Keys are C strings. A type may be specified when looking up, 43 * defining, or undefining. A type value of 0 means "match any type"; 44 * any other value will only match the given type. 45 * 46 * It's possible that a client will attempt to define a <key, type, 47 * value> tuple when a tuple with the given key and type already 48 * exists in the table. What to do in this case is specified by the 49 * client. Possible policies are: 50 * 51 *\li isccc_symexists_reject Disallow the define, returning #ISC_R_EXISTS 52 *\li isccc_symexists_replace Replace the old value with the new. The 53 * undefine action (if provided) will be called 54 * with the old <key, type, value> tuple. 55 *\li isccc_symexists_add Add the new tuple, leaving the old tuple in 56 * the table. Subsequent lookups will retrieve 57 * the most-recently-defined tuple. 58 * 59 * A lookup of a key using type 0 will return the most-recently 60 * defined symbol with that key. An undefine of a key using type 0 61 * will undefine the most-recently defined symbol with that key. 62 * Trying to define a key with type 0 is illegal. 63 * 64 * The symbol table library does not make a copy the key field, so the 65 * caller must ensure that any key it passes to isccc_symtab_define() 66 * will not change until it calls isccc_symtab_undefine() or 67 * isccc_symtab_destroy(). 68 * 69 * A user-specified action will be called (if provided) when a symbol 70 * is undefined. It can be used to free memory associated with keys 71 * and/or values. 72 */ 73 74 /*** 75 *** Imports. 76 ***/ 77 78 #include <stdbool.h> 79 80 #include <isc/lang.h> 81 82 #include <isccc/types.h> 83 84 /*** 85 *** Symbol Tables. 86 ***/ 87 88 typedef union isccc_symvalue { 89 void *as_pointer; 90 int as_integer; 91 unsigned int as_uinteger; 92 } isccc_symvalue_t; 93 94 typedef void (*isccc_symtabundefaction_t)(char *key, unsigned int type, 95 isccc_symvalue_t value, 96 void *userarg); 97 98 typedef bool (*isccc_symtabforeachaction_t)(char *key, unsigned int type, 99 isccc_symvalue_t value, 100 void *userarg); 101 102 typedef enum { 103 isccc_symexists_reject = 0, 104 isccc_symexists_replace = 1, 105 isccc_symexists_add = 2 106 } isccc_symexists_t; 107 108 ISC_LANG_BEGINDECLS 109 110 isc_result_t 111 isccc_symtab_create(unsigned int size, 112 isccc_symtabundefaction_t undefine_action, 113 void *undefine_arg, bool case_sensitive, 114 isccc_symtab_t **symtabp); 115 116 void 117 isccc_symtab_destroy(isccc_symtab_t **symtabp); 118 119 isc_result_t 120 isccc_symtab_lookup(isccc_symtab_t *symtab, const char *key, unsigned int type, 121 isccc_symvalue_t *value); 122 123 isc_result_t 124 isccc_symtab_define(isccc_symtab_t *symtab, char *key, unsigned int type, 125 isccc_symvalue_t value, isccc_symexists_t exists_policy); 126 127 isc_result_t 128 isccc_symtab_undefine(isccc_symtab_t *symtab, const char *key, 129 unsigned int type); 130 131 void 132 isccc_symtab_foreach(isccc_symtab_t *symtab, isccc_symtabforeachaction_t action, 133 void *arg); 134 135 ISC_LANG_ENDDECLS 136