"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/isc/include/isc/symtab.h" (7 Sep 2020, 4325 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "symtab.h" see the Fossies "Dox" file reference documentation.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 
   13 #ifndef ISC_SYMTAB_H
   14 #define ISC_SYMTAB_H 1
   15 
   16 /*****
   17  ***** Module Info
   18  *****/
   19 
   20 /*! \file isc/symtab.h
   21  * \brief Provides a simple memory-based symbol table.
   22  *
   23  * Keys are C strings, and key comparisons are case-insensitive.  A type may
   24  * be specified when looking up, defining, or undefining.  A type value of
   25  * 0 means "match any type"; any other value will only match the given
   26  * type.
   27  *
   28  * It's possible that a client will attempt to define a <key, type, value>
   29  * tuple when a tuple with the given key and type already exists in the table.
   30  * What to do in this case is specified by the client.  Possible policies are:
   31  *
   32  *\li   #isc_symexists_reject   Disallow the define, returning #ISC_R_EXISTS
   33  *\li   #isc_symexists_replace  Replace the old value with the new.  The
   34  *              undefine action (if provided) will be called
   35  *              with the old <key, type, value> tuple.
   36  *\li   #isc_symexists_add  Add the new tuple, leaving the old tuple in
   37  *              the table.  Subsequent lookups will retrieve
   38  *              the most-recently-defined tuple.
   39  *
   40  * A lookup of a key using type 0 will return the most-recently defined
   41  * symbol with that key.  An undefine of a key using type 0 will undefine the
   42  * most-recently defined symbol with that key.  Trying to define a key with
   43  * type 0 is illegal.
   44  *
   45  * The symbol table library does not make a copy the key field, so the
   46  * caller must ensure that any key it passes to isc_symtab_define() will not
   47  * change until it calls isc_symtab_undefine() or isc_symtab_destroy().
   48  *
   49  * A user-specified action will be called (if provided) when a symbol is
   50  * undefined.  It can be used to free memory associated with keys and/or
   51  * values.
   52  *
   53  * A symbol table is implemented as a hash table of lists; the size of the
   54  * hash table is set by the 'size' parameter to isc_symtbl_create().  When
   55  * the number of entries in the symbol table reaches three quarters of this
   56  * value, the hash table is reallocated with size doubled, in order to
   57  * optimize lookup performance.  This has a negative effect on insertion
   58  * performance, which can be mitigated by sizing the table appropriately
   59  * when creating it.
   60  *
   61  * \li MP:
   62  *  The callers of this module must ensure any required synchronization.
   63  *
   64  * \li Reliability:
   65  *  No anticipated impact.
   66  *
   67  * \li Resources:
   68  *  TBS
   69  *
   70  * \li Security:
   71  *  No anticipated impact.
   72  *
   73  * \li Standards:
   74  *  None.
   75  */
   76 
   77 /***
   78  *** Imports.
   79  ***/
   80 
   81 #include <stdbool.h>
   82 
   83 #include <isc/lang.h>
   84 #include <isc/types.h>
   85 
   86 /*
   87  *** Symbol Tables.
   88  ***/
   89 /*% Symbol table value. */
   90 typedef union isc_symvalue {
   91     void *              as_pointer;
   92     const void *            as_cpointer;
   93     int             as_integer;
   94     unsigned int            as_uinteger;
   95 } isc_symvalue_t;
   96 
   97 typedef void (*isc_symtabaction_t)(char *key, unsigned int type,
   98                    isc_symvalue_t value, void *userarg);
   99 /*% Symbol table exists. */
  100 typedef enum {
  101     isc_symexists_reject = 0,   /*%< Disallow the define */
  102     isc_symexists_replace = 1,  /*%< Replace the old value with the new */
  103     isc_symexists_add = 2       /*%< Add the new tuple */
  104 } isc_symexists_t;
  105 
  106 ISC_LANG_BEGINDECLS
  107 
  108 /*% Create a symbol table. */
  109 isc_result_t
  110 isc_symtab_create(isc_mem_t *mctx, unsigned int size,
  111           isc_symtabaction_t undefine_action, void *undefine_arg,
  112           bool case_sensitive, isc_symtab_t **symtabp);
  113 
  114 /*% Destroy a symbol table. */
  115 void
  116 isc_symtab_destroy(isc_symtab_t **symtabp);
  117 
  118 /*% Lookup a symbol table. */
  119 isc_result_t
  120 isc_symtab_lookup(isc_symtab_t *symtab, const char *key, unsigned int type,
  121           isc_symvalue_t *value);
  122 
  123 /*% Define a symbol table. */
  124 isc_result_t
  125 isc_symtab_define(isc_symtab_t *symtab, const char *key, unsigned int type,
  126           isc_symvalue_t value, isc_symexists_t exists_policy);
  127 
  128 /*% Undefine a symbol table. */
  129 isc_result_t
  130 isc_symtab_undefine(isc_symtab_t *symtab, const char *key, unsigned int type);
  131 
  132 /*% Return the number of items in a symbol table. */
  133 unsigned int
  134 isc_symtab_count(isc_symtab_t *symtab);
  135 ISC_LANG_ENDDECLS
  136 
  137 #endif /* ISC_SYMTAB_H */