src/include/utils/elog.h

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