1/*-------------------------------------------------------------------------
2 *
3 * elog.h
4 * POSTGRES error reporting/logging definitions.
5 *
6 *
7 * Portions Copyright (c) 1996-2019, 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 ERROR 20 /* user error - abort transaction; return to
44 * known state */
45/* Save ERROR value in PGERROR so it can be restored when Win32 includes
46 * modify it. We have to use a constant rather than ERROR because macros
47 * are expanded only when referenced outside macros.
48 */
49#ifdef WIN32
50#define PGERROR 20
51#endif
52#define FATAL 21 /* fatal error - abort process */
53#define PANIC 22 /* take down the other backends with me */
54
55 /* #define DEBUG DEBUG1 */ /* Backward compatibility with pre-7.3 */
56
57
58/* macros for representing SQLSTATE strings compactly */
59#define PGSIXBIT(ch) (((ch) - '0') & 0x3F)
60#define PGUNSIXBIT(val) (((val) & 0x3F) + '0')
61
62#define MAKE_SQLSTATE(ch1,ch2,ch3,ch4,ch5) \
63 (PGSIXBIT(ch1) + (PGSIXBIT(ch2) << 6) + (PGSIXBIT(ch3) << 12) + \
64 (PGSIXBIT(ch4) << 18) + (PGSIXBIT(ch5) << 24))
65
66/* These macros depend on the fact that '0' becomes a zero in SIXBIT */
67#define ERRCODE_TO_CATEGORY(ec) ((ec) & ((1 << 12) - 1))
68#define ERRCODE_IS_CATEGORY(ec) (((ec) & ~((1 << 12) - 1)) == 0)
69
70/* SQLSTATE codes for errors are defined in a separate file */
71#include "utils/errcodes.h"
72
73/*
74 * Provide a way to prevent "errno" from being accidentally used inside an
75 * elog() or ereport() invocation. Since we know that some operating systems
76 * define errno as something involving a function call, we'll put a local
77 * variable of the same name as that function in the local scope to force a
78 * compile error. On platforms that don't define errno in that way, nothing
79 * happens, so we get no warning ... but we can live with that as long as it
80 * happens on some popular platforms.
81 */
82#if defined(errno) && defined(__linux__)
83#define pg_prevent_errno_in_scope() int __errno_location pg_attribute_unused()
84#elif defined(errno) && (defined(__darwin__) || defined(__freebsd__))
85#define pg_prevent_errno_in_scope() int __error pg_attribute_unused()
86#else
87#define pg_prevent_errno_in_scope()
88#endif
89
90
91/*----------
92 * New-style error reporting API: to be used in this way:
93 * ereport(ERROR,
94 * (errcode(ERRCODE_UNDEFINED_CURSOR),
95 * errmsg("portal \"%s\" not found", stmt->portalname),
96 * ... other errxxx() fields as needed ...));
97 *
98 * The error level is required, and so is a primary error message (errmsg
99 * or errmsg_internal). All else is optional. errcode() defaults to
100 * ERRCODE_INTERNAL_ERROR if elevel is ERROR or more, ERRCODE_WARNING
101 * if elevel is WARNING, or ERRCODE_SUCCESSFUL_COMPLETION if elevel is
102 * NOTICE or below.
103 *
104 * ereport_domain() allows a message domain to be specified, for modules that
105 * wish to use a different message catalog from the backend's. To avoid having
106 * one copy of the default text domain per .o file, we define it as NULL here
107 * and have errstart insert the default text domain. Modules can either use
108 * ereport_domain() directly, or preferably they can override the TEXTDOMAIN
109 * macro.
110 *
111 * If elevel >= ERROR, the call will not return; we try to inform the compiler
112 * of that via pg_unreachable(). However, no useful optimization effect is
113 * obtained unless the compiler sees elevel as a compile-time constant, else
114 * we're just adding code bloat. So, if __builtin_constant_p is available,
115 * use that to cause the second if() to vanish completely for non-constant
116 * cases. We avoid using a local variable because it's not necessary and
117 * prevents gcc from making the unreachability deduction at optlevel -O0.
118 *----------
119 */
120#ifdef HAVE__BUILTIN_CONSTANT_P
121#define ereport_domain(elevel, domain, rest) \
122 do { \
123 pg_prevent_errno_in_scope(); \
124 if (errstart(elevel, __FILE__, __LINE__, PG_FUNCNAME_MACRO, domain)) \
125 errfinish rest; \
126 if (__builtin_constant_p(elevel) && (elevel) >= ERROR) \
127 pg_unreachable(); \
128 } while(0)
129#else /* !HAVE__BUILTIN_CONSTANT_P */
130#define ereport_domain(elevel, domain, rest) \
131 do { \
132 const int elevel_ = (elevel); \
133 pg_prevent_errno_in_scope(); \
134 if (errstart(elevel_, __FILE__, __LINE__, PG_FUNCNAME_MACRO, domain)) \
135 errfinish rest; \
136 if (elevel_ >= ERROR) \
137 pg_unreachable(); \
138 } while(0)
139#endif /* HAVE__BUILTIN_CONSTANT_P */
140
141#define ereport(elevel, rest) \
142 ereport_domain(elevel, TEXTDOMAIN, rest)
143
144#define TEXTDOMAIN NULL
145
146extern bool errstart(int elevel, const char *filename, int lineno,
147 const char *funcname, const char *domain);
148extern void errfinish(int dummy,...);
149
150extern int errcode(int sqlerrcode);
151
152extern int errcode_for_file_access(void);
153extern int errcode_for_socket_access(void);
154
155extern int errmsg(const char *fmt,...) pg_attribute_printf(1, 2);
156extern int errmsg_internal(const char *fmt,...) pg_attribute_printf(1, 2);
157
158extern int errmsg_plural(const char *fmt_singular, const char *fmt_plural,
159 unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
160
161extern int errdetail(const char *fmt,...) pg_attribute_printf(1, 2);
162extern int errdetail_internal(const char *fmt,...) pg_attribute_printf(1, 2);
163
164extern int errdetail_log(const char *fmt,...) pg_attribute_printf(1, 2);
165
166extern int errdetail_log_plural(const char *fmt_singular,
167 const char *fmt_plural,
168 unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
169
170extern int errdetail_plural(const char *fmt_singular, const char *fmt_plural,
171 unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
172
173extern int errhint(const char *fmt,...) pg_attribute_printf(1, 2);
174
175/*
176 * errcontext() is typically called in error context callback functions, not
177 * within an ereport() invocation. The callback function can be in a different
178 * module than the ereport() call, so the message domain passed in errstart()
179 * is not usually the correct domain for translating the context message.
180 * set_errcontext_domain() first sets the domain to be used, and
181 * errcontext_msg() passes the actual message.
182 */
183#define errcontext set_errcontext_domain(TEXTDOMAIN), errcontext_msg
184
185extern int set_errcontext_domain(const char *domain);
186
187extern int errcontext_msg(const char *fmt,...) pg_attribute_printf(1, 2);
188
189extern int errhidestmt(bool hide_stmt);
190extern int errhidecontext(bool hide_ctx);
191
192extern int errfunction(const char *funcname);
193extern int errposition(int cursorpos);
194
195extern int internalerrposition(int cursorpos);
196extern int internalerrquery(const char *query);
197
198extern int err_generic_string(int field, const char *str);
199
200extern int geterrcode(void);
201extern int geterrposition(void);
202extern int getinternalerrposition(void);
203
204
205/*----------
206 * Old-style error reporting API: to be used in this way:
207 * elog(ERROR, "portal \"%s\" not found", stmt->portalname);
208 *----------
209 */
210/*
211 * Using variadic macros, we can give the compiler a hint about the
212 * call not returning when elevel >= ERROR. See comments for ereport().
213 * Note that historically elog() has called elog_start (which saves errno)
214 * before evaluating "elevel", so we preserve that behavior here.
215 */
216#ifdef HAVE__BUILTIN_CONSTANT_P
217#define elog(elevel, ...) \
218 do { \
219 pg_prevent_errno_in_scope(); \
220 elog_start(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
221 elog_finish(elevel, __VA_ARGS__); \
222 if (__builtin_constant_p(elevel) && (elevel) >= ERROR) \
223 pg_unreachable(); \
224 } while(0)
225#else /* !HAVE__BUILTIN_CONSTANT_P */
226#define elog(elevel, ...) \
227 do { \
228 pg_prevent_errno_in_scope(); \
229 elog_start(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
230 { \
231 const int elevel_ = (elevel); \
232 elog_finish(elevel_, __VA_ARGS__); \
233 if (elevel_ >= ERROR) \
234 pg_unreachable(); \
235 } \
236 } while(0)
237#endif /* HAVE__BUILTIN_CONSTANT_P */
238
239extern void elog_start(const char *filename, int lineno, const char *funcname);
240extern void elog_finish(int elevel, const char *fmt,...) pg_attribute_printf(2, 3);
241
242
243/* Support for constructing error strings separately from ereport() calls */
244
245extern void pre_format_elog_string(int errnumber, const char *domain);
246extern char *format_elog_string(const char *fmt,...) pg_attribute_printf(1, 2);
247
248
249/* Support for attaching context information to error reports */
250
251typedef struct ErrorContextCallback
252{
253 struct ErrorContextCallback *previous;
254 void (*callback) (void *arg);
255 void *arg;
256} ErrorContextCallback;
257
258extern PGDLLIMPORT ErrorContextCallback *error_context_stack;
259
260
261/*----------
262 * API for catching ereport(ERROR) exits. Use these macros like so:
263 *
264 * PG_TRY();
265 * {
266 * ... code that might throw ereport(ERROR) ...
267 * }
268 * PG_CATCH();
269 * {
270 * ... error recovery code ...
271 * }
272 * PG_END_TRY();
273 *
274 * (The braces are not actually necessary, but are recommended so that
275 * pgindent will indent the construct nicely.) The error recovery code
276 * can either do PG_RE_THROW to propagate the error outwards, or do a
277 * (sub)transaction abort. Failure to do so may leave the system in an
278 * inconsistent state for further processing.
279 *
280 * Note: while the system will correctly propagate any new ereport(ERROR)
281 * occurring in the recovery section, there is a small limit on the number
282 * of levels this will work for. It's best to keep the error recovery
283 * section simple enough that it can't generate any new errors, at least
284 * not before popping the error stack.
285 *
286 * Note: an ereport(FATAL) will not be caught by this construct; control will
287 * exit straight through proc_exit(). Therefore, do NOT put any cleanup
288 * of non-process-local resources into the error recovery section, at least
289 * not without taking thought for what will happen during ereport(FATAL).
290 * The PG_ENSURE_ERROR_CLEANUP macros provided by storage/ipc.h may be
291 * helpful in such cases.
292 *
293 * Note: if a local variable of the function containing PG_TRY is modified
294 * in the PG_TRY section and used in the PG_CATCH section, that variable
295 * must be declared "volatile" for POSIX compliance. This is not mere
296 * pedantry; we have seen bugs from compilers improperly optimizing code
297 * away when such a variable was not marked. Beware that gcc's -Wclobbered
298 * warnings are just about entirely useless for catching such oversights.
299 *----------
300 */
301#define PG_TRY() \
302 do { \
303 sigjmp_buf *save_exception_stack = PG_exception_stack; \
304 ErrorContextCallback *save_context_stack = error_context_stack; \
305 sigjmp_buf local_sigjmp_buf; \
306 if (sigsetjmp(local_sigjmp_buf, 0) == 0) \
307 { \
308 PG_exception_stack = &local_sigjmp_buf
309
310#define PG_CATCH() \
311 } \
312 else \
313 { \
314 PG_exception_stack = save_exception_stack; \
315 error_context_stack = save_context_stack
316
317#define PG_END_TRY() \
318 } \
319 PG_exception_stack = save_exception_stack; \
320 error_context_stack = save_context_stack; \
321 } while (0)
322
323/*
324 * Some compilers understand pg_attribute_noreturn(); for other compilers,
325 * insert pg_unreachable() so that the compiler gets the point.
326 */
327#ifdef HAVE_PG_ATTRIBUTE_NORETURN
328#define PG_RE_THROW() \
329 pg_re_throw()
330#else
331#define PG_RE_THROW() \
332 (pg_re_throw(), pg_unreachable())
333#endif
334
335extern PGDLLIMPORT sigjmp_buf *PG_exception_stack;
336
337
338/* Stuff that error handlers might want to use */
339
340/*
341 * ErrorData holds the data accumulated during any one ereport() cycle.
342 * Any non-NULL pointers must point to palloc'd data.
343 * (The const pointers are an exception; we assume they point at non-freeable
344 * constant strings.)
345 */
346typedef struct ErrorData
347{
348 int elevel; /* error level */
349 bool output_to_server; /* will report to server log? */
350 bool output_to_client; /* will report to client? */
351 bool show_funcname; /* true to force funcname inclusion */
352 bool hide_stmt; /* true to prevent STATEMENT: inclusion */
353 bool hide_ctx; /* true to prevent CONTEXT: inclusion */
354 const char *filename; /* __FILE__ of ereport() call */
355 int lineno; /* __LINE__ of ereport() call */
356 const char *funcname; /* __func__ of ereport() call */
357 const char *domain; /* message domain */
358 const char *context_domain; /* message domain for context message */
359 int sqlerrcode; /* encoded ERRSTATE */
360 char *message; /* primary error message (translated) */
361 char *detail; /* detail error message */
362 char *detail_log; /* detail error message for server log only */
363 char *hint; /* hint message */
364 char *context; /* context message */
365 const char *message_id; /* primary message's id (original string) */
366 char *schema_name; /* name of schema */
367 char *table_name; /* name of table */
368 char *column_name; /* name of column */
369 char *datatype_name; /* name of datatype */
370 char *constraint_name; /* name of constraint */
371 int cursorpos; /* cursor index into query string */
372 int internalpos; /* cursor index into internalquery */
373 char *internalquery; /* text of internally-generated query */
374 int saved_errno; /* errno at entry */
375
376 /* context containing associated non-constant strings */
377 struct MemoryContextData *assoc_context;
378} ErrorData;
379
380extern void EmitErrorReport(void);
381extern ErrorData *CopyErrorData(void);
382extern void FreeErrorData(ErrorData *edata);
383extern void FlushErrorState(void);
384extern void ReThrowError(ErrorData *edata) pg_attribute_noreturn();
385extern void ThrowErrorData(ErrorData *edata);
386extern void pg_re_throw(void) pg_attribute_noreturn();
387
388extern char *GetErrorContextStack(void);
389
390/* Hook for intercepting messages before they are sent to the server log */
391typedef void (*emit_log_hook_type) (ErrorData *edata);
392extern PGDLLIMPORT emit_log_hook_type emit_log_hook;
393
394
395/* GUC-configurable parameters */
396
397typedef enum
398{
399 PGERROR_TERSE, /* single-line error messages */
400 PGERROR_DEFAULT, /* recommended style */
401 PGERROR_VERBOSE /* all the facts, ma'am */
402} PGErrorVerbosity;
403
404extern int Log_error_verbosity;
405extern char *Log_line_prefix;
406extern int Log_destination;
407extern char *Log_destination_string;
408extern bool syslog_sequence_numbers;
409extern bool syslog_split_messages;
410
411/* Log destination bitmap */
412#define LOG_DESTINATION_STDERR 1
413#define LOG_DESTINATION_SYSLOG 2
414#define LOG_DESTINATION_EVENTLOG 4
415#define LOG_DESTINATION_CSVLOG 8
416
417/* Other exported functions */
418extern void DebugFileOpen(void);
419extern char *unpack_sql_state(int sql_state);
420extern bool in_error_recursion_trouble(void);
421
422#ifdef HAVE_SYSLOG
423extern void set_syslog_parameters(const char *ident, int facility);
424#endif
425
426/*
427 * Write errors to stderr (or by equal means when stderr is
428 * not available). Used before ereport/elog can be used
429 * safely (memory context, GUC load etc)
430 */
431extern void write_stderr(const char *fmt,...) pg_attribute_printf(1, 2);
432
433#endif /* ELOG_H */
434