PostgreSQL Source Code  git master
elog.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * elog.h
4  * POSTGRES error reporting/logging definitions.
5  *
6  *
7  * Portions Copyright (c) 1996-2021, PostgreSQL Global Development Group
8  * Portions Copyright (c) 1994, Regents of the University of California
9  *
10  * src/include/utils/elog.h
11  *
12  *-------------------------------------------------------------------------
13  */
14 #ifndef ELOG_H
15 #define ELOG_H
16 
17 #include <setjmp.h>
18 
19 /* Error level codes */
20 #define DEBUG5 10 /* Debugging messages, in categories of
21  * decreasing detail. */
22 #define DEBUG4 11
23 #define DEBUG3 12
24 #define DEBUG2 13
25 #define DEBUG1 14 /* used by GUC debug_* variables */
26 #define LOG 15 /* Server operational messages; sent only to
27  * server log by default. */
28 #define LOG_SERVER_ONLY 16 /* Same as LOG for server reporting, but never
29  * sent to client. */
30 #define COMMERROR LOG_SERVER_ONLY /* Client communication problems; same as
31  * LOG for server reporting, but never
32  * sent to client. */
33 #define INFO 17 /* Messages specifically requested by user (eg
34  * VACUUM VERBOSE output); always sent to
35  * client regardless of client_min_messages,
36  * but by default not sent to server log. */
37 #define NOTICE 18 /* Helpful messages to users about query
38  * operation; sent to client and not to server
39  * log by default. */
40 #define WARNING 19 /* Warnings. NOTICE is for expected messages
41  * like implicit sequence creation by SERIAL.
42  * WARNING is for unexpected messages. */
43 #define PGWARNING 19 /* Must equal WARNING; see NOTE below. */
44 #define WARNING_CLIENT_ONLY 20 /* Warnings to be sent to client as usual, but
45  * never to the server log. */
46 #define ERROR 21 /* user error - abort transaction; return to
47  * known state */
48 #define PGERROR 21 /* Must equal ERROR; see NOTE below. */
49 #define FATAL 22 /* fatal error - abort process */
50 #define PANIC 23 /* take down the other backends with me */
51 
52 /*
53  * NOTE: the alternate names PGWARNING and PGERROR are useful for dealing
54  * with third-party headers that make other definitions of WARNING and/or
55  * ERROR. One can, for example, re-define ERROR as PGERROR after including
56  * such a header.
57  */
58 
59 
60 /* macros for representing SQLSTATE strings compactly */
61 #define PGSIXBIT(ch) (((ch) - '0') & 0x3F)
62 #define PGUNSIXBIT(val) (((val) & 0x3F) + '0')
63 
64 #define MAKE_SQLSTATE(ch1,ch2,ch3,ch4,ch5) \
65  (PGSIXBIT(ch1) + (PGSIXBIT(ch2) << 6) + (PGSIXBIT(ch3) << 12) + \
66  (PGSIXBIT(ch4) << 18) + (PGSIXBIT(ch5) << 24))
67 
68 /* These macros depend on the fact that '0' becomes a zero in PGSIXBIT */
69 #define ERRCODE_TO_CATEGORY(ec) ((ec) & ((1 << 12) - 1))
70 #define ERRCODE_IS_CATEGORY(ec) (((ec) & ~((1 << 12) - 1)) == 0)
71 
72 /* SQLSTATE codes for errors are defined in a separate file */
73 #include "utils/errcodes.h"
74 
75 /*
76  * Provide a way to prevent "errno" from being accidentally used inside an
77  * elog() or ereport() invocation. Since we know that some operating systems
78  * define errno as something involving a function call, we'll put a local
79  * variable of the same name as that function in the local scope to force a
80  * compile error. On platforms that don't define errno in that way, nothing
81  * happens, so we get no warning ... but we can live with that as long as it
82  * happens on some popular platforms.
83  */
84 #if defined(errno) && defined(__linux__)
85 #define pg_prevent_errno_in_scope() int __errno_location pg_attribute_unused()
86 #elif defined(errno) && (defined(__darwin__) || defined(__freebsd__))
87 #define pg_prevent_errno_in_scope() int __error pg_attribute_unused()
88 #else
89 #define pg_prevent_errno_in_scope()
90 #endif
91 
92 
93 /*----------
94  * New-style error reporting API: to be used in this way:
95  * ereport(ERROR,
96  * errcode(ERRCODE_UNDEFINED_CURSOR),
97  * errmsg("portal \"%s\" not found", stmt->portalname),
98  * ... other errxxx() fields as needed ...);
99  *
100  * The error level is required, and so is a primary error message (errmsg
101  * or errmsg_internal). All else is optional. errcode() defaults to
102  * ERRCODE_INTERNAL_ERROR if elevel is ERROR or more, ERRCODE_WARNING
103  * if elevel is WARNING, or ERRCODE_SUCCESSFUL_COMPLETION if elevel is
104  * NOTICE or below.
105  *
106  * Before Postgres v12, extra parentheses were required around the
107  * list of auxiliary function calls; that's now optional.
108  *
109  * ereport_domain() allows a message domain to be specified, for modules that
110  * wish to use a different message catalog from the backend's. To avoid having
111  * one copy of the default text domain per .o file, we define it as NULL here
112  * and have errstart insert the default text domain. Modules can either use
113  * ereport_domain() directly, or preferably they can override the TEXTDOMAIN
114  * macro.
115  *
116  * When __builtin_constant_p is available and elevel >= ERROR we make a call
117  * to errstart_cold() instead of errstart(). This version of the function is
118  * marked with pg_attribute_cold which will coax supporting compilers into
119  * generating code which is more optimized towards non-ERROR cases. Because
120  * we use __builtin_constant_p() in the condition, when elevel is not a
121  * compile-time constant, or if it is, but it's < ERROR, the compiler has no
122  * need to generate any code for this branch. It can simply call errstart()
123  * unconditionally.
124  *
125  * If elevel >= ERROR, the call will not return; we try to inform the compiler
126  * of that via pg_unreachable(). However, no useful optimization effect is
127  * obtained unless the compiler sees elevel as a compile-time constant, else
128  * we're just adding code bloat. So, if __builtin_constant_p is available,
129  * use that to cause the second if() to vanish completely for non-constant
130  * cases. We avoid using a local variable because it's not necessary and
131  * prevents gcc from making the unreachability deduction at optlevel -O0.
132  *----------
133  */
134 #ifdef HAVE__BUILTIN_CONSTANT_P
135 #define ereport_domain(elevel, domain, ...) \
136  do { \
137  pg_prevent_errno_in_scope(); \
138  if (__builtin_constant_p(elevel) && (elevel) >= ERROR ? \
139  errstart_cold(elevel, domain) : \
140  errstart(elevel, domain)) \
141  __VA_ARGS__, errfinish(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
142  if (__builtin_constant_p(elevel) && (elevel) >= ERROR) \
143  pg_unreachable(); \
144  } while(0)
145 #else /* !HAVE__BUILTIN_CONSTANT_P */
146 #define ereport_domain(elevel, domain, ...) \
147  do { \
148  const int elevel_ = (elevel); \
149  pg_prevent_errno_in_scope(); \
150  if (errstart(elevel_, domain)) \
151  __VA_ARGS__, errfinish(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
152  if (elevel_ >= ERROR) \
153  pg_unreachable(); \
154  } while(0)
155 #endif /* HAVE__BUILTIN_CONSTANT_P */
156 
157 #define ereport(elevel, ...) \
158  ereport_domain(elevel, TEXTDOMAIN, __VA_ARGS__)
159 
160 #define TEXTDOMAIN NULL
161 
162 extern bool message_level_is_interesting(int elevel);
163 
164 extern bool errstart(int elevel, const char *domain);
165 extern pg_attribute_cold bool errstart_cold(int elevel, const char *domain);
166 extern void errfinish(const char *filename, int lineno, const char *funcname);
167 
168 extern int errcode(int sqlerrcode);
169 
170 extern int errcode_for_file_access(void);
171 extern int errcode_for_socket_access(void);
172 
173 extern int errmsg(const char *fmt,...) pg_attribute_printf(1, 2);
174 extern int errmsg_internal(const char *fmt,...) pg_attribute_printf(1, 2);
175 
176 extern int errmsg_plural(const char *fmt_singular, const char *fmt_plural,
177  unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
178 
179 extern int errdetail(const char *fmt,...) pg_attribute_printf(1, 2);
180 extern int errdetail_internal(const char *fmt,...) pg_attribute_printf(1, 2);
181 
182 extern int errdetail_log(const char *fmt,...) pg_attribute_printf(1, 2);
183 
184 extern int errdetail_log_plural(const char *fmt_singular,
185  const char *fmt_plural,
186  unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
187 
188 extern int errdetail_plural(const char *fmt_singular, const char *fmt_plural,
189  unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
190 
191 extern int errhint(const char *fmt,...) pg_attribute_printf(1, 2);
192 
193 extern int errhint_plural(const char *fmt_singular, const char *fmt_plural,
194  unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
195 
196 /*
197  * errcontext() is typically called in error context callback functions, not
198  * within an ereport() invocation. The callback function can be in a different
199  * module than the ereport() call, so the message domain passed in errstart()
200  * is not usually the correct domain for translating the context message.
201  * set_errcontext_domain() first sets the domain to be used, and
202  * errcontext_msg() passes the actual message.
203  */
204 #define errcontext set_errcontext_domain(TEXTDOMAIN), errcontext_msg
205 
206 extern int set_errcontext_domain(const char *domain);
207 
208 extern int errcontext_msg(const char *fmt,...) pg_attribute_printf(1, 2);
209 
210 extern int errhidestmt(bool hide_stmt);
211 extern int errhidecontext(bool hide_ctx);
212 
213 extern int errbacktrace(void);
214 
215 extern int errposition(int cursorpos);
216 
217 extern int internalerrposition(int cursorpos);
218 extern int internalerrquery(const char *query);
219 
220 extern int err_generic_string(int field, const char *str);
221 
222 extern int geterrcode(void);
223 extern int geterrposition(void);
224 extern int getinternalerrposition(void);
225 
226 
227 /*----------
228  * Old-style error reporting API: to be used in this way:
229  * elog(ERROR, "portal \"%s\" not found", stmt->portalname);
230  *----------
231  */
232 #define elog(elevel, ...) \
233  ereport(elevel, errmsg_internal(__VA_ARGS__))
234 
235 
236 /* Support for constructing error strings separately from ereport() calls */
237 
238 extern void pre_format_elog_string(int errnumber, const char *domain);
239 extern char *format_elog_string(const char *fmt,...) pg_attribute_printf(1, 2);
240 
241 
242 /* Support for attaching context information to error reports */
243 
244 typedef struct ErrorContextCallback
245 {
246  struct ErrorContextCallback *previous;
247  void (*callback) (void *arg);
248  void *arg;
250 
252 
253 
254 /*----------
255  * API for catching ereport(ERROR) exits. Use these macros like so:
256  *
257  * PG_TRY();
258  * {
259  * ... code that might throw ereport(ERROR) ...
260  * }
261  * PG_CATCH();
262  * {
263  * ... error recovery code ...
264  * }
265  * PG_END_TRY();
266  *
267  * (The braces are not actually necessary, but are recommended so that
268  * pgindent will indent the construct nicely.) The error recovery code
269  * can either do PG_RE_THROW to propagate the error outwards, or do a
270  * (sub)transaction abort. Failure to do so may leave the system in an
271  * inconsistent state for further processing.
272  *
273  * For the common case that the error recovery code and the cleanup in the
274  * normal code path are identical, the following can be used instead:
275  *
276  * PG_TRY();
277  * {
278  * ... code that might throw ereport(ERROR) ...
279  * }
280  * PG_FINALLY();
281  * {
282  * ... cleanup code ...
283  * }
284  * PG_END_TRY();
285  *
286  * The cleanup code will be run in either case, and any error will be rethrown
287  * afterwards.
288  *
289  * You cannot use both PG_CATCH() and PG_FINALLY() in the same
290  * PG_TRY()/PG_END_TRY() block.
291  *
292  * Note: while the system will correctly propagate any new ereport(ERROR)
293  * occurring in the recovery section, there is a small limit on the number
294  * of levels this will work for. It's best to keep the error recovery
295  * section simple enough that it can't generate any new errors, at least
296  * not before popping the error stack.
297  *
298  * Note: an ereport(FATAL) will not be caught by this construct; control will
299  * exit straight through proc_exit(). Therefore, do NOT put any cleanup
300  * of non-process-local resources into the error recovery section, at least
301  * not without taking thought for what will happen during ereport(FATAL).
302  * The PG_ENSURE_ERROR_CLEANUP macros provided by storage/ipc.h may be
303  * helpful in such cases.
304  *
305  * Note: if a local variable of the function containing PG_TRY is modified
306  * in the PG_TRY section and used in the PG_CATCH section, that variable
307  * must be declared "volatile" for POSIX compliance. This is not mere
308  * pedantry; we have seen bugs from compilers improperly optimizing code
309  * away when such a variable was not marked. Beware that gcc's -Wclobbered
310  * warnings are just about entirely useless for catching such oversights.
311  *----------
312  */
313 #define PG_TRY() \
314  do { \
315  sigjmp_buf *_save_exception_stack = PG_exception_stack; \
316  ErrorContextCallback *_save_context_stack = error_context_stack; \
317  sigjmp_buf _local_sigjmp_buf; \
318  bool _do_rethrow = false; \
319  if (sigsetjmp(_local_sigjmp_buf, 0) == 0) \
320  { \
321  PG_exception_stack = &_local_sigjmp_buf
322 
323 #define PG_CATCH() \
324  } \
325  else \
326  { \
327  PG_exception_stack = _save_exception_stack; \
328  error_context_stack = _save_context_stack
329 
330 #define PG_FINALLY() \
331  } \
332  else \
333  _do_rethrow = true; \
334  { \
335  PG_exception_stack = _save_exception_stack; \
336  error_context_stack = _save_context_stack
337 
338 #define PG_END_TRY() \
339  } \
340  if (_do_rethrow) \
341  PG_RE_THROW(); \
342  PG_exception_stack = _save_exception_stack; \
343  error_context_stack = _save_context_stack; \
344  } while (0)
345 
346 /*
347  * Some compilers understand pg_attribute_noreturn(); for other compilers,
348  * insert pg_unreachable() so that the compiler gets the point.
349  */
350 #ifdef HAVE_PG_ATTRIBUTE_NORETURN
351 #define PG_RE_THROW() \
352  pg_re_throw()
353 #else
354 #define PG_RE_THROW() \
355  (pg_re_throw(), pg_unreachable())
356 #endif
357 
358 extern PGDLLIMPORT sigjmp_buf *PG_exception_stack;
359 
360 
361 /* Stuff that error handlers might want to use */
362 
363 /*
364  * ErrorData holds the data accumulated during any one ereport() cycle.
365  * Any non-NULL pointers must point to palloc'd data.
366  * (The const pointers are an exception; we assume they point at non-freeable
367  * constant strings.)
368  */
369 typedef struct ErrorData
370 {
371  int elevel; /* error level */
372  bool output_to_server; /* will report to server log? */
373  bool output_to_client; /* will report to client? */
374  bool hide_stmt; /* true to prevent STATEMENT: inclusion */
375  bool hide_ctx; /* true to prevent CONTEXT: inclusion */
376  const char *filename; /* __FILE__ of ereport() call */
377  int lineno; /* __LINE__ of ereport() call */
378  const char *funcname; /* __func__ of ereport() call */
379  const char *domain; /* message domain */
380  const char *context_domain; /* message domain for context message */
381  int sqlerrcode; /* encoded ERRSTATE */
382  char *message; /* primary error message (translated) */
383  char *detail; /* detail error message */
384  char *detail_log; /* detail error message for server log only */
385  char *hint; /* hint message */
386  char *context; /* context message */
387  char *backtrace; /* backtrace */
388  const char *message_id; /* primary message's id (original string) */
389  char *schema_name; /* name of schema */
390  char *table_name; /* name of table */
391  char *column_name; /* name of column */
392  char *datatype_name; /* name of datatype */
393  char *constraint_name; /* name of constraint */
394  int cursorpos; /* cursor index into query string */
395  int internalpos; /* cursor index into internalquery */
396  char *internalquery; /* text of internally-generated query */
397  int saved_errno; /* errno at entry */
398 
399  /* context containing associated non-constant strings */
401 } ErrorData;
402 
403 extern void EmitErrorReport(void);
404 extern ErrorData *CopyErrorData(void);
405 extern void FreeErrorData(ErrorData *edata);
406 extern void FlushErrorState(void);
407 extern void ReThrowError(ErrorData *edata) pg_attribute_noreturn();
408 extern void ThrowErrorData(ErrorData *edata);
409 extern void pg_re_throw(void) pg_attribute_noreturn();
410 
411 extern char *GetErrorContextStack(void);
412 
413 /* Hook for intercepting messages before they are sent to the server log */
414 typedef void (*emit_log_hook_type) (ErrorData *edata);
416 
417 
418 /* GUC-configurable parameters */
419 
420 typedef enum
421 {
422  PGERROR_TERSE, /* single-line error messages */
423  PGERROR_DEFAULT, /* recommended style */
424  PGERROR_VERBOSE /* all the facts, ma'am */
426 
427 extern int Log_error_verbosity;
428 extern char *Log_line_prefix;
429 extern int Log_destination;
430 extern char *Log_destination_string;
431 extern bool syslog_sequence_numbers;
432 extern bool syslog_split_messages;
433 
434 /* Log destination bitmap */
435 #define LOG_DESTINATION_STDERR 1
436 #define LOG_DESTINATION_SYSLOG 2
437 #define LOG_DESTINATION_EVENTLOG 4
438 #define LOG_DESTINATION_CSVLOG 8
439 
440 /* Other exported functions */
441 extern void DebugFileOpen(void);
442 extern char *unpack_sql_state(int sql_state);
443 extern bool in_error_recursion_trouble(void);
444 
445 #ifdef HAVE_SYSLOG
446 extern void set_syslog_parameters(const char *ident, int facility);
447 #endif
448 
449 /*
450  * Write errors to stderr (or by equal means when stderr is
451  * not available). Used before ereport/elog can be used
452  * safely (memory context, GUC load etc)
453  */
454 extern void write_stderr(const char *fmt,...) pg_attribute_printf(1, 2);
455 
456 #endif /* ELOG_H */
char * schema_name
Definition: elog.h:389
#define pg_attribute_noreturn()
Definition: c.h:179
bool hide_stmt
Definition: elog.h:374
int errbacktrace(void)
Definition: elog.c:931
#define pg_attribute_cold
Definition: c.h:237
void pre_format_elog_string(int errnumber, const char *domain)
Definition: elog.c:1467
int errcode_for_file_access(void)
Definition: elog.c:721
int errposition(int cursorpos)
Definition: elog.c:1285
char * format_elog_string(const char *fmt,...) pg_attribute_printf(1
int sqlerrcode
Definition: elog.h:381
const char * funcname
Definition: elog.h:378
void ReThrowError(ErrorData *edata) pg_attribute_noreturn()
Definition: elog.c:1738
ErrorData * CopyErrorData(void)
Definition: elog.c:1560
char * Log_line_prefix
Definition: elog.c:110
int lineno
Definition: elog.h:377
PGDLLIMPORT sigjmp_buf * PG_exception_stack
Definition: elog.c:95
char * internalquery
Definition: elog.h:396
int int errmsg_internal(const char *fmt,...) pg_attribute_printf(1
int int errhidestmt(bool hide_stmt)
Definition: elog.c:1250
void FreeErrorData(ErrorData *edata)
Definition: elog.c:1616
char struct ErrorContextCallback ErrorContextCallback
void errfinish(const char *filename, int lineno, const char *funcname)
Definition: elog.c:513
struct ErrorContextCallback * previous
Definition: elog.h:246
int int int errmsg_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n,...) pg_attribute_printf(1
#define PGDLLIMPORT
Definition: c.h:1317
int cursorpos
Definition: elog.h:394
const char * context_domain
Definition: elog.h:380
int errhidecontext(bool hide_ctx)
Definition: elog.c:1269
bool syslog_sequence_numbers
Definition: elog.c:113
char * GetErrorContextStack(void)
Definition: elog.c:1855
const char * filename
Definition: elog.h:376
char * detail_log
Definition: elog.h:384
int errdetail_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n,...) pg_attribute_printf(1
int errcode_for_socket_access(void)
Definition: elog.c:792
int set_errcontext_domain(const char *domain)
Definition: elog.c:1230
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:48
int geterrcode(void)
Definition: elog.c:1400
int geterrposition(void)
Definition: elog.c:1417
int internalerrquery(const char *query)
Definition: elog.c:1321
char * table_name
Definition: elog.h:390
pg_attribute_cold bool errstart_cold(int elevel, const char *domain)
Definition: elog.c:324
bool output_to_server
Definition: elog.h:372
int internalpos
Definition: elog.h:395
int saved_errno
Definition: elog.h:397
bool hide_ctx
Definition: elog.h:375
void ThrowErrorData(ErrorData *edata)
Definition: elog.c:1679
const char * ident
Definition: memnodes.h:91
int int errhint_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n,...) pg_attribute_printf(1
int internalerrposition(int cursorpos)
Definition: elog.c:1301
char * backtrace
Definition: elog.h:387
char * datatype_name
Definition: elog.h:392
int elevel
Definition: elog.h:371
static int elevel
Definition: vacuumlazy.c:400
char * detail
Definition: elog.h:383
void EmitErrorReport(void)
Definition: elog.c:1509
int int int pg_attribute_printf(2, 4)
int int errdetail_internal(const char *fmt,...) pg_attribute_printf(1
PGDLLIMPORT emit_log_hook_type emit_log_hook
Definition: elog.c:106
const char * message_id
Definition: elog.h:388
int Log_destination
Definition: elog.c:111
int errmsg(const char *fmt,...) pg_attribute_printf(1
void(* emit_log_hook_type)(ErrorData *edata)
Definition: elog.h:414
bool message_level_is_interesting(int elevel)
Definition: elog.c:270
char * column_name
Definition: elog.h:391
int err_generic_string(int field, const char *str)
Definition: elog.c:1351
int getinternalerrposition(void)
Definition: elog.c:1434
PGErrorVerbosity
Definition: elog.h:420
bool errstart(int elevel, const char *domain)
Definition: elog.c:340
char * hint
Definition: elog.h:385
int errcontext_msg(const char *fmt,...) pg_attribute_printf(1
char * context
Definition: elog.h:386
struct MemoryContextData * assoc_context
Definition: elog.h:400
int errhint(const char *fmt,...) pg_attribute_printf(1
int int int errdetail_log(const char *fmt,...) pg_attribute_printf(1
static char * filename
Definition: pg_dumpall.c:91
bool in_error_recursion_trouble(void)
Definition: elog.c:291
void pg_re_throw(void) pg_attribute_noreturn()
Definition: elog.c:1799
void write_stderr(const char *fmt,...) pg_attribute_printf(1
void * arg
bool syslog_split_messages
Definition: elog.c:114
void FlushErrorState(void)
Definition: elog.c:1654
int errdetail(const char *fmt,...) pg_attribute_printf(1
int Log_error_verbosity
Definition: elog.c:109
const char * domain
Definition: elog.h:379
char * constraint_name
Definition: elog.h:393
char * Log_destination_string
Definition: elog.c:112
char * unpack_sql_state(int sql_state)
Definition: elog.c:2988
int int int int errdetail_log_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n,...) pg_attribute_printf(1
bool output_to_client
Definition: elog.h:373
char * message
Definition: elog.h:382
void DebugFileOpen(void)
Definition: elog.c:1922
PGDLLIMPORT ErrorContextCallback * error_context_stack
Definition: elog.c:93
struct ErrorData ErrorData
int errcode(int sqlerrcode)
Definition: elog.c:698