contrib/bind-9.2.4rc7/lib/isc/include/isc/symtab.h

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