granicus.if.org Git - postgresql/blob - src/include/utils/guc.h

   1 /*--------------------------------------------------------------------
   2  * guc.h
   3  *
   4  * External declarations pertaining to backend/utils/misc/guc.c and
   5  * backend/utils/misc/guc-file.l
   6  *
   7  * Copyright (c) 2000-2019, PostgreSQL Global Development Group
   8  * Written by Peter Eisentraut <peter_e@gmx.net>.
   9  *
  10  * src/include/utils/guc.h
  11  *--------------------------------------------------------------------
  12  */
  13 #ifndef GUC_H
  14 #define GUC_H
  15
  16 #include "nodes/parsenodes.h"
  17 #include "tcop/dest.h"
  18 #include "utils/array.h"
  19
  20
  21 /* upper limit for GUC variables measured in kilobytes of memory */
  22 /* note that various places assume the byte size fits in a "long" variable */
  23 #if SIZEOF_SIZE_T > 4 && SIZEOF_LONG > 4
  24 #define MAX_KILOBYTES   INT_MAX
  25 #else
  26 #define MAX_KILOBYTES   (INT_MAX / 1024)
  27 #endif
  28
  29 /*
  30  * Automatic configuration file name for ALTER SYSTEM.
  31  * This file will be used to store values of configuration parameters
  32  * set by ALTER SYSTEM command.
  33  */
  34 #define PG_AUTOCONF_FILENAME            "postgresql.auto.conf"
  35
  36 /*
  37  * Certain options can only be set at certain times. The rules are
  38  * like this:
  39  *
  40  * INTERNAL options cannot be set by the user at all, but only through
  41  * internal processes ("server_version" is an example).  These are GUC
  42  * variables only so they can be shown by SHOW, etc.
  43  *
  44  * POSTMASTER options can only be set when the postmaster starts,
  45  * either from the configuration file or the command line.
  46  *
  47  * SIGHUP options can only be set at postmaster startup or by changing
  48  * the configuration file and sending the HUP signal to the postmaster
  49  * or a backend process. (Notice that the signal receipt will not be
  50  * evaluated immediately. The postmaster and the backend check it at a
  51  * certain point in their main loop. It's safer to wait than to read a
  52  * file asynchronously.)
  53  *
  54  * BACKEND and SU_BACKEND options can only be set at postmaster startup,
  55  * from the configuration file, or by client request in the connection
  56  * startup packet (e.g., from libpq's PGOPTIONS variable).  SU_BACKEND
  57  * options can be set from the startup packet only when the user is a
  58  * superuser.  Furthermore, an already-started backend will ignore changes
  59  * to such an option in the configuration file.  The idea is that these
  60  * options are fixed for a given backend once it's started, but they can
  61  * vary across backends.
  62  *
  63  * SUSET options can be set at postmaster startup, with the SIGHUP
  64  * mechanism, or from the startup packet or SQL if you're a superuser.
  65  *
  66  * USERSET options can be set by anyone any time.
  67  */
  68 typedef enum
  69 {
  70         PGC_INTERNAL,
  71         PGC_POSTMASTER,
  72         PGC_SIGHUP,
  73         PGC_SU_BACKEND,
  74         PGC_BACKEND,
  75         PGC_SUSET,
  76         PGC_USERSET
  77 } GucContext;
  78
  79 /*
  80  * The following type records the source of the current setting.  A
  81  * new setting can only take effect if the previous setting had the
  82  * same or lower level.  (E.g, changing the config file doesn't
  83  * override the postmaster command line.)  Tracking the source allows us
  84  * to process sources in any convenient order without affecting results.
  85  * Sources <= PGC_S_OVERRIDE will set the default used by RESET, as well
  86  * as the current value.  Note that source == PGC_S_OVERRIDE should be
  87  * used when setting a PGC_INTERNAL option.
  88  *
  89  * PGC_S_INTERACTIVE isn't actually a source value, but is the
  90  * dividing line between "interactive" and "non-interactive" sources for
  91  * error reporting purposes.
  92  *
  93  * PGC_S_TEST is used when testing values to be used later ("doit" will always
  94  * be false, so this never gets stored as the actual source of any value).
  95  * For example, ALTER DATABASE/ROLE tests proposed per-database or per-user
  96  * defaults this way, and CREATE FUNCTION tests proposed function SET clauses
  97  * this way.  This is an interactive case, but it needs its own source value
  98  * because some assign hooks need to make different validity checks in this
  99  * case.  In particular, references to nonexistent database objects generally
 100  * shouldn't throw hard errors in this case, at most NOTICEs, since the
 101  * objects might exist by the time the setting is used for real.
 102  *
 103  * NB: see GucSource_Names in guc.c if you change this.
 104  */
 105 typedef enum
 106 {
 107         PGC_S_DEFAULT,                          /* hard-wired default ("boot_val") */
 108         PGC_S_DYNAMIC_DEFAULT,          /* default computed during initialization */
 109         PGC_S_ENV_VAR,                          /* postmaster environment variable */
 110         PGC_S_FILE,                                     /* postgresql.conf */
 111         PGC_S_ARGV,                                     /* postmaster command line */
 112         PGC_S_GLOBAL,                           /* global in-database setting */
 113         PGC_S_DATABASE,                         /* per-database setting */
 114         PGC_S_USER,                                     /* per-user setting */
 115         PGC_S_DATABASE_USER,            /* per-user-and-database setting */
 116         PGC_S_CLIENT,                           /* from client connection request */
 117         PGC_S_OVERRIDE,                         /* special case to forcibly set default */
 118         PGC_S_INTERACTIVE,                      /* dividing line for error reporting */
 119         PGC_S_TEST,                                     /* test per-database or per-user setting */
 120         PGC_S_SESSION                           /* SET command */
 121 } GucSource;
 122
 123 /*
 124  * Parsing the configuration file(s) will return a list of name-value pairs
 125  * with source location info.  We also abuse this data structure to carry
 126  * error reports about the config files.  An entry reporting an error will
 127  * have errmsg != NULL, and might have NULLs for name, value, and/or filename.
 128  *
 129  * If "ignore" is true, don't attempt to apply the item (it might be an error
 130  * report, or an item we determined to be duplicate).  "applied" is set true
 131  * if we successfully applied, or could have applied, the setting.
 132  */
 133 typedef struct ConfigVariable
 134 {
 135         char       *name;
 136         char       *value;
 137         char       *errmsg;
 138         char       *filename;
 139         int                     sourceline;
 140         bool            ignore;
 141         bool            applied;
 142         struct ConfigVariable *next;
 143 } ConfigVariable;
 144
 145 extern bool ParseConfigFile(const char *config_file, bool strict,
 146                                                         const char *calling_file, int calling_lineno,
 147                                                         int depth, int elevel,
 148                                                         ConfigVariable **head_p, ConfigVariable **tail_p);
 149 extern bool ParseConfigFp(FILE *fp, const char *config_file,
 150                                                   int depth, int elevel,
 151                                                   ConfigVariable **head_p, ConfigVariable **tail_p);
 152 extern bool ParseConfigDirectory(const char *includedir,
 153                                                                  const char *calling_file, int calling_lineno,
 154                                                                  int depth, int elevel,
 155                                                                  ConfigVariable **head_p,
 156                                                                  ConfigVariable **tail_p);
 157 extern void FreeConfigVariables(ConfigVariable *list);
 158
 159 /*
 160  * The possible values of an enum variable are specified by an array of
 161  * name-value pairs.  The "hidden" flag means the value is accepted but
 162  * won't be displayed when guc.c is asked for a list of acceptable values.
 163  */
 164 struct config_enum_entry
 165 {
 166         const char *name;
 167         int                     val;
 168         bool            hidden;
 169 };
 170
 171 /*
 172  * Signatures for per-variable check/assign/show hook functions
 173  */
 174 typedef bool (*GucBoolCheckHook) (bool *newval, void **extra, GucSource source);
 175 typedef bool (*GucIntCheckHook) (int *newval, void **extra, GucSource source);
 176 typedef bool (*GucRealCheckHook) (double *newval, void **extra, GucSource source);
 177 typedef bool (*GucStringCheckHook) (char **newval, void **extra, GucSource source);
 178 typedef bool (*GucEnumCheckHook) (int *newval, void **extra, GucSource source);
 179
 180 typedef void (*GucBoolAssignHook) (bool newval, void *extra);
 181 typedef void (*GucIntAssignHook) (int newval, void *extra);
 182 typedef void (*GucRealAssignHook) (double newval, void *extra);
 183 typedef void (*GucStringAssignHook) (const char *newval, void *extra);
 184 typedef void (*GucEnumAssignHook) (int newval, void *extra);
 185
 186 typedef const char *(*GucShowHook) (void);
 187
 188 /*
 189  * Miscellaneous
 190  */
 191 typedef enum
 192 {
 193         /* Types of set_config_option actions */
 194         GUC_ACTION_SET,                         /* regular SET command */
 195         GUC_ACTION_LOCAL,                       /* SET LOCAL command */
 196         GUC_ACTION_SAVE                         /* function SET option, or temp assignment */
 197 } GucAction;
 198
 199 #define GUC_QUALIFIER_SEPARATOR '.'
 200
 201 /*
 202  * bit values in "flags" of a GUC variable
 203  */
 204 #define GUC_LIST_INPUT                  0x0001  /* input can be list format */
 205 #define GUC_LIST_QUOTE                  0x0002  /* double-quote list elements */
 206 #define GUC_NO_SHOW_ALL                 0x0004  /* exclude from SHOW ALL */
 207 #define GUC_NO_RESET_ALL                0x0008  /* exclude from RESET ALL */
 208 #define GUC_REPORT                              0x0010  /* auto-report changes to client */
 209 #define GUC_NOT_IN_SAMPLE               0x0020  /* not in postgresql.conf.sample */
 210 #define GUC_DISALLOW_IN_FILE    0x0040  /* can't set in postgresql.conf */
 211 #define GUC_CUSTOM_PLACEHOLDER  0x0080  /* placeholder for custom variable */
 212 #define GUC_SUPERUSER_ONLY              0x0100  /* show only to superusers */
 213 #define GUC_IS_NAME                             0x0200  /* limit string to NAMEDATALEN-1 */
 214 #define GUC_NOT_WHILE_SEC_REST  0x0400  /* can't set if security restricted */
 215 #define GUC_DISALLOW_IN_AUTO_FILE 0x0800        /* can't set in
 216                                                                                          * PG_AUTOCONF_FILENAME */
 217
 218 #define GUC_UNIT_KB                             0x1000  /* value is in kilobytes */
 219 #define GUC_UNIT_BLOCKS                 0x2000  /* value is in blocks */
 220 #define GUC_UNIT_XBLOCKS                0x3000  /* value is in xlog blocks */
 221 #define GUC_UNIT_MB                             0x4000  /* value is in megabytes */
 222 #define GUC_UNIT_BYTE                   0x8000  /* value is in bytes */
 223 #define GUC_UNIT_MEMORY                 0xF000  /* mask for size-related units */
 224
 225 #define GUC_UNIT_MS                        0x10000      /* value is in milliseconds */
 226 #define GUC_UNIT_S                         0x20000      /* value is in seconds */
 227 #define GUC_UNIT_MIN               0x30000      /* value is in minutes */
 228 #define GUC_UNIT_TIME              0xF0000      /* mask for time-related units */
 229
 230 #define GUC_EXPLAIN                       0x100000      /* include in explain */
 231
 232 #define GUC_UNIT                                (GUC_UNIT_MEMORY | GUC_UNIT_TIME)
 233
 234
 235 /* GUC vars that are actually declared in guc.c, rather than elsewhere */
 236 extern bool log_duration;
 237 extern bool Debug_print_plan;
 238 extern bool Debug_print_parse;
 239 extern bool Debug_print_rewritten;
 240 extern bool Debug_pretty_print;
 241
 242 extern bool log_parser_stats;
 243 extern bool log_planner_stats;
 244 extern bool log_executor_stats;
 245 extern bool log_statement_stats;
 246 extern bool log_btree_build_stats;
 247
 248 extern PGDLLIMPORT bool check_function_bodies;
 249 extern bool session_auth_is_superuser;
 250
 251 extern int      log_min_error_statement;
 252 extern PGDLLIMPORT int log_min_messages;
 253 extern PGDLLIMPORT int client_min_messages;
 254 extern int      log_min_duration_statement;
 255 extern int      log_temp_files;
 256 extern double log_xact_sample_rate;
 257
 258 extern int      temp_file_limit;
 259
 260 extern int      num_temp_buffers;
 261
 262 extern char *cluster_name;
 263 extern PGDLLIMPORT char *ConfigFileName;
 264 extern char *HbaFileName;
 265 extern char *IdentFileName;
 266 extern char *external_pid_file;
 267
 268 extern PGDLLIMPORT char *application_name;
 269
 270 extern int      tcp_keepalives_idle;
 271 extern int      tcp_keepalives_interval;
 272 extern int      tcp_keepalives_count;
 273 extern int      tcp_user_timeout;
 274
 275 #ifdef TRACE_SORT
 276 extern bool trace_sort;
 277 #endif
 278
 279 /*
 280  * Functions exported by guc.c
 281  */
 282 extern void SetConfigOption(const char *name, const char *value,
 283                                                         GucContext context, GucSource source);
 284
 285 extern void DefineCustomBoolVariable(const char *name,
 286                                                                          const char *short_desc,
 287                                                                          const char *long_desc,
 288                                                                          bool *valueAddr,
 289                                                                          bool bootValue,
 290                                                                          GucContext context,
 291                                                                          int flags,
 292                                                                          GucBoolCheckHook check_hook,
 293                                                                          GucBoolAssignHook assign_hook,
 294                                                                          GucShowHook show_hook);
 295
 296 extern void DefineCustomIntVariable(const char *name,
 297                                                                         const char *short_desc,
 298                                                                         const char *long_desc,
 299                                                                         int *valueAddr,
 300                                                                         int bootValue,
 301                                                                         int minValue,
 302                                                                         int maxValue,
 303                                                                         GucContext context,
 304                                                                         int flags,
 305                                                                         GucIntCheckHook check_hook,
 306                                                                         GucIntAssignHook assign_hook,
 307                                                                         GucShowHook show_hook);
 308
 309 extern void DefineCustomRealVariable(const char *name,
 310                                                                          const char *short_desc,
 311                                                                          const char *long_desc,
 312                                                                          double *valueAddr,
 313                                                                          double bootValue,
 314                                                                          double minValue,
 315                                                                          double maxValue,
 316                                                                          GucContext context,
 317                                                                          int flags,
 318                                                                          GucRealCheckHook check_hook,
 319                                                                          GucRealAssignHook assign_hook,
 320                                                                          GucShowHook show_hook);
 321
 322 extern void DefineCustomStringVariable(const char *name,
 323                                                                            const char *short_desc,
 324                                                                            const char *long_desc,
 325                                                                            char **valueAddr,
 326                                                                            const char *bootValue,
 327                                                                            GucContext context,
 328                                                                            int flags,
 329                                                                            GucStringCheckHook check_hook,
 330                                                                            GucStringAssignHook assign_hook,
 331                                                                            GucShowHook show_hook);
 332
 333 extern void DefineCustomEnumVariable(const char *name,
 334                                                                          const char *short_desc,
 335                                                                          const char *long_desc,
 336                                                                          int *valueAddr,
 337                                                                          int bootValue,
 338                                                                          const struct config_enum_entry *options,
 339                                                                          GucContext context,
 340                                                                          int flags,
 341                                                                          GucEnumCheckHook check_hook,
 342                                                                          GucEnumAssignHook assign_hook,
 343                                                                          GucShowHook show_hook);
 344
 345 extern void EmitWarningsOnPlaceholders(const char *className);
 346
 347 extern const char *GetConfigOption(const char *name, bool missing_ok,
 348                                                                    bool restrict_privileged);
 349 extern const char *GetConfigOptionResetString(const char *name);
 350 extern int      GetConfigOptionFlags(const char *name, bool missing_ok);
 351 extern void ProcessConfigFile(GucContext context);
 352 extern void InitializeGUCOptions(void);
 353 extern bool SelectConfigFiles(const char *userDoption, const char *progname);
 354 extern void ResetAllOptions(void);
 355 extern void AtStart_GUC(void);
 356 extern int      NewGUCNestLevel(void);
 357 extern void AtEOXact_GUC(bool isCommit, int nestLevel);
 358 extern void BeginReportingGUCOptions(void);
 359 extern void ParseLongOption(const char *string, char **name, char **value);
 360 extern bool parse_int(const char *value, int *result, int flags,
 361                                           const char **hintmsg);
 362 extern bool parse_real(const char *value, double *result, int flags,
 363                                            const char **hintmsg);
 364 extern int      set_config_option(const char *name, const char *value,
 365                                                           GucContext context, GucSource source,
 366                                                           GucAction action, bool changeVal, int elevel,
 367                                                           bool is_reload);
 368 extern void AlterSystemSetConfigFile(AlterSystemStmt *altersysstmt);
 369 extern char *GetConfigOptionByName(const char *name, const char **varname,
 370                                                                    bool missing_ok);
 371 extern void GetConfigOptionByNum(int varnum, const char **values, bool *noshow);
 372 extern int      GetNumConfigOptions(void);
 373
 374 extern void SetPGVariable(const char *name, List *args, bool is_local);
 375 extern void GetPGVariable(const char *name, DestReceiver *dest);
 376 extern TupleDesc GetPGVariableResultDesc(const char *name);
 377
 378 extern void ExecSetVariableStmt(VariableSetStmt *stmt, bool isTopLevel);
 379 extern char *ExtractSetVariableArgs(VariableSetStmt *stmt);
 380
 381 extern void ProcessGUCArray(ArrayType *array,
 382                                                         GucContext context, GucSource source, GucAction action);
 383 extern ArrayType *GUCArrayAdd(ArrayType *array, const char *name, const char *value);
 384 extern ArrayType *GUCArrayDelete(ArrayType *array, const char *name);
 385 extern ArrayType *GUCArrayReset(ArrayType *array);
 386
 387 #ifdef EXEC_BACKEND
 388 extern void write_nondefault_variables(GucContext context);
 389 extern void read_nondefault_variables(void);
 390 #endif
 391
 392 /* GUC serialization */
 393 extern Size EstimateGUCStateSpace(void);
 394 extern void SerializeGUCState(Size maxsize, char *start_address);
 395 extern void RestoreGUCState(void *gucstate);
 396
 397 /* Support for messages reported from GUC check hooks */
 398
 399 extern PGDLLIMPORT char *GUC_check_errmsg_string;
 400 extern PGDLLIMPORT char *GUC_check_errdetail_string;
 401 extern PGDLLIMPORT char *GUC_check_errhint_string;
 402
 403 extern void GUC_check_errcode(int sqlerrcode);
 404
 405 #define GUC_check_errmsg \
 406         pre_format_elog_string(errno, TEXTDOMAIN), \
 407         GUC_check_errmsg_string = format_elog_string
 408
 409 #define GUC_check_errdetail \
 410         pre_format_elog_string(errno, TEXTDOMAIN), \
 411         GUC_check_errdetail_string = format_elog_string
 412
 413 #define GUC_check_errhint \
 414         pre_format_elog_string(errno, TEXTDOMAIN), \
 415         GUC_check_errhint_string = format_elog_string
 416
 417
 418 /*
 419  * The following functions are not in guc.c, but are declared here to avoid
 420  * having to include guc.h in some widely used headers that it really doesn't
 421  * belong in.
 422  */
 423
 424 /* in commands/tablespace.c */
 425 extern bool check_default_tablespace(char **newval, void **extra, GucSource source);
 426 extern bool check_temp_tablespaces(char **newval, void **extra, GucSource source);
 427 extern void assign_temp_tablespaces(const char *newval, void *extra);
 428
 429 /* in catalog/namespace.c */
 430 extern bool check_search_path(char **newval, void **extra, GucSource source);
 431 extern void assign_search_path(const char *newval, void *extra);
 432
 433 /* in access/transam/xlog.c */
 434 extern bool check_wal_buffers(int *newval, void **extra, GucSource source);
 435 extern void assign_xlog_sync_method(int new_sync_method, void *extra);
 436
 437 #endif                                                  /* GUC_H */