external/ibm-public/postfix/dist/src/util/dict.h

   1 /*      $NetBSD$        */
   2
   3 #ifndef _DICT_H_INCLUDED_
   4 #define _DICT_H_INCLUDED_
   5
   6 /*++
   7 /* NAME
   8 /*      dict 3h
   9 /* SUMMARY
  10 /*      dictionary manager
  11 /* SYNOPSIS
  12 /*      #include <dict.h>
  13 /* DESCRIPTION
  14 /* .nf
  15
  16  /*
  17   * System library.
  18   */
  19 #include <fcntl.h>
  20
  21  /*
  22   * Utility library.
  23   */
  24 #include <vstream.h>
  25 #include <argv.h>
  26 #include <vstring.h>
  27
  28  /*
  29   * Generic dictionary interface - in reality, a dictionary extends this
  30   * structure with private members to maintain internal state.
  31   */
  32 typedef struct DICT {
  33     char   *type;                       /* for diagnostics */
  34     char   *name;                       /* for diagnostics */
  35     int     flags;                      /* see below */
  36     const char *(*lookup) (struct DICT *, const char *);
  37     void    (*update) (struct DICT *, const char *, const char *);
  38     int     (*delete) (struct DICT *, const char *);
  39     int     (*sequence) (struct DICT *, int, const char **, const char **);
  40     void    (*close) (struct DICT *);
  41     int     lock_fd;                    /* for dict_update() lock */
  42     int     stat_fd;                    /* change detection */
  43     time_t  mtime;                      /* mod time at open */
  44     VSTRING *fold_buf;                  /* key folding buffer */
  45 } DICT;
  46
  47 extern DICT *dict_alloc(const char *, const char *, ssize_t);
  48 extern void dict_free(DICT *);
  49
  50 extern DICT *dict_debug(DICT *);
  51
  52 #define DICT_DEBUG(d) ((d)->flags & DICT_FLAG_DEBUG ? dict_debug(d) : (d))
  53
  54 #define DICT_FLAG_NONE          (0)
  55 #define DICT_FLAG_DUP_WARN      (1<<0)  /* if file, warn about dups */
  56 #define DICT_FLAG_DUP_IGNORE    (1<<1)  /* if file, ignore dups */
  57 #define DICT_FLAG_TRY0NULL      (1<<2)  /* do not append 0 to key/value */
  58 #define DICT_FLAG_TRY1NULL      (1<<3)  /* append 0 to key/value */
  59 #define DICT_FLAG_FIXED         (1<<4)  /* fixed key map */
  60 #define DICT_FLAG_PATTERN       (1<<5)  /* keys are patterns */
  61 #define DICT_FLAG_LOCK          (1<<6)  /* lock before access */
  62 #define DICT_FLAG_DUP_REPLACE   (1<<7)  /* if file, replace dups */
  63 #define DICT_FLAG_SYNC_UPDATE   (1<<8)  /* if file, sync updates */
  64 #define DICT_FLAG_DEBUG         (1<<9)  /* log access */
  65 /*#define DICT_FLAG_FOLD_KEY    (1<<10) /* lowercase the lookup key */
  66 #define DICT_FLAG_NO_REGSUB     (1<<11) /* disallow regexp substitution */
  67 #define DICT_FLAG_NO_PROXY      (1<<12) /* disallow proxy mapping */
  68 #define DICT_FLAG_NO_UNAUTH     (1<<13) /* disallow unauthenticated data */
  69 #define DICT_FLAG_FOLD_FIX      (1<<14) /* case-fold key with fixed-case map */
  70 #define DICT_FLAG_FOLD_MUL      (1<<15) /* case-fold key with multi-case map */
  71 #define DICT_FLAG_FOLD_ANY      (DICT_FLAG_FOLD_FIX | DICT_FLAG_FOLD_MUL)
  72
  73  /* IMPORTANT: Update the dict_mask[] table when the above changes */
  74
  75  /*
  76   * The subsets of flags that control how a map is used. These are relevant
  77   * mainly for proxymap support. Note: some categories overlap.
  78   *
  79   * DICT_FLAG_PARANOID - flags that forbid the use of insecure map types for
  80   * security-sensitive operations. These flags are specified by the caller,
  81   * and are checked by the map implementation itself upon open, lookup etc.
  82   * requests.
  83   *
  84   * DICT_FLAG_IMPL_MASK - flags that specify properties of the lookup table
  85   * implementation. These flags are set by the map implementation itself.
  86   *
  87   * DICT_FLAG_INST_MASK - flags that control how a specific table instance is
  88   * opened or used. The caller specifies these flags, and the caller may not
  89   * change them between open, lookup, etc. requests (although the map itself
  90   * may make changes to some of these flags).
  91   *
  92   * DICT_FLAG_NP_INST_MASK - ditto, but without the paranoia flags.
  93   *
  94   * DICT_FLAG_RQST_MASK - flags that the caller specifies, and that the caller
  95   * may change between open, lookup etc. requests.
  96   */
  97 #define DICT_FLAG_PARANOID \
  98         (DICT_FLAG_NO_REGSUB | DICT_FLAG_NO_PROXY | DICT_FLAG_NO_UNAUTH)
  99 #define DICT_FLAG_IMPL_MASK     (DICT_FLAG_FIXED | DICT_FLAG_PATTERN)
 100 #define DICT_FLAG_RQST_MASK     (DICT_FLAG_FOLD_ANY | DICT_FLAG_LOCK | \
 101                                 DICT_FLAG_DUP_REPLACE | DICT_FLAG_DUP_WARN | \
 102                                 DICT_FLAG_SYNC_UPDATE)
 103 #define DICT_FLAG_NP_INST_MASK  ~(DICT_FLAG_IMPL_MASK | DICT_FLAG_RQST_MASK)
 104 #define DICT_FLAG_INST_MASK     (DICT_FLAG_NP_INST_MASK | DICT_FLAG_PARANOID)
 105
 106 extern int dict_unknown_allowed;
 107 extern int dict_errno;
 108
 109 #define DICT_ERR_NONE   0               /* no error */
 110 #define DICT_ERR_RETRY  1               /* soft error */
 111
 112  /*
 113   * Sequence function types.
 114   */
 115 #define DICT_SEQ_FUN_FIRST     0        /* set cursor to first record */
 116 #define DICT_SEQ_FUN_NEXT      1        /* set cursor to next record */
 117
 118  /*
 119   * Interface for dictionary types.
 120   */
 121 extern ARGV *dict_mapnames(void);
 122
 123  /*
 124   * High-level interface, with logical dictionary names.
 125   */
 126 extern void dict_register(const char *, DICT *);
 127 extern DICT *dict_handle(const char *);
 128 extern void dict_unregister(const char *);
 129 extern void dict_update(const char *, const char *, const char *);
 130 extern const char *dict_lookup(const char *, const char *);
 131 extern int dict_delete(const char *, const char *);
 132 extern int dict_sequence(const char *, const int, const char **, const char **);
 133 extern void dict_load_file(const char *, const char *);
 134 extern void dict_load_fp(const char *, VSTREAM *);
 135 extern const char *dict_eval(const char *, const char *, int);
 136
 137  /*
 138   * Low-level interface, with physical dictionary handles.
 139   */
 140 extern DICT *dict_open(const char *, int, int);
 141 extern DICT *dict_open3(const char *, const char *, int, int);
 142 extern void dict_open_register(const char *, DICT *(*) (const char *, int, int));
 143
 144 #define dict_get(dp, key)       ((const char *) (dp)->lookup((dp), (key)))
 145 #define dict_put(dp, key, val)  (dp)->update((dp), (key), (val))
 146 #define dict_del(dp, key)       (dp)->delete((dp), (key))
 147 #define dict_seq(dp, f, key, val) (dp)->sequence((dp), (f), (key), (val))
 148 #define dict_close(dp)          (dp)->close(dp)
 149 typedef void (*DICT_WALK_ACTION) (const char *, DICT *, char *);
 150 extern void dict_walk(DICT_WALK_ACTION, char *);
 151 extern int dict_changed(void);
 152 extern const char *dict_changed_name(void);
 153 extern const char *dict_flags_str(int);
 154
 155 /* LICENSE
 156 /* .ad
 157 /* .fi
 158 /*      The Secure Mailer license must be distributed with this software.
 159 /* AUTHOR(S)
 160 /*      Wietse Venema
 161 /*      IBM T.J. Watson Research
 162 /*      P.O. Box 704
 163 /*      Yorktown Heights, NY 10598, USA
 164 /*--*/
 165
 166 #endif