Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / isc / include / isc / symtab.h
1 /*
2  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
3  * Copyright (C) 1996-2001  Internet Software Consortium.
4  *
5  * Permission to use, copy, modify, and/or 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.24.128.2 2009/01/19 23:47:03 tbox Exp $ */
19
20 #ifndef ISC_SYMTAB_H
21 #define ISC_SYMTAB_H 1
22
23 /*****
24  ***** Module Info
25  *****/
26
27 /*! \file isc/symtab.h
28  * \brief Provides a simple memory-based symbol table.
29  *
30  * Keys are C strings, and key comparisons are case-insensitive.  A type may
31  * be specified when looking up, defining, or undefining.  A type value of
32  * 0 means "match any type"; any other value will only match the given
33  * type.
34  *
35  * It's possible that a client will attempt to define a <key, type, value>
36  * tuple when a tuple with the given key and type already exists in the table.
37  * What to do in this case is specified by the client.  Possible policies are:
38  *
39  *\li   #isc_symexists_reject   Disallow the define, returning #ISC_R_EXISTS
40  *\li   #isc_symexists_replace  Replace the old value with the new.  The
41  *                              undefine action (if provided) will be called
42  *                              with the old <key, type, value> tuple.
43  *\li   #isc_symexists_add      Add the new tuple, leaving the old tuple in
44  *                              the table.  Subsequent lookups will retrieve
45  *                              the most-recently-defined tuple.
46  *
47  * A lookup of a key using type 0 will return the most-recently defined
48  * symbol with that key.  An undefine of a key using type 0 will undefine the
49  * most-recently defined symbol with that key.  Trying to define a key with
50  * type 0 is illegal.
51  *
52  * The symbol table library does not make a copy the key field, so the
53  * caller must ensure that any key it passes to isc_symtab_define() will not
54  * change until it calls isc_symtab_undefine() or isc_symtab_destroy().
55  *
56  * A user-specified action will be called (if provided) when a symbol is
57  * undefined.  It can be used to free memory associated with keys and/or
58  * values.
59  *
60  * \li MP:
61  *      The callers of this module must ensure any required synchronization.
62  *
63  * \li Reliability:
64  *      No anticipated impact.
65  *
66  * \li Resources:
67  *      TBS
68  *
69  * \li Security:
70  *      No anticipated impact.
71  *
72  * \li Standards:
73  *      None.
74  */
75
76 /***
77  *** Imports.
78  ***/
79
80 #include <isc/lang.h>
81 #include <isc/types.h>
82
83 /*
84  *** Symbol Tables.
85  ***/
86 /*% Symbol table value. */
87 typedef union isc_symvalue {
88         void *                          as_pointer;
89         const void *                    as_cpointer;
90         int                             as_integer;
91         unsigned int                    as_uinteger;
92 } isc_symvalue_t;
93
94 typedef void (*isc_symtabaction_t)(char *key, unsigned int type,
95                                    isc_symvalue_t value, void *userarg);
96 /*% Symbol table exists. */
97 typedef enum {
98         isc_symexists_reject = 0,       /*%< Disallow the define */
99         isc_symexists_replace = 1,      /*%< Replace the old value with the new */
100         isc_symexists_add = 2           /*%< Add the new tuple */
101 } isc_symexists_t;
102
103 ISC_LANG_BEGINDECLS
104
105 /*% Create a symbol table. */
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 /*% Destroy a symbol table. */
112 void
113 isc_symtab_destroy(isc_symtab_t **symtabp);
114
115 /*% Lookup a symbol table. */
116 isc_result_t
117 isc_symtab_lookup(isc_symtab_t *symtab, const char *key, unsigned int type,
118                   isc_symvalue_t *value);
119
120 /*% Define a symbol table. */
121 isc_result_t
122 isc_symtab_define(isc_symtab_t *symtab, const char *key, unsigned int type,
123                   isc_symvalue_t value, isc_symexists_t exists_policy);
124
125 /*% Undefine a symbol table. */
126 isc_result_t
127 isc_symtab_undefine(isc_symtab_t *symtab, const char *key, unsigned int type);
128
129 ISC_LANG_ENDDECLS
130
131 #endif /* ISC_SYMTAB_H */