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 */
68typedef 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 */
105typedef 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 */
133typedef 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
145extern 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);
149extern bool ParseConfigFp(FILE *fp, const char *config_file,
150 int depth, int elevel,
151 ConfigVariable **head_p, ConfigVariable **tail_p);
152extern 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);
157extern 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 */
164struct 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 */
174typedef bool (*GucBoolCheckHook) (bool *newval, void **extra, GucSource source);
175typedef bool (*GucIntCheckHook) (int *newval, void **extra, GucSource source);
176typedef bool (*GucRealCheckHook) (double *newval, void **extra, GucSource source);
177typedef bool (*GucStringCheckHook) (char **newval, void **extra, GucSource source);
178typedef bool (*GucEnumCheckHook) (int *newval, void **extra, GucSource source);
179
180typedef void (*GucBoolAssignHook) (bool newval, void *extra);
181typedef void (*GucIntAssignHook) (int newval, void *extra);
182typedef void (*GucRealAssignHook) (double newval, void *extra);
183typedef void (*GucStringAssignHook) (const char *newval, void *extra);
184typedef void (*GucEnumAssignHook) (int newval, void *extra);
185
186typedef const char *(*GucShowHook) (void);
187
188/*
189 * Miscellaneous
190 */
191typedef 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 */
236extern bool log_duration;
237extern bool Debug_print_plan;
238extern bool Debug_print_parse;
239extern bool Debug_print_rewritten;
240extern bool Debug_pretty_print;
241
242extern bool log_parser_stats;
243extern bool log_planner_stats;
244extern bool log_executor_stats;
245extern bool log_statement_stats;
246extern bool log_btree_build_stats;
247
248extern PGDLLIMPORT bool check_function_bodies;
249extern bool session_auth_is_superuser;
250
251extern int log_min_error_statement;
252extern PGDLLIMPORT int log_min_messages;
253extern PGDLLIMPORT int client_min_messages;
254extern int log_min_duration_statement;
255extern int log_temp_files;
256extern double log_xact_sample_rate;
257
258extern int temp_file_limit;
259
260extern int num_temp_buffers;
261
262extern char *cluster_name;
263extern PGDLLIMPORT char *ConfigFileName;
264extern char *HbaFileName;
265extern char *IdentFileName;
266extern char *external_pid_file;
267
268extern PGDLLIMPORT char *application_name;
269
270extern int tcp_keepalives_idle;
271extern int tcp_keepalives_interval;
272extern int tcp_keepalives_count;
273extern int tcp_user_timeout;
274
275#ifdef TRACE_SORT
276extern bool trace_sort;
277#endif
278
279/*
280 * Functions exported by guc.c
281 */
282extern void SetConfigOption(const char *name, const char *value,
283 GucContext context, GucSource source);
284
285extern 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
296extern 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
309extern 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
322extern 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
333extern 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
345extern void EmitWarningsOnPlaceholders(const char *className);
346
347extern const char *GetConfigOption(const char *name, bool missing_ok,
348 bool restrict_privileged);
349extern const char *GetConfigOptionResetString(const char *name);
350extern int GetConfigOptionFlags(const char *name, bool missing_ok);
351extern void ProcessConfigFile(GucContext context);
352extern void InitializeGUCOptions(void);
353extern bool SelectConfigFiles(const char *userDoption, const char *progname);
354extern void ResetAllOptions(void);
355extern void AtStart_GUC(void);
356extern int NewGUCNestLevel(void);
357extern void AtEOXact_GUC(bool isCommit, int nestLevel);
358extern void BeginReportingGUCOptions(void);
359extern void ParseLongOption(const char *string, char **name, char **value);
360extern bool parse_int(const char *value, int *result, int flags,
361 const char **hintmsg);
362extern bool parse_real(const char *value, double *result, int flags,
363 const char **hintmsg);
364extern 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);
368extern void AlterSystemSetConfigFile(AlterSystemStmt *setstmt);
369extern char *GetConfigOptionByName(const char *name, const char **varname,
370 bool missing_ok);
371extern void GetConfigOptionByNum(int varnum, const char **values, bool *noshow);
372extern int GetNumConfigOptions(void);
373
374extern void SetPGVariable(const char *name, List *args, bool is_local);
375extern void GetPGVariable(const char *name, DestReceiver *dest);
376extern TupleDesc GetPGVariableResultDesc(const char *name);
377
378extern void ExecSetVariableStmt(VariableSetStmt *stmt, bool isTopLevel);
379extern char *ExtractSetVariableArgs(VariableSetStmt *stmt);
380
381extern void ProcessGUCArray(ArrayType *array,
382 GucContext context, GucSource source, GucAction action);
383extern ArrayType *GUCArrayAdd(ArrayType *array, const char *name, const char *value);
384extern ArrayType *GUCArrayDelete(ArrayType *array, const char *name);
385extern ArrayType *GUCArrayReset(ArrayType *array);
386
387#ifdef EXEC_BACKEND
388extern void write_nondefault_variables(GucContext context);
389extern void read_nondefault_variables(void);
390#endif
391
392/* GUC serialization */
393extern Size EstimateGUCStateSpace(void);
394extern void SerializeGUCState(Size maxsize, char *start_address);
395extern void RestoreGUCState(void *gucstate);
396
397/* Support for messages reported from GUC check hooks */
398
399extern PGDLLIMPORT char *GUC_check_errmsg_string;
400extern PGDLLIMPORT char *GUC_check_errdetail_string;
401extern PGDLLIMPORT char *GUC_check_errhint_string;
402
403extern 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 */
425extern bool check_default_tablespace(char **newval, void **extra, GucSource source);
426extern bool check_temp_tablespaces(char **newval, void **extra, GucSource source);
427extern void assign_temp_tablespaces(const char *newval, void *extra);
428
429/* in catalog/namespace.c */
430extern bool check_search_path(char **newval, void **extra, GucSource source);
431extern void assign_search_path(const char *newval, void *extra);
432
433/* in access/transam/xlog.c */
434extern bool check_wal_buffers(int *newval, void **extra, GucSource source);
435extern void assign_xlog_sync_method(int new_sync_method, void *extra);
436
437#endif /* GUC_H */
438