1/*--------------------------------------------------------------------
4 * External declarations pertaining to Grand Unified Configuration.
6 * Copyright (c) 2000-2025, PostgreSQL Global Development Group
7 * Written by Peter Eisentraut <peter_e@gmx.net>.
9 * src/include/utils/guc.h
10 *--------------------------------------------------------------------
21 * Maximum for integer GUC variables that are measured in kilobytes of memory.
22 * This value is chosen to ensure that the corresponding number of bytes fits
23 * into a variable of type size_t or ssize_t. Be sure to compute the number
24 * of bytes like "guc_var * (Size) 1024" to avoid int-width overflow.
27#define MAX_KILOBYTES INT_MAX
29 #define MAX_KILOBYTES (INT_MAX / 1024)
33 * Automatic configuration file name for ALTER SYSTEM.
34 * This file will be used to store values of configuration parameters
35 * set by ALTER SYSTEM command.
37 #define PG_AUTOCONF_FILENAME "postgresql.auto.conf"
40 * Certain options can only be set at certain times. The rules are
43 * INTERNAL options cannot be set by the user at all, but only through
44 * internal processes ("server_version" is an example). These are GUC
45 * variables only so they can be shown by SHOW, etc.
47 * POSTMASTER options can only be set when the postmaster starts,
48 * either from the configuration file or the command line.
50 * SIGHUP options can only be set at postmaster startup or by changing
51 * the configuration file and sending the HUP signal to the postmaster
52 * or a backend process. (Notice that the signal receipt will not be
53 * evaluated immediately. The postmaster and the backend check it at a
54 * certain point in their main loop. It's safer to wait than to read a
55 * file asynchronously.)
57 * BACKEND and SU_BACKEND options can only be set at postmaster startup,
58 * from the configuration file, or by client request in the connection
59 * startup packet (e.g., from libpq's PGOPTIONS variable). SU_BACKEND
60 * options can be set from the startup packet only when the user is a
61 * superuser. Furthermore, an already-started backend will ignore changes
62 * to such an option in the configuration file. The idea is that these
63 * options are fixed for a given backend once it's started, but they can
64 * vary across backends.
66 * SUSET options can be set at postmaster startup, with the SIGHUP
67 * mechanism, or from the startup packet or SQL if you're a superuser.
69 * USERSET options can be set by anyone any time.
83 * The following type records the source of the current setting. A
84 * new setting can only take effect if the previous setting had the
85 * same or lower level. (E.g, changing the config file doesn't
86 * override the postmaster command line.) Tracking the source allows us
87 * to process sources in any convenient order without affecting results.
88 * Sources <= PGC_S_OVERRIDE will set the default used by RESET, as well
89 * as the current value.
91 * PGC_S_INTERACTIVE isn't actually a source value, but is the
92 * dividing line between "interactive" and "non-interactive" sources for
93 * error reporting purposes.
95 * PGC_S_TEST is used when testing values to be used later. For example,
96 * ALTER DATABASE/ROLE tests proposed per-database or per-user defaults this
97 * way, and CREATE FUNCTION tests proposed function SET clauses this way.
98 * This is an interactive case, but it needs its own source value because
99 * some assign hooks need to make different validity checks in this case.
100 * In particular, references to nonexistent database objects generally
101 * shouldn't throw hard errors in this case, at most NOTICEs, since the
102 * objects might exist by the time the setting is used for real.
104 * When setting the value of a non-compile-time-constant PGC_INTERNAL option,
105 * source == PGC_S_DYNAMIC_DEFAULT should typically be used so that the value
106 * will show as "default" in pg_settings. If there is a specific reason not
107 * to want that, use source == PGC_S_OVERRIDE.
109 * NB: see GucSource_Names in guc_tables.c if you change this.
130 * Parsing the configuration file(s) will return a list of name-value pairs
131 * with source location info. We also abuse this data structure to carry
132 * error reports about the config files. An entry reporting an error will
133 * have errmsg != NULL, and might have NULLs for name, value, and/or filename.
135 * If "ignore" is true, don't attempt to apply the item (it might be an error
136 * report, or an item we determined to be duplicate). "applied" is set true
137 * if we successfully applied, or could have applied, the setting.
154 const char *calling_file,
int calling_lineno,
155 int depth,
int elevel,
158 int depth,
int elevel,
161 const char *calling_file,
int calling_lineno,
162 int depth,
int elevel,
169 * The possible values of an enum variable are specified by an array of
170 * name-value pairs. The "hidden" flag means the value is accepted but
171 * won't be displayed when guc.c is asked for a list of acceptable values.
181 * Signatures for per-variable check/assign/show hook functions
195 typedef const char *(*GucShowHook) (void);
202 /* Types of set_config_option actions */
208 #define GUC_QUALIFIER_SEPARATOR '.'
211 * Bit values in "flags" of a GUC variable. Note that these don't appear
212 * on disk, so we can reassign their values freely.
214 #define GUC_LIST_INPUT 0x000001 /* input can be list format */
215 #define GUC_LIST_QUOTE 0x000002 /* double-quote list elements */
216 #define GUC_NO_SHOW_ALL 0x000004 /* exclude from SHOW ALL */
217 #define GUC_NO_RESET 0x000008 /* disallow RESET and SAVE */
218 #define GUC_NO_RESET_ALL 0x000010 /* exclude from RESET ALL */
219 #define GUC_EXPLAIN 0x000020 /* include in EXPLAIN */
220 #define GUC_REPORT 0x000040 /* auto-report changes to client */
221 #define GUC_NOT_IN_SAMPLE 0x000080 /* not in postgresql.conf.sample */
222 #define GUC_DISALLOW_IN_FILE 0x000100 /* can't set in postgresql.conf */
223 #define GUC_CUSTOM_PLACEHOLDER 0x000200 /* placeholder for custom variable */
224 #define GUC_SUPERUSER_ONLY 0x000400 /* show only to superusers */
225 #define GUC_IS_NAME 0x000800 /* limit string to NAMEDATALEN-1 */
226 #define GUC_NOT_WHILE_SEC_REST 0x001000 /* can't set if security restricted */
227 #define GUC_DISALLOW_IN_AUTO_FILE \
228 0x002000 /* can't set in PG_AUTOCONF_FILENAME */
229 #define GUC_RUNTIME_COMPUTED 0x004000 /* delay processing in 'postgres -C' */
230 #define GUC_ALLOW_IN_PARALLEL 0x008000 /* allow setting in parallel mode */
232 #define GUC_UNIT_KB 0x01000000 /* value is in kilobytes */
233 #define GUC_UNIT_BLOCKS 0x02000000 /* value is in blocks */
234 #define GUC_UNIT_XBLOCKS 0x03000000 /* value is in xlog blocks */
235 #define GUC_UNIT_MB 0x04000000 /* value is in megabytes */
236 #define GUC_UNIT_BYTE 0x05000000 /* value is in bytes */
237 #define GUC_UNIT_MEMORY 0x0F000000 /* mask for size-related units */
239 #define GUC_UNIT_MS 0x10000000 /* value is in milliseconds */
240 #define GUC_UNIT_S 0x20000000 /* value is in seconds */
241 #define GUC_UNIT_MIN 0x30000000 /* value is in minutes */
242 #define GUC_UNIT_TIME 0x70000000 /* mask for time-related units */
244 #define GUC_UNIT (GUC_UNIT_MEMORY | GUC_UNIT_TIME)
247/* GUC vars that are actually defined in guc_tables.c, rather than elsewhere */
254#ifdef DEBUG_NODE_TESTS_ENABLED
255extern PGDLLIMPORT bool Debug_copy_parse_plan_trees;
256extern PGDLLIMPORT bool Debug_write_read_parse_plan_trees;
257extern PGDLLIMPORT bool Debug_raw_expression_coverage_test;
260 * support for legacy compile-time settings
263#ifdef COPY_PARSE_PLAN_TREES
264#define DEFAULT_DEBUG_COPY_PARSE_PLAN_TREES true
266#define DEFAULT_DEBUG_COPY_PARSE_PLAN_TREES false
269#ifdef READ_WRITE_PARSE_PLAN_TREES
270#define DEFAULT_DEBUG_READ_WRITE_PARSE_PLAN_TREES true
272#define DEFAULT_DEBUG_READ_WRITE_PARSE_PLAN_TREES false
275#ifdef RAW_EXPRESSION_COVERAGE_TEST
276#define DEFAULT_DEBUG_RAW_EXPRESSION_COVERAGE_TEST true
278#define DEFAULT_DEBUG_RAW_EXPRESSION_COVERAGE_TEST false
281#endif /* DEBUG_NODE_TESTS_ENABLED */
328#ifdef DEBUG_BOUNDED_SORT
333 * Declarations for options for enum values
335 * For most parameters, these are defined statically inside guc_tables.c. But
336 * for some parameters, the definitions require symbols that are not easily
337 * available inside guc_tables.c, so they are instead defined in their home
338 * modules. For those, we keep the extern declarations here. (An alternative
339 * would be to put the extern declarations in the modules' header files, but
340 * that would then require including the definition of struct
341 * config_enum_entry into those header files.)
351 * Functions exported by guc.c
357 const char *short_desc,
358 const char *long_desc,
368 const char *short_desc,
369 const char *long_desc,
381 const char *short_desc,
382 const char *long_desc,
394 const char *short_desc,
395 const char *long_desc,
397 const char *bootValue,
405 const char *short_desc,
406 const char *long_desc,
418/* old name for MarkGUCPrefixReserved, for backwards compatibility: */
419 #define EmitWarningsOnPlaceholders(className) MarkGUCPrefixReserved(className)
422 bool restrict_privileged);
440 const char **hintmsg);
442 const char **hintmsg);
457 int elevel,
bool is_reload);
471extern void *
guc_malloc(
int elevel,
size_t size);
473extern char *
guc_strdup(
int elevel,
const char *src);
477extern void write_nondefault_variables(
GucContext context);
478extern void read_nondefault_variables(
void);
481/* GUC serialization */
486/* Functions exported by guc_funcs.c */
493/* Support for messages reported from GUC check hooks */
501 #define GUC_check_errmsg \
502 pre_format_elog_string(errno, TEXTDOMAIN), \
503 GUC_check_errmsg_string = format_elog_string
505 #define GUC_check_errdetail \
506 pre_format_elog_string(errno, TEXTDOMAIN), \
507 GUC_check_errdetail_string = format_elog_string
509 #define GUC_check_errhint \
510 pre_format_elog_string(errno, TEXTDOMAIN), \
511 GUC_check_errhint_string = format_elog_string
static Datum values[MAXATTR]
#define pg_attribute_nonnull(...)
void BeginReportingGUCOptions(void)
void GUC_check_errcode(int sqlerrcode)
void RestoreGUCState(void *gucstate)
PGDLLIMPORT const struct config_enum_entry archive_mode_options[]
PGDLLIMPORT const struct config_enum_entry recovery_target_action_options[]
bool(* GucBoolCheckHook)(bool *newval, void **extra, GucSource source)
int set_config_option_ext(const char *name, const char *value, GucContext context, GucSource source, Oid srole, GucAction action, bool changeVal, int elevel, bool is_reload)
PGDLLIMPORT bool AllowAlterSystem
PGDLLIMPORT int client_min_messages
bool parse_int(const char *value, int *result, int flags, const char **hintmsg)
void GetPGVariable(const char *name, DestReceiver *dest)
void FreeConfigVariables(ConfigVariable *list)
const char * get_config_unit_name(int flags)
PGDLLIMPORT bool trace_sort
char * GetConfigOptionByName(const char *name, const char **varname, bool missing_ok)
bool ParseConfigFp(FILE *fp, const char *config_file, int depth, int elevel, ConfigVariable **head_p, ConfigVariable **tail_p)
bool(* GucRealCheckHook)(double *newval, void **extra, GucSource source)
int NewGUCNestLevel(void)
PGDLLIMPORT int temp_file_limit
PGDLLIMPORT char * GUC_check_errhint_string
ArrayType * GUCArrayAdd(ArrayType *array, const char *name, const char *value)
void ProcessGUCArray(ArrayType *array, GucContext context, GucSource source, GucAction action)
PGDLLIMPORT char * application_name
void SetConfigOption(const char *name, const char *value, GucContext context, GucSource source)
void(* GucStringAssignHook)(const char *newval, void *extra)
PGDLLIMPORT const struct config_enum_entry dynamic_shared_memory_options[]
void void void void DefineCustomStringVariable(const char *name, const char *short_desc, const char *long_desc, char **valueAddr, const char *bootValue, GucContext context, int flags, GucStringCheckHook check_hook, GucStringAssignHook assign_hook, GucShowHook show_hook) pg_attribute_nonnull(1
PGDLLIMPORT int tcp_keepalives_idle
pg_nodiscard void * guc_realloc(int elevel, void *old, size_t size)
bool(* GucEnumCheckHook)(int *newval, void **extra, GucSource source)
PGDLLIMPORT bool Debug_print_parse
void void void DefineCustomRealVariable(const char *name, const char *short_desc, const char *long_desc, double *valueAddr, double bootValue, double minValue, double maxValue, GucContext context, int flags, GucRealCheckHook check_hook, GucRealAssignHook assign_hook, GucShowHook show_hook) pg_attribute_nonnull(1
void(* GucBoolAssignHook)(bool newval, void *extra)
PGDLLIMPORT char * GUC_check_errdetail_string
PGDLLIMPORT char * backtrace_functions
PGDLLIMPORT bool Debug_print_rewritten
void * guc_malloc(int elevel, size_t size)
bool parse_real(const char *value, double *result, int flags, const char **hintmsg)
void(* GucEnumAssignHook)(int newval, void *extra)
PGDLLIMPORT int tcp_user_timeout
const char * GetConfigOption(const char *name, bool missing_ok, bool restrict_privileged)
PGDLLIMPORT bool log_duration
void SerializeGUCState(Size maxsize, char *start_address)
char * ExtractSetVariableArgs(VariableSetStmt *stmt)
PGDLLIMPORT bool log_planner_stats
bool SelectConfigFiles(const char *userDoption, const char *progname)
PGDLLIMPORT char * HbaFileName
PGDLLIMPORT int log_parameter_max_length
config_handle * get_config_handle(const char *name)
PGDLLIMPORT char * external_pid_file
char * DeescapeQuotedString(const char *s)
void AlterSystemSetConfigFile(AlterSystemStmt *altersysstmt)
struct ConfigVariable ConfigVariable
PGDLLIMPORT int log_min_error_statement
Size EstimateGUCStateSpace(void)
void void DefineCustomIntVariable(const char *name, const char *short_desc, const char *long_desc, int *valueAddr, int bootValue, int minValue, int maxValue, GucContext context, int flags, GucIntCheckHook check_hook, GucIntAssignHook assign_hook, GucShowHook show_hook) pg_attribute_nonnull(1
PGDLLIMPORT bool log_btree_build_stats
TupleDesc GetPGVariableResultDesc(const char *name)
PGDLLIMPORT bool in_hot_standby_guc
PGDLLIMPORT char * ConfigFileName
PGDLLIMPORT int log_min_duration_statement
void ParseLongOption(const char *string, char **name, char **value)
void ResetAllOptions(void)
PGDLLIMPORT bool Debug_print_raw_parse
const char * GetConfigOptionResetString(const char *name)
void SetPGVariable(const char *name, List *args, bool is_local)
PGDLLIMPORT bool current_role_is_superuser
PGDLLIMPORT char * IdentFileName
bool(* GucStringCheckHook)(char **newval, void **extra, GucSource source)
PGDLLIMPORT const struct config_enum_entry wal_sync_method_options[]
PGDLLIMPORT bool log_executor_stats
PGDLLIMPORT bool Debug_print_plan
void void void void void void MarkGUCPrefixReserved(const char *className)
void InitializeGUCOptions(void)
bool ParseConfigFile(const char *config_file, bool strict, const char *calling_file, int calling_lineno, int depth, int elevel, ConfigVariable **head_p, ConfigVariable **tail_p)
bool ParseConfigDirectory(const char *includedir, const char *calling_file, int calling_lineno, int depth, int elevel, ConfigVariable **head_p, ConfigVariable **tail_p)
void(* GucIntAssignHook)(int newval, void *extra)
ArrayType * GUCArrayReset(ArrayType *array)
void(* GucRealAssignHook)(double newval, void *extra)
PGDLLIMPORT int log_min_duration_sample
PGDLLIMPORT char * role_string
void DefineCustomBoolVariable(const char *name, const char *short_desc, const char *long_desc, bool *valueAddr, bool bootValue, GucContext context, int flags, GucBoolCheckHook check_hook, GucBoolAssignHook assign_hook, GucShowHook show_hook) pg_attribute_nonnull(1
ArrayType * GUCArrayDelete(ArrayType *array, const char *name)
PGDLLIMPORT bool Debug_pretty_print
PGDLLIMPORT int tcp_keepalives_interval
PGDLLIMPORT int log_temp_files
void ExecSetVariableStmt(VariableSetStmt *stmt, bool isTopLevel)
PGDLLIMPORT int tcp_keepalives_count
bool(* GucIntCheckHook)(int *newval, void **extra, GucSource source)
void RestrictSearchPath(void)
PGDLLIMPORT bool check_function_bodies
int GetConfigOptionFlags(const char *name, bool missing_ok)
PGDLLIMPORT int num_temp_buffers
PGDLLIMPORT double log_xact_sample_rate
void check_GUC_name_for_parameter_acl(const char *name)
PGDLLIMPORT const struct config_enum_entry wal_level_options[]
char * convert_GUC_name_for_parameter_acl(const char *name)
int set_config_with_handle(const char *name, config_handle *handle, const char *value, GucContext context, GucSource source, Oid srole, GucAction action, bool changeVal, int elevel, bool is_reload)
PGDLLIMPORT const struct config_enum_entry io_method_options[]
PGDLLIMPORT bool log_statement_stats
void ProcessConfigFile(GucContext context)
void void void void void DefineCustomEnumVariable(const char *name, const char *short_desc, const char *long_desc, int *valueAddr, int bootValue, const struct config_enum_entry *options, GucContext context, int flags, GucEnumCheckHook check_hook, GucEnumAssignHook assign_hook, GucShowHook show_hook) pg_attribute_nonnull(1
PGDLLIMPORT bool log_parser_stats
void TransformGUCArray(ArrayType *array, List **names, List **values)
char * guc_strdup(int elevel, const char *src)
void ReportChangedGUCOptions(void)
PGDLLIMPORT int log_min_messages
void AtEOXact_GUC(bool isCommit, int nestLevel)
const char *(* GucShowHook)(void)
PGDLLIMPORT int log_parameter_max_length_on_error
PGDLLIMPORT char * event_source
int set_config_option(const char *name, const char *value, GucContext context, GucSource source, GucAction action, bool changeVal, int elevel, bool is_reload)
PGDLLIMPORT char * GUC_check_errmsg_string
PGDLLIMPORT double log_statement_sample_rate
PGDLLIMPORT char * cluster_name
static rewind_source * source
static char * config_file
static const char * userDoption
struct ConfigVariable * next