PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
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-2017, 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 /*----------
75  * New-style error reporting API: to be used in this way:
76  * ereport(ERROR,
77  * (errcode(ERRCODE_UNDEFINED_CURSOR),
78  * errmsg("portal \"%s\" not found", stmt->portalname),
79  * ... other errxxx() fields as needed ...));
80  *
81  * The error level is required, and so is a primary error message (errmsg
82  * or errmsg_internal). All else is optional. errcode() defaults to
83  * ERRCODE_INTERNAL_ERROR if elevel is ERROR or more, ERRCODE_WARNING
84  * if elevel is WARNING, or ERRCODE_SUCCESSFUL_COMPLETION if elevel is
85  * NOTICE or below.
86  *
87  * ereport_domain() allows a message domain to be specified, for modules that
88  * wish to use a different message catalog from the backend's. To avoid having
89  * one copy of the default text domain per .o file, we define it as NULL here
90  * and have errstart insert the default text domain. Modules can either use
91  * ereport_domain() directly, or preferably they can override the TEXTDOMAIN
92  * macro.
93  *
94  * If elevel >= ERROR, the call will not return; we try to inform the compiler
95  * of that via pg_unreachable(). However, no useful optimization effect is
96  * obtained unless the compiler sees elevel as a compile-time constant, else
97  * we're just adding code bloat. So, if __builtin_constant_p is available,
98  * use that to cause the second if() to vanish completely for non-constant
99  * cases. We avoid using a local variable because it's not necessary and
100  * prevents gcc from making the unreachability deduction at optlevel -O0.
101  *----------
102  */
103 #ifdef HAVE__BUILTIN_CONSTANT_P
104 #define ereport_domain(elevel, domain, rest) \
105  do { \
106  if (errstart(elevel, __FILE__, __LINE__, PG_FUNCNAME_MACRO, domain)) \
107  errfinish rest; \
108  if (__builtin_constant_p(elevel) && (elevel) >= ERROR) \
109  pg_unreachable(); \
110  } while(0)
111 #else /* !HAVE__BUILTIN_CONSTANT_P */
112 #define ereport_domain(elevel, domain, rest) \
113  do { \
114  const int elevel_ = (elevel); \
115  if (errstart(elevel_, __FILE__, __LINE__, PG_FUNCNAME_MACRO, domain)) \
116  errfinish rest; \
117  if (elevel_ >= ERROR) \
118  pg_unreachable(); \
119  } while(0)
120 #endif /* HAVE__BUILTIN_CONSTANT_P */
121 
122 #define ereport(elevel, rest) \
123  ereport_domain(elevel, TEXTDOMAIN, rest)
124 
125 #define TEXTDOMAIN NULL
126 
127 extern bool errstart(int elevel, const char *filename, int lineno,
128  const char *funcname, const char *domain);
129 extern void errfinish(int dummy,...);
130 
131 extern int errcode(int sqlerrcode);
132 
133 extern int errcode_for_file_access(void);
134 extern int errcode_for_socket_access(void);
135 
136 extern int errmsg(const char *fmt,...) pg_attribute_printf(1, 2);
137 extern int errmsg_internal(const char *fmt,...) pg_attribute_printf(1, 2);
138 
139 extern int errmsg_plural(const char *fmt_singular, const char *fmt_plural,
140  unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
141 
142 extern int errdetail(const char *fmt,...) pg_attribute_printf(1, 2);
143 extern int errdetail_internal(const char *fmt,...) pg_attribute_printf(1, 2);
144 
145 extern int errdetail_log(const char *fmt,...) pg_attribute_printf(1, 2);
146 
147 extern int errdetail_log_plural(const char *fmt_singular,
148  const char *fmt_plural,
149  unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
150 
151 extern int errdetail_plural(const char *fmt_singular, const char *fmt_plural,
152  unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
153 
154 extern int errhint(const char *fmt,...) pg_attribute_printf(1, 2);
155 
156 /*
157  * errcontext() is typically called in error context callback functions, not
158  * within an ereport() invocation. The callback function can be in a different
159  * module than the ereport() call, so the message domain passed in errstart()
160  * is not usually the correct domain for translating the context message.
161  * set_errcontext_domain() first sets the domain to be used, and
162  * errcontext_msg() passes the actual message.
163  */
164 #define errcontext set_errcontext_domain(TEXTDOMAIN), errcontext_msg
165 
166 extern int set_errcontext_domain(const char *domain);
167 
168 extern int errcontext_msg(const char *fmt,...) pg_attribute_printf(1, 2);
169 
170 extern int errhidestmt(bool hide_stmt);
171 extern int errhidecontext(bool hide_ctx);
172 
173 extern int errfunction(const char *funcname);
174 extern int errposition(int cursorpos);
175 
176 extern int internalerrposition(int cursorpos);
177 extern int internalerrquery(const char *query);
178 
179 extern int err_generic_string(int field, const char *str);
180 
181 extern int geterrcode(void);
182 extern int geterrposition(void);
183 extern int getinternalerrposition(void);
184 
185 
186 /*----------
187  * Old-style error reporting API: to be used in this way:
188  * elog(ERROR, "portal \"%s\" not found", stmt->portalname);
189  *----------
190  */
191 #ifdef HAVE__VA_ARGS
192 /*
193  * If we have variadic macros, we can give the compiler a hint about the
194  * call not returning when elevel >= ERROR. See comments for ereport().
195  * Note that historically elog() has called elog_start (which saves errno)
196  * before evaluating "elevel", so we preserve that behavior here.
197  */
198 #ifdef HAVE__BUILTIN_CONSTANT_P
199 #define elog(elevel, ...) \
200  do { \
201  elog_start(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
202  elog_finish(elevel, __VA_ARGS__); \
203  if (__builtin_constant_p(elevel) && (elevel) >= ERROR) \
204  pg_unreachable(); \
205  } while(0)
206 #else /* !HAVE__BUILTIN_CONSTANT_P */
207 #define elog(elevel, ...) \
208  do { \
209  elog_start(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
210  { \
211  const int elevel_ = (elevel); \
212  elog_finish(elevel_, __VA_ARGS__); \
213  if (elevel_ >= ERROR) \
214  pg_unreachable(); \
215  } \
216  } while(0)
217 #endif /* HAVE__BUILTIN_CONSTANT_P */
218 #else /* !HAVE__VA_ARGS */
219 #define elog \
220  elog_start(__FILE__, __LINE__, PG_FUNCNAME_MACRO), \
221  elog_finish
222 #endif /* HAVE__VA_ARGS */
223 
224 extern void elog_start(const char *filename, int lineno, const char *funcname);
225 extern void elog_finish(int elevel, const char *fmt,...) pg_attribute_printf(2, 3);
226 
227 
228 /* Support for constructing error strings separately from ereport() calls */
229 
230 extern void pre_format_elog_string(int errnumber, const char *domain);
231 extern char *format_elog_string(const char *fmt,...) pg_attribute_printf(1, 2);
232 
233 
234 /* Support for attaching context information to error reports */
235 
237 {
238  struct ErrorContextCallback *previous;
239  void (*callback) (void *arg);
240  void *arg;
242 
244 
245 
246 /*----------
247  * API for catching ereport(ERROR) exits. Use these macros like so:
248  *
249  * PG_TRY();
250  * {
251  * ... code that might throw ereport(ERROR) ...
252  * }
253  * PG_CATCH();
254  * {
255  * ... error recovery code ...
256  * }
257  * PG_END_TRY();
258  *
259  * (The braces are not actually necessary, but are recommended so that
260  * pgindent will indent the construct nicely.) The error recovery code
261  * can optionally do PG_RE_THROW() to propagate the same error outwards.
262  *
263  * Note: while the system will correctly propagate any new ereport(ERROR)
264  * occurring in the recovery section, there is a small limit on the number
265  * of levels this will work for. It's best to keep the error recovery
266  * section simple enough that it can't generate any new errors, at least
267  * not before popping the error stack.
268  *
269  * Note: an ereport(FATAL) will not be caught by this construct; control will
270  * exit straight through proc_exit(). Therefore, do NOT put any cleanup
271  * of non-process-local resources into the error recovery section, at least
272  * not without taking thought for what will happen during ereport(FATAL).
273  * The PG_ENSURE_ERROR_CLEANUP macros provided by storage/ipc.h may be
274  * helpful in such cases.
275  *
276  * Note: if a local variable of the function containing PG_TRY is modified
277  * in the PG_TRY section and used in the PG_CATCH section, that variable
278  * must be declared "volatile" for POSIX compliance. This is not mere
279  * pedantry; we have seen bugs from compilers improperly optimizing code
280  * away when such a variable was not marked. Beware that gcc's -Wclobbered
281  * warnings are just about entirely useless for catching such oversights.
282  *----------
283  */
284 #define PG_TRY() \
285  do { \
286  sigjmp_buf *save_exception_stack = PG_exception_stack; \
287  ErrorContextCallback *save_context_stack = error_context_stack; \
288  sigjmp_buf local_sigjmp_buf; \
289  if (sigsetjmp(local_sigjmp_buf, 0) == 0) \
290  { \
291  PG_exception_stack = &local_sigjmp_buf
292 
293 #define PG_CATCH() \
294  } \
295  else \
296  { \
297  PG_exception_stack = save_exception_stack; \
298  error_context_stack = save_context_stack
299 
300 #define PG_END_TRY() \
301  } \
302  PG_exception_stack = save_exception_stack; \
303  error_context_stack = save_context_stack; \
304  } while (0)
305 
306 /*
307  * Some compilers understand pg_attribute_noreturn(); for other compilers,
308  * insert pg_unreachable() so that the compiler gets the point.
309  */
310 #ifdef HAVE_PG_ATTRIBUTE_NORETURN
311 #define PG_RE_THROW() \
312  pg_re_throw()
313 #else
314 #define PG_RE_THROW() \
315  (pg_re_throw(), pg_unreachable())
316 #endif
317 
318 extern PGDLLIMPORT sigjmp_buf *PG_exception_stack;
319 
320 
321 /* Stuff that error handlers might want to use */
322 
323 /*
324  * ErrorData holds the data accumulated during any one ereport() cycle.
325  * Any non-NULL pointers must point to palloc'd data.
326  * (The const pointers are an exception; we assume they point at non-freeable
327  * constant strings.)
328  */
329 typedef struct ErrorData
330 {
331  int elevel; /* error level */
332  bool output_to_server; /* will report to server log? */
333  bool output_to_client; /* will report to client? */
334  bool show_funcname; /* true to force funcname inclusion */
335  bool hide_stmt; /* true to prevent STATEMENT: inclusion */
336  bool hide_ctx; /* true to prevent CONTEXT: inclusion */
337  const char *filename; /* __FILE__ of ereport() call */
338  int lineno; /* __LINE__ of ereport() call */
339  const char *funcname; /* __func__ of ereport() call */
340  const char *domain; /* message domain */
341  const char *context_domain; /* message domain for context message */
342  int sqlerrcode; /* encoded ERRSTATE */
343  char *message; /* primary error message (translated) */
344  char *detail; /* detail error message */
345  char *detail_log; /* detail error message for server log only */
346  char *hint; /* hint message */
347  char *context; /* context message */
348  const char *message_id; /* primary message's id (original string) */
349  char *schema_name; /* name of schema */
350  char *table_name; /* name of table */
351  char *column_name; /* name of column */
352  char *datatype_name; /* name of datatype */
353  char *constraint_name; /* name of constraint */
354  int cursorpos; /* cursor index into query string */
355  int internalpos; /* cursor index into internalquery */
356  char *internalquery; /* text of internally-generated query */
357  int saved_errno; /* errno at entry */
358 
359  /* context containing associated non-constant strings */
361 } ErrorData;
362 
363 extern void EmitErrorReport(void);
364 extern ErrorData *CopyErrorData(void);
365 extern void FreeErrorData(ErrorData *edata);
366 extern void FlushErrorState(void);
367 extern void ReThrowError(ErrorData *edata) pg_attribute_noreturn();
368 extern void ThrowErrorData(ErrorData *edata);
369 extern void pg_re_throw(void) pg_attribute_noreturn();
370 
371 extern char *GetErrorContextStack(void);
372 
373 /* Hook for intercepting messages before they are sent to the server log */
376 
377 
378 /* GUC-configurable parameters */
379 
381 {
382  PGERROR_TERSE, /* single-line error messages */
383  PGERROR_DEFAULT, /* recommended style */
384  PGERROR_VERBOSE /* all the facts, ma'am */
386 
387 extern int Log_error_verbosity;
388 extern char *Log_line_prefix;
389 extern int Log_destination;
390 extern char *Log_destination_string;
391 extern bool syslog_sequence_numbers;
392 extern bool syslog_split_messages;
393 
394 /* Log destination bitmap */
395 #define LOG_DESTINATION_STDERR 1
396 #define LOG_DESTINATION_SYSLOG 2
397 #define LOG_DESTINATION_EVENTLOG 4
398 #define LOG_DESTINATION_CSVLOG 8
399 
400 /* Other exported functions */
401 extern void DebugFileOpen(void);
402 extern char *unpack_sql_state(int sql_state);
403 extern bool in_error_recursion_trouble(void);
404 
405 #ifdef HAVE_SYSLOG
406 extern void set_syslog_parameters(const char *ident, int facility);
407 #endif
408 
409 /*
410  * Write errors to stderr (or by equal means when stderr is
411  * not available). Used before ereport/elog can be used
412  * safely (memory context, GUC load etc)
413  */
414 extern void write_stderr(const char *fmt,...) pg_attribute_printf(1, 2);
415 
416 #endif /* ELOG_H */
typedef(PHANDLE, HANDLE, WAITORTIMERCALLBACK, PVOID, ULONG, ULONG)
char * schema_name
Definition: elog.h:349
bool hide_stmt
Definition: elog.h:335
int errcode_for_file_access(void)
Definition: elog.c:598
int errposition(int cursorpos)
Definition: elog.c:1125
char * format_elog_string(const char *fmt,...) pg_attribute_printf(1
int sqlerrcode
Definition: elog.h:342
void elog_start(const char *filename, int lineno, const char *funcname)
Definition: elog.c:1298
void errfinish(int dummy,...)
Definition: elog.c:413
const char * funcname
Definition: elog.h:339
void ReThrowError(ErrorData *edata) pg_attribute_noreturn()
Definition: elog.c:1670
ErrorData * CopyErrorData(void)
Definition: elog.c:1497
int int int pg_attribute_printf(2, 4)
char * Log_line_prefix
Definition: elog.c:105
int lineno
Definition: elog.h:338
PGDLLIMPORT sigjmp_buf * PG_exception_stack
Definition: elog.c:90
char * internalquery
Definition: elog.h:356
int int errmsg_internal(const char *fmt,...) pg_attribute_printf(1
int int errhidestmt(bool hide_stmt)
Definition: elog.c:1068
void FreeErrorData(ErrorData *edata)
Definition: elog.c:1551
char struct ErrorContextCallback ErrorContextCallback
struct ErrorContextCallback * previous
Definition: elog.h:238
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:1063
int cursorpos
Definition: elog.h:354
const char * context_domain
Definition: elog.h:341
int errhidecontext(bool hide_ctx)
Definition: elog.c:1087
bool syslog_sequence_numbers
Definition: elog.c:108
char * GetErrorContextStack(void)
Definition: elog.c:1796
const char * filename
Definition: elog.h:337
char * detail_log
Definition: elog.h:345
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:669
int set_errcontext_domain(const char *domain)
Definition: elog.c:1048
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:48
int geterrcode(void)
Definition: elog.c:1240
int geterrposition(void)
Definition: elog.c:1257
int internalerrquery(const char *query)
Definition: elog.c:1161
char * table_name
Definition: elog.h:350
bool output_to_server
Definition: elog.h:332
int internalpos
Definition: elog.h:355
int saved_errno
Definition: elog.h:357
bool hide_ctx
Definition: elog.h:336
bool errstart(int elevel, const char *filename, int lineno, const char *funcname, const char *domain)
Definition: elog.c:233
void ThrowErrorData(ErrorData *edata)
Definition: elog.c:1612
int internalerrposition(int cursorpos)
Definition: elog.c:1141
char * datatype_name
Definition: elog.h:352
int elevel
Definition: elog.h:331
void elog_finish(int elevel, const char *fmt,...) pg_attribute_printf(2
static int elevel
Definition: vacuumlazy.c:136
char * detail
Definition: elog.h:344
void EmitErrorReport(void)
Definition: elog.c:1446
int int errdetail_internal(const char *fmt,...) pg_attribute_printf(1
PGDLLIMPORT emit_log_hook_type emit_log_hook
Definition: elog.c:101
const char * message_id
Definition: elog.h:348
int Log_destination
Definition: elog.c:106
bool show_funcname
Definition: elog.h:334
int errmsg(const char *fmt,...) pg_attribute_printf(1
char * column_name
Definition: elog.h:351
int err_generic_string(int field, const char *str)
Definition: elog.c:1191
int getinternalerrposition(void)
Definition: elog.c:1274
PGErrorVerbosity
Definition: elog.h:380
char * hint
Definition: elog.h:346
void void pre_format_elog_string(int errnumber, const char *domain)
Definition: elog.c:1404
int errcontext_msg(const char *fmt,...) pg_attribute_printf(1
char * context
Definition: elog.h:347
struct MemoryContextData * assoc_context
Definition: elog.h:360
#define pg_attribute_noreturn()
Definition: c.h:653
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:89
bool in_error_recursion_trouble(void)
Definition: elog.c:196
void pg_re_throw(void) pg_attribute_noreturn()
Definition: elog.c:1729
void(* emit_log_hook_type)(ErrorData *edata)
Definition: elog.h:374
void write_stderr(const char *fmt,...) pg_attribute_printf(1
void * arg
bool syslog_split_messages
Definition: elog.c:109
int errfunction(const char *funcname)
Definition: elog.c:1108
void FlushErrorState(void)
Definition: elog.c:1587
int errdetail(const char *fmt,...) pg_attribute_printf(1
int Log_error_verbosity
Definition: elog.c:104
const char * domain
Definition: elog.h:340
char * constraint_name
Definition: elog.h:353
char * Log_destination_string
Definition: elog.c:107
char * unpack_sql_state(int sql_state)
Definition: elog.c:2844
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:333
char * message
Definition: elog.h:343
void DebugFileOpen(void)
Definition: elog.c:1863
PGDLLIMPORT ErrorContextCallback * error_context_stack
Definition: elog.c:88
struct ErrorData ErrorData
int errcode(int sqlerrcode)
Definition: elog.c:575