src/include/access/reloptions.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * reloptions.h
   4  *        Core support for relation options (pg_class.reloptions)
   5  *
   6  * Note: the functions dealing with text-array reloptions values declare
   7  * them as Datum, not ArrayType *, to avoid needing to include array.h
   8  * into a lot of low-level code.
   9  *
  10  *
  11  * Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group
  12  * Portions Copyright (c) 1994, Regents of the University of California
  13  *
  14  * $PostgreSQL$
  15  *
  16  *-------------------------------------------------------------------------
  17  */
  18 #ifndef RELOPTIONS_H
  19 #define RELOPTIONS_H
  20
  21 #include "access/htup.h"
  22 #include "nodes/pg_list.h"
  23
  24 /* types supported by reloptions */
  25 typedef enum relopt_type
  26 {
  27         RELOPT_TYPE_BOOL,
  28         RELOPT_TYPE_INT,
  29         RELOPT_TYPE_REAL,
  30         RELOPT_TYPE_STRING
  31 } relopt_type;
  32
  33 /* kinds supported by reloptions */
  34 typedef enum relopt_kind
  35 {
  36         RELOPT_KIND_HEAP = (1 << 0),
  37         RELOPT_KIND_TOAST = (1 << 1),
  38         RELOPT_KIND_BTREE = (1 << 2),
  39         RELOPT_KIND_HASH = (1 << 3),
  40         RELOPT_KIND_GIN = (1 << 4),
  41         RELOPT_KIND_GIST = (1 << 5),
  42         /* if you add a new kind, make sure you update "last_default" too */
  43         RELOPT_KIND_LAST_DEFAULT = RELOPT_KIND_GIST,
  44         /* some compilers treat enums as signed ints, so we can't use 1 << 31 */
  45         RELOPT_KIND_MAX = (1 << 30)
  46 } relopt_kind;
  47
  48 /* reloption namespaces allowed for heaps -- currently only TOAST */
  49 #define HEAP_RELOPT_NAMESPACES { "toast", NULL }
  50
  51 /* generic struct to hold shared data */
  52 typedef struct relopt_gen
  53 {
  54         const char *name;                       /* must be first (used as list termination
  55                                                                  * marker) */
  56         const char *desc;
  57         bits32          kinds;
  58         int                     namelen;
  59         relopt_type type;
  60 } relopt_gen;
  61
  62 /* holds a parsed value */
  63 typedef struct relopt_value
  64 {
  65         relopt_gen *gen;
  66         bool            isset;
  67         union
  68         {
  69                 bool            bool_val;
  70                 int                     int_val;
  71                 double          real_val;
  72                 char       *string_val; /* allocated separately */
  73         }                       values;
  74 } relopt_value;
  75
  76 /* reloptions records for specific variable types */
  77 typedef struct relopt_bool
  78 {
  79         relopt_gen      gen;
  80         bool            default_val;
  81 } relopt_bool;
  82
  83 typedef struct relopt_int
  84 {
  85         relopt_gen      gen;
  86         int                     default_val;
  87         int                     min;
  88         int                     max;
  89 } relopt_int;
  90
  91 typedef struct relopt_real
  92 {
  93         relopt_gen      gen;
  94         double          default_val;
  95         double          min;
  96         double          max;
  97 } relopt_real;
  98
  99 /* validation routines for strings */
 100 typedef void (*validate_string_relopt) (char *value);
 101
 102 typedef struct relopt_string
 103 {
 104         relopt_gen      gen;
 105         int                     default_len;
 106         bool            default_isnull;
 107         validate_string_relopt validate_cb;
 108         char            default_val[1]; /* variable length, zero-terminated */
 109 } relopt_string;
 110
 111 /* This is the table datatype for fillRelOptions */
 112 typedef struct
 113 {
 114         const char *optname;            /* option's name */
 115         relopt_type opttype;            /* option's datatype */
 116         int                     offset;                 /* offset of field in result struct */
 117 } relopt_parse_elt;
 118
 119
 120 /*
 121  * These macros exist for the convenience of amoptions writers (but consider
 122  * using fillRelOptions, which is a lot simpler).  Beware of multiple
 123  * evaluation of arguments!
 124  *
 125  * The last argument in the HANDLE_*_RELOPTION macros allows the caller to
 126  * determine whether the option was set (true), or its value acquired from
 127  * defaults (false); it can be passed as (char *) NULL if the caller does not
 128  * need this information.
 129  *
 130  * optname is the option name (a string), var is the variable
 131  * on which the value should be stored (e.g. StdRdOptions->fillfactor), and
 132  * option is a relopt_value pointer.
 133  *
 134  * The normal way to use this is to loop on the relopt_value array returned by
 135  * parseRelOptions:
 136  * for (i = 0; options[i].gen->name; i++)
 137  * {
 138  *              if (HAVE_RELOPTION("fillfactor", options[i])
 139  *              {
 140  *                      HANDLE_INT_RELOPTION("fillfactor", rdopts->fillfactor, options[i], &isset);
 141  *                      continue;
 142  *              }
 143  *              if (HAVE_RELOPTION("default_row_acl", options[i])
 144  *              {
 145  *                      ...
 146  *              }
 147  *              ...
 148  *              if (validate)
 149  *                      ereport(ERROR,
 150  *                                      (errmsg("unknown option")));
 151  *      }
 152  *
 153  *      Note that this is more or less the same that fillRelOptions does, so only
 154  *      use this if you need to do something non-standard within some option's
 155  *      code block.
 156  */
 157 #define HAVE_RELOPTION(optname, option) \
 158         (pg_strncasecmp(option.gen->name, optname, option.gen->namelen + 1) == 0)
 159
 160 #define HANDLE_INT_RELOPTION(optname, var, option, wasset)              \
 161         do {                                                                                                            \
 162                 if (option.isset)                                                                               \
 163                         var = option.values.int_val;                                            \
 164                 else                                                                                                    \
 165                         var = ((relopt_int *) option.gen)->default_val;         \
 166                 (wasset) != NULL ? *(wasset) = option.isset : (dummyret)NULL; \
 167         } while (0)
 168
 169 #define HANDLE_BOOL_RELOPTION(optname, var, option, wasset)                     \
 170         do {                                                                                                                    \
 171                 if (option.isset)                                                                               \
 172                         var = option.values.bool_val;                                           \
 173                 else                                                                                                    \
 174                         var = ((relopt_bool *) option.gen)->default_val;        \
 175                 (wasset) != NULL ? *(wasset) = option.isset : (dummyret) NULL; \
 176         } while (0)
 177
 178 #define HANDLE_REAL_RELOPTION(optname, var, option, wasset)             \
 179         do {                                                                                                            \
 180                 if (option.isset)                                                                               \
 181                         var = option.values.real_val;                                           \
 182                 else                                                                                                    \
 183                         var = ((relopt_real *) option.gen)->default_val;        \
 184                 (wasset) != NULL ? *(wasset) = option.isset : (dummyret) NULL; \
 185         } while (0)
 186
 187 /*
 188  * Note that this assumes that the variable is already allocated at the tail of
 189  * reloptions structure (StdRdOptions or equivalent).
 190  *
 191  * "base" is a pointer to the reloptions structure, and "offset" is an integer
 192  * variable that must be initialized to sizeof(reloptions structure).  This
 193  * struct must have been allocated with enough space to hold any string option
 194  * present, including terminating \0 for every option.  SET_VARSIZE() must be
 195  * called on the struct with this offset as the second argument, after all the
 196  * string options have been processed.
 197  */
 198 #define HANDLE_STRING_RELOPTION(optname, var, option, base, offset, wasset) \
 199         do {                                                                                                            \
 200                 relopt_string *optstring = (relopt_string *) option.gen;\
 201                 char *string_val;                                                                               \
 202                 if (option.isset)                                                                               \
 203                         string_val = option.values.string_val;                          \
 204                 else if (!optstring->default_isnull)                                    \
 205                         string_val = optstring->default_val;                            \
 206                 else                                                                                                    \
 207                         string_val = NULL;                                                                      \
 208                 (wasset) != NULL ? *(wasset) = option.isset : (dummyret) NULL; \
 209                 if (string_val == NULL)                                                                 \
 210                         var = 0;                                                                                        \
 211                 else                                                                                                    \
 212                 {                                                                                                               \
 213                         strcpy(((char *)(base)) + (offset), string_val);        \
 214                         var = (offset);                                                                         \
 215                         (offset) += strlen(string_val) + 1;                                     \
 216                 }                                                                                                               \
 217         } while (0)
 218
 219 /*
 220  * For use during amoptions: get the strlen of a string option
 221  * (either default or the user defined value)
 222  */
 223 #define GET_STRING_RELOPTION_LEN(option) \
 224         ((option).isset ? strlen((option).values.string_val) : \
 225          ((relopt_string *) (option).gen)->default_len)
 226
 227 /*
 228  * For use by code reading options already parsed: get a pointer to the string
 229  * value itself.  "optstruct" is the StdRdOption struct or equivalent, "member"
 230  * is the struct member corresponding to the string option
 231  */
 232 #define GET_STRING_RELOPTION(optstruct, member) \
 233         ((optstruct)->member == 0 ? NULL : \
 234          (char *)(optstruct) + (optstruct)->member)
 235
 236
 237 extern relopt_kind add_reloption_kind(void);
 238 extern void add_bool_reloption(bits32 kinds, char *name, char *desc,
 239                                    bool default_val);
 240 extern void add_int_reloption(bits32 kinds, char *name, char *desc,
 241                                   int default_val, int min_val, int max_val);
 242 extern void add_real_reloption(bits32 kinds, char *name, char *desc,
 243                                    double default_val, double min_val, double max_val);
 244 extern void add_string_reloption(bits32 kinds, char *name, char *desc,
 245                                          char *default_val, validate_string_relopt validator);
 246
 247 extern Datum transformRelOptions(Datum oldOptions, List *defList,
 248                                         char *namspace, char *validnsps[],
 249                                         bool ignoreOids, bool isReset);
 250 extern List *untransformRelOptions(Datum options);
 251 extern bytea *extractRelOptions(HeapTuple tuple, TupleDesc tupdesc,
 252                                   Oid amoptions);
 253 extern relopt_value *parseRelOptions(Datum options, bool validate,
 254                                 relopt_kind kind, int *numrelopts);
 255 extern void *allocateReloptStruct(Size base, relopt_value *options,
 256                                          int numoptions);
 257 extern void fillRelOptions(void *rdopts, Size basesize,
 258                            relopt_value *options, int numoptions,
 259                            bool validate,
 260                            const relopt_parse_elt *elems, int nelems);
 261
 262 extern bytea *default_reloptions(Datum reloptions, bool validate,
 263                                    relopt_kind kind);
 264 extern bytea *heap_reloptions(char relkind, Datum reloptions, bool validate);
 265 extern bytea *index_reloptions(RegProcedure amoptions, Datum reloptions,
 266                                  bool validate);
 267
 268 #endif   /* RELOPTIONS_H */