1/*-------------------------------------------------------------------------
4 * POSTGRES error reporting/logging definitions.
7 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
10 * src/include/utils/elog.h
12 *-------------------------------------------------------------------------
21/* We cannot include nodes.h yet, so forward-declare struct Node */
25/* Error level codes */
26 #define DEBUG5 10 /* Debugging messages, in categories of
27 * decreasing detail. */
31 #define DEBUG1 14 /* used by GUC debug_* variables */
32 #define LOG 15 /* Server operational messages; sent only to
33 * server log by default. */
34 #define LOG_SERVER_ONLY 16 /* Same as LOG for server reporting, but never
36 #define COMMERROR LOG_SERVER_ONLY /* Client communication problems; same as
37 * LOG for server reporting, but never
39 #define INFO 17 /* Messages specifically requested by user (eg
40 * VACUUM VERBOSE output); always sent to
41 * client regardless of client_min_messages,
42 * but by default not sent to server log. */
43#define NOTICE 18 /* Helpful messages to users about query
44 * operation; sent to client and not to server
46#define WARNING 19 /* Warnings. NOTICE is for expected messages
47 * like implicit sequence creation by SERIAL.
48 * WARNING is for unexpected messages. */
49#define PGWARNING 19 /* Must equal WARNING; see NOTE below. */
50#define WARNING_CLIENT_ONLY 20 /* Warnings to be sent to client as usual, but
51 * never to the server log. */
52#define ERROR 21 /* user error - abort transaction; return to
54 #define PGERROR 21 /* Must equal ERROR; see NOTE below. */
55#define FATAL 22 /* fatal error - abort process */
56 #define PANIC 23 /* take down the other backends with me */
59 * NOTE: the alternate names PGWARNING and PGERROR are useful for dealing
60 * with third-party headers that make other definitions of WARNING and/or
61 * ERROR. One can, for example, re-define ERROR as PGERROR after including
66/* macros for representing SQLSTATE strings compactly */
67#define PGSIXBIT(ch) (((ch) - '0') & 0x3F)
68#define PGUNSIXBIT(val) (((val) & 0x3F) + '0')
70#define MAKE_SQLSTATE(ch1,ch2,ch3,ch4,ch5) \
71 (PGSIXBIT(ch1) + (PGSIXBIT(ch2) << 6) + (PGSIXBIT(ch3) << 12) + \
72 (PGSIXBIT(ch4) << 18) + (PGSIXBIT(ch5) << 24))
74/* These macros depend on the fact that '0' becomes a zero in PGSIXBIT */
75#define ERRCODE_TO_CATEGORY(ec) ((ec) & ((1 << 12) - 1))
76#define ERRCODE_IS_CATEGORY(ec) (((ec) & ~((1 << 12) - 1)) == 0)
78/* SQLSTATE codes for errors are defined in a separate file */
79#include "utils/errcodes.h"
82 * Provide a way to prevent "errno" from being accidentally used inside an
83 * elog() or ereport() invocation. Since we know that some operating systems
84 * define errno as something involving a function call, we'll put a local
85 * variable of the same name as that function in the local scope to force a
86 * compile error. On platforms that don't define errno in that way, nothing
87 * happens, so we get no warning ... but we can live with that as long as it
88 * happens on some popular platforms.
90#if defined(errno) && defined(__linux__)
91#define pg_prevent_errno_in_scope() int __errno_location pg_attribute_unused()
92#elif defined(errno) && (defined(__darwin__) || defined(__FreeBSD__))
93#define pg_prevent_errno_in_scope() int __error pg_attribute_unused()
95#define pg_prevent_errno_in_scope()
100 * New-style error reporting API: to be used in this way:
102 * errcode(ERRCODE_UNDEFINED_CURSOR),
103 * errmsg("portal \"%s\" not found", stmt->portalname),
104 * ... other errxxx() fields as needed ...);
106 * The error level is required, and so is a primary error message (errmsg
107 * or errmsg_internal). All else is optional. errcode() defaults to
108 * ERRCODE_INTERNAL_ERROR if elevel is ERROR or more, ERRCODE_WARNING
109 * if elevel is WARNING, or ERRCODE_SUCCESSFUL_COMPLETION if elevel is
112 * Before Postgres v12, extra parentheses were required around the
113 * list of auxiliary function calls; that's now optional.
115 * ereport_domain() allows a message domain to be specified, for modules that
116 * wish to use a different message catalog from the backend's. To avoid having
117 * one copy of the default text domain per .o file, we define it as NULL here
118 * and have errstart insert the default text domain. Modules can either use
119 * ereport_domain() directly, or preferably they can override the TEXTDOMAIN
122 * When pg_integer_constant_p is available and elevel >= ERROR we make
123 * a call to errstart_cold() instead of errstart(). This version of the
124 * function is marked with pg_attribute_cold which will coax supporting
125 * compilers into generating code which is more optimized towards non-ERROR
126 * cases. Because we use pg_integer_constant_p() in the condition,
127 * when elevel is not a compile-time constant, or if it is, but it's < ERROR,
128 * the compiler has no need to generate any code for this branch. It can
129 * simply call errstart() unconditionally.
131 * If elevel >= ERROR, the call will not return; we try to inform the compiler
132 * of that via pg_unreachable(). However, no useful optimization effect is
133 * obtained unless the compiler sees elevel as a compile-time constant, else
134 * we're just adding code bloat. So, if pg_integer_constant_p is
135 * available, use that to cause the second if() to vanish completely for
136 * non-constant cases. We avoid using a local variable because it's not
137 * necessary and prevents gcc from making the unreachability deduction at
141#ifdef HAVE_PG_INTEGER_CONSTANT_P
142#define ereport_domain(elevel, domain, ...) \
144 pg_prevent_errno_in_scope(); \
145 if (pg_integer_constant_p(elevel) && (elevel) >= ERROR ? \
146 errstart_cold(elevel, domain) : \
147 errstart(elevel, domain)) \
148 __VA_ARGS__, errfinish(__FILE__, __LINE__, __func__); \
149 if (pg_integer_constant_p(elevel) && (elevel) >= ERROR) \
152#else /* !HAVE_PG_INTEGER_CONSTANT_P */
153 #define ereport_domain(elevel, domain, ...) \
155 const int elevel_ = (elevel); \
156 pg_prevent_errno_in_scope(); \
157 if (errstart(elevel_, domain)) \
158 __VA_ARGS__, errfinish(__FILE__, __LINE__, __func__); \
159 if (elevel_ >= ERROR) \
162#endif /* HAVE_PG_INTEGER_CONSTANT_P */
164#define ereport(elevel, ...) \
165 ereport_domain(elevel, TEXTDOMAIN, __VA_ARGS__)
167 #define TEXTDOMAIN NULL
171extern bool errstart(
int elevel,
const char *domain);
183extern
int errmsg_plural(const
char *fmt_singular, const
char *fmt_plural,
192 const
char *fmt_plural,
195extern
int errdetail_plural(const
char *fmt_singular, const
char *fmt_plural,
201extern
int errhint_plural(const
char *fmt_singular, const
char *fmt_plural,
205 * errcontext() is typically called in error context callback functions, not
206 * within an ereport() invocation. The callback function can be in a different
207 * module than the ereport() call, so the message domain passed in errstart()
208 * is not usually the correct domain for translating the context message.
209 * set_errcontext_domain() first sets the domain to be used, and
210 * errcontext_msg() passes the actual message.
212#define errcontext set_errcontext_domain(TEXTDOMAIN), errcontext_msg
236 * Old-style error reporting API: to be used in this way:
237 * elog(ERROR, "portal \"%s\" not found", stmt->portalname);
240#define elog(elevel, ...) \
241 ereport(elevel, errmsg_internal(__VA_ARGS__))
245 * Support for reporting "soft" errors that don't require a full transaction
246 * abort to clean up. This is to be used in this way:
248 * errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
249 * errmsg("invalid input syntax for type %s: \"%s\"",
250 * "boolean", in_str),
251 * ... other errxxx() fields as needed ...);
253 * "context" is a node pointer or NULL, and the remaining auxiliary calls
254 * provide the same error details as in ereport(). If context is not a
255 * pointer to an ErrorSaveContext node, then errsave(context, ...)
256 * behaves identically to ereport(ERROR, ...). If context is a pointer
257 * to an ErrorSaveContext node, then the information provided by the
258 * auxiliary calls is stored in the context node and control returns
259 * normally. The caller of errsave() must then do any required cleanup
260 * and return control back to its caller. That caller must check the
261 * ErrorSaveContext node to see whether an error occurred before
262 * it can trust the function's result to be meaningful.
264 * errsave_domain() allows a message domain to be specified; it is
265 * precisely analogous to ereport_domain().
268#define errsave_domain(context, domain, ...) \
270 struct Node *context_ = (context); \
271 pg_prevent_errno_in_scope(); \
272 if (errsave_start(context_, domain)) \
273 __VA_ARGS__, errsave_finish(context_, __FILE__, __LINE__, __func__); \
276#define errsave(context, ...) \
277 errsave_domain(context, TEXTDOMAIN, __VA_ARGS__)
280 * "ereturn(context, dummy_value, ...);" is exactly the same as
281 * "errsave(context, ...); return dummy_value;". This saves a bit
282 * of typing in the common case where a function has no cleanup
283 * actions to take after reporting a soft error. "dummy_value"
284 * can be empty if the function returns void.
286#define ereturn_domain(context, dummy_value, domain, ...) \
288 errsave_domain(context, domain, __VA_ARGS__); \
289 return dummy_value; \
292#define ereturn(context, dummy_value, ...) \
293 ereturn_domain(context, dummy_value, TEXTDOMAIN, __VA_ARGS__)
301/* Support for constructing error strings separately from ereport() calls */
307/* Support for attaching context information to error reports */
320 * API for catching ereport(ERROR) exits. Use these macros like so:
324 * ... code that might throw ereport(ERROR) ...
328 * ... error recovery code ...
332 * (The braces are not actually necessary, but are recommended so that
333 * pgindent will indent the construct nicely.) The error recovery code
334 * can either do PG_RE_THROW to propagate the error outwards, or do a
335 * (sub)transaction abort. Failure to do so may leave the system in an
336 * inconsistent state for further processing.
338 * For the common case that the error recovery code and the cleanup in the
339 * normal code path are identical, the following can be used instead:
343 * ... code that might throw ereport(ERROR) ...
347 * ... cleanup code ...
351 * The cleanup code will be run in either case, and any error will be rethrown
354 * You cannot use both PG_CATCH() and PG_FINALLY() in the same
355 * PG_TRY()/PG_END_TRY() block.
357 * Note: while the system will correctly propagate any new ereport(ERROR)
358 * occurring in the recovery section, there is a small limit on the number
359 * of levels this will work for. It's best to keep the error recovery
360 * section simple enough that it can't generate any new errors, at least
361 * not before popping the error stack.
363 * Note: an ereport(FATAL) will not be caught by this construct; control will
364 * exit straight through proc_exit(). Therefore, do NOT put any cleanup
365 * of non-process-local resources into the error recovery section, at least
366 * not without taking thought for what will happen during ereport(FATAL).
367 * The PG_ENSURE_ERROR_CLEANUP macros provided by storage/ipc.h may be
368 * helpful in such cases.
370 * Note: if a local variable of the function containing PG_TRY is modified
371 * in the PG_TRY section and used in the PG_CATCH section, that variable
372 * must be declared "volatile" for POSIX compliance. This is not mere
373 * pedantry; we have seen bugs from compilers improperly optimizing code
374 * away when such a variable was not marked. Beware that gcc's -Wclobbered
375 * warnings are just about entirely useless for catching such oversights.
377 * Each of these macros accepts an optional argument which can be specified
378 * to apply a suffix to the variables declared within the macros. This suffix
379 * can be used to avoid the compiler emitting warnings about shadowed
380 * variables when compiling with -Wshadow in situations where nested PG_TRY()
381 * statements are required. The optional suffix may contain any character
382 * that's allowed in a variable name. The suffix, if specified, must be the
383 * same within each component macro of the given PG_TRY() statement.
388 sigjmp_buf *_save_exception_stack##__VA_ARGS__ = PG_exception_stack; \
389 ErrorContextCallback *_save_context_stack##__VA_ARGS__ = error_context_stack; \
390 sigjmp_buf _local_sigjmp_buf##__VA_ARGS__; \
391 bool _do_rethrow##__VA_ARGS__ = false; \
392 if (sigsetjmp(_local_sigjmp_buf##__VA_ARGS__, 0) == 0) \
394 PG_exception_stack = &_local_sigjmp_buf##__VA_ARGS__
396#define PG_CATCH(...) \
400 PG_exception_stack = _save_exception_stack##__VA_ARGS__; \
401 error_context_stack = _save_context_stack##__VA_ARGS__
403#define PG_FINALLY(...) \
406 _do_rethrow##__VA_ARGS__ = true; \
408 PG_exception_stack = _save_exception_stack##__VA_ARGS__; \
409 error_context_stack = _save_context_stack##__VA_ARGS__
411#define PG_END_TRY(...) \
413 if (_do_rethrow##__VA_ARGS__) \
415 PG_exception_stack = _save_exception_stack##__VA_ARGS__; \
416 error_context_stack = _save_context_stack##__VA_ARGS__; \
419 #define PG_RE_THROW() \
425 /* Stuff that error handlers might want to use */
428 * ErrorData holds the data accumulated during any one ereport() cycle.
429 * Any non-NULL pointers must point to palloc'd data.
430 * (The const pointers are an exception; we assume they point at non-freeable
438 bool hide_stmt;
/* true to prevent STATEMENT: inclusion */
439 bool hide_ctx;
/* true to prevent CONTEXT: inclusion */
440 const char *
filename;
/* __FILE__ of ereport() call */
441 int lineno;
/* __LINE__ of ereport() call */
442 const char *
funcname;
/* __func__ of ereport() call */
446 char *
message;
/* primary error message (translated) */
448 char *
detail_log;
/* detail error message for server log only */
449 char *
hint;
/* hint message */
452 const char *
message_id;
/* primary message's id (original string) */
458 int cursorpos;
/* cursor index into query string */
459 int internalpos;
/* cursor index into internalquery */
460 char *
internalquery;
/* text of internally-generated query */
463 /* context containing associated non-constant strings */
477/* Hook for intercepting messages before they are sent to the server log */
482/* GUC-configurable parameters */
498/* Log destination bitmap */
499#define LOG_DESTINATION_STDERR 1
500#define LOG_DESTINATION_SYSLOG 2
501#define LOG_DESTINATION_EVENTLOG 4
502#define LOG_DESTINATION_CSVLOG 8
503#define LOG_DESTINATION_JSONLOG 16
505/* Other exported functions */
512/* Common functions shared across destinations */
521/* Destination-specific functions */
526 * Write errors to stderr (or by equal means when stderr is
527 * not available). Used before ereport/elog can be used
528 * safely (memory context, GUC load etc)
#define pg_attribute_cold
int getinternalerrposition(void)
int int errhidestmt(bool hide_stmt)
PGDLLIMPORT int Log_error_verbosity
PGDLLIMPORT int Log_destination
struct ErrorData ErrorData
void(* emit_log_hook_type)(ErrorData *edata)
int errcode_for_socket_access(void)
bool errsave_start(struct Node *context, const char *domain)
int err_generic_string(int field, const char *str)
PGDLLIMPORT sigjmp_buf * PG_exception_stack
int int errdetail_internal(const char *fmt,...) pg_attribute_printf(1
void errsave_finish(struct Node *context, const char *filename, int lineno, const char *funcname)
int errhint(const char *fmt,...) pg_attribute_printf(1
int internalerrquery(const char *query)
int int int errhint_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n,...) pg_attribute_printf(1
int internalerrposition(int cursorpos)
bool check_log_of_query(ErrorData *edata)
bool errstart(int elevel, const char *domain)
void EmitErrorReport(void)
int errdetail(const char *fmt,...) pg_attribute_printf(1
char * GetErrorContextStack(void)
void FreeErrorData(ErrorData *edata)
const char * error_severity(int elevel)
int int int pg_attribute_printf(2, 4)
int errmsg(const char *fmt,...) pg_attribute_printf(1
int int errmsg_internal(const char *fmt,...) pg_attribute_printf(1
int errcode_for_file_access(void)
pg_noreturn void ReThrowError(ErrorData *edata)
void pre_format_elog_string(int errnumber, const char *domain)
int int int errmsg_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n,...) pg_attribute_printf(1
char * get_formatted_start_time(void)
ErrorData * CopyErrorData(void)
PGDLLIMPORT char * Log_destination_string
void FlushErrorState(void)
void write_stderr(const char *fmt,...) pg_attribute_printf(1
PGDLLIMPORT emit_log_hook_type emit_log_hook
int errcontext_msg(const char *fmt,...) pg_attribute_printf(1
void ThrowErrorData(ErrorData *edata)
bool message_level_is_interesting(int elevel)
void write_pipe_chunks(char *data, int len, int dest)
int errhidecontext(bool hide_ctx)
int int int errdetail_log(const char *fmt,...) pg_attribute_printf(1
PGDLLIMPORT char * Log_line_prefix
void write_csvlog(ErrorData *edata)
pg_attribute_cold bool errstart_cold(int elevel, const char *domain)
void write_jsonlog(ErrorData *edata)
const char * get_backend_type_for_log(void)
int errcode(int sqlerrcode)
pg_noreturn void pg_re_throw(void)
PGDLLIMPORT bool syslog_split_messages
PGDLLIMPORT ErrorContextCallback * error_context_stack
PGDLLIMPORT bool syslog_sequence_numbers
char struct ErrorContextCallback ErrorContextCallback
char * format_elog_string(const char *fmt,...) pg_attribute_printf(1
void log_status_format(StringInfo buf, const char *format, ErrorData *edata)
char * get_formatted_log_time(void)
bool in_error_recursion_trouble(void)
void errfinish(const char *filename, int lineno, const char *funcname)
int errposition(int cursorpos)
char * unpack_sql_state(int sql_state)
int int int int errdetail_log_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n,...) pg_attribute_printf(1
int set_errcontext_domain(const char *domain)
void reset_formatted_start_time(void)
int errdetail_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n,...) pg_attribute_printf(1
int int errhint_internal(const char *fmt,...) pg_attribute_printf(1
struct ErrorContextCallback * previous
struct MemoryContextData * assoc_context
const char * context_domain
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)