granicus.if.org Git - postgresql/blob - src/include/utils/elog.h

   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 PGSIXBIT */
  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
 146 extern bool errstart(int elevel, const char *filename, int lineno,
 147                                          const char *funcname, const char *domain);
 148 extern void errfinish(int dummy,...);
 149
 150 extern int      errcode(int sqlerrcode);
 151
 152 extern int      errcode_for_file_access(void);
 153 extern int      errcode_for_socket_access(void);
 154
 155 extern int      errmsg(const char *fmt,...) pg_attribute_printf(1, 2);
 156 extern int      errmsg_internal(const char *fmt,...) pg_attribute_printf(1, 2);
 157
 158 extern 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
 161 extern int      errdetail(const char *fmt,...) pg_attribute_printf(1, 2);
 162 extern int      errdetail_internal(const char *fmt,...) pg_attribute_printf(1, 2);
 163
 164 extern int      errdetail_log(const char *fmt,...) pg_attribute_printf(1, 2);
 165
 166 extern 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
 170 extern 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
 173 extern 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
 185 extern int      set_errcontext_domain(const char *domain);
 186
 187 extern int      errcontext_msg(const char *fmt,...) pg_attribute_printf(1, 2);
 188
 189 extern int      errhidestmt(bool hide_stmt);
 190 extern int      errhidecontext(bool hide_ctx);
 191
 192 extern int      errfunction(const char *funcname);
 193 extern int      errposition(int cursorpos);
 194
 195 extern int      internalerrposition(int cursorpos);
 196 extern int      internalerrquery(const char *query);
 197
 198 extern int      err_generic_string(int field, const char *str);
 199
 200 extern int      geterrcode(void);
 201 extern int      geterrposition(void);
 202 extern 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
 239 extern void elog_start(const char *filename, int lineno, const char *funcname);
 240 extern 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
 245 extern void pre_format_elog_string(int errnumber, const char *domain);
 246 extern char *format_elog_string(const char *fmt,...) pg_attribute_printf(1, 2);
 247
 248
 249 /* Support for attaching context information to error reports */
 250
 251 typedef struct ErrorContextCallback
 252 {
 253         struct ErrorContextCallback *previous;
 254         void            (*callback) (void *arg);
 255         void       *arg;
 256 } ErrorContextCallback;
 257
 258 extern 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
 335 extern 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  */
 346 typedef 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
 380 extern void EmitErrorReport(void);
 381 extern ErrorData *CopyErrorData(void);
 382 extern void FreeErrorData(ErrorData *edata);
 383 extern void FlushErrorState(void);
 384 extern void ReThrowError(ErrorData *edata) pg_attribute_noreturn();
 385 extern void ThrowErrorData(ErrorData *edata);
 386 extern void pg_re_throw(void) pg_attribute_noreturn();
 387
 388 extern char *GetErrorContextStack(void);
 389
 390 /* Hook for intercepting messages before they are sent to the server log */
 391 typedef void (*emit_log_hook_type) (ErrorData *edata);
 392 extern PGDLLIMPORT emit_log_hook_type emit_log_hook;
 393
 394
 395 /* GUC-configurable parameters */
 396
 397 typedef 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
 404 extern int      Log_error_verbosity;
 405 extern char *Log_line_prefix;
 406 extern int      Log_destination;
 407 extern char *Log_destination_string;
 408 extern bool syslog_sequence_numbers;
 409 extern 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 */
 418 extern void DebugFileOpen(void);
 419 extern char *unpack_sql_state(int sql_state);
 420 extern bool in_error_recursion_trouble(void);
 421
 422 #ifdef HAVE_SYSLOG
 423 extern 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  */
 431 extern void write_stderr(const char *fmt,...) pg_attribute_printf(1, 2);
 432
 433 #endif                                                  /* ELOG_H */