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