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; 249 } ErrorContextCallback; 250 251 extern PGDLLIMPORT ErrorContextCallback *error_context_stack; 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 */ 400 struct MemoryContextData *assoc_context; 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); 415 extern PGDLLIMPORT emit_log_hook_type emit_log_hook; 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 */ 425 } PGErrorVerbosity; 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 */ 457