src/include/utils/elog.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * elog.h
   4  *        POSTGRES error reporting/logging definitions.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * $PostgreSQL$
  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 COMMERROR       16                      /* Client communication problems; same as LOG
  29                                                                  * for server reporting, but never sent to
  30                                                                  * client. */
  31 #define INFO            17                      /* Messages specifically requested by user (eg
  32                                                                  * VACUUM VERBOSE output); always sent to
  33                                                                  * client regardless of client_min_messages,
  34                                                                  * but by default not sent to server log. */
  35 #define NOTICE          18                      /* Helpful messages to users about query
  36                                                                  * operation; sent to client and server log by
  37                                                                  * default. */
  38 #define WARNING         19                      /* Warnings.  NOTICE is for expected messages
  39                                                                  * like implicit sequence creation by SERIAL.
  40                                                                  * WARNING is for unexpected messages. */
  41 #define ERROR           20                      /* user error - abort transaction; return to
  42                                                                  * known state */
  43 /* Save ERROR value in PGERROR so it can be restored when Win32 includes
  44  * modify it.  We have to use a constant rather than ERROR because macros
  45  * are expanded only when referenced outside macros.
  46  */
  47 #ifdef WIN32
  48 #define PGERROR         20
  49 #endif
  50 #define FATAL           21                      /* fatal error - abort process */
  51 #define PANIC           22                      /* take down the other backends with me */
  52
  53  /* #define DEBUG DEBUG1 */     /* Backward compatibility with pre-7.3 */
  54
  55
  56 /* macros for representing SQLSTATE strings compactly */
  57 #define PGSIXBIT(ch)    (((ch) - '0') & 0x3F)
  58 #define PGUNSIXBIT(val) (((val) & 0x3F) + '0')
  59
  60 #define MAKE_SQLSTATE(ch1,ch2,ch3,ch4,ch5)      \
  61         (PGSIXBIT(ch1) + (PGSIXBIT(ch2) << 6) + (PGSIXBIT(ch3) << 12) + \
  62          (PGSIXBIT(ch4) << 18) + (PGSIXBIT(ch5) << 24))
  63
  64 /* These macros depend on the fact that '0' becomes a zero in SIXBIT */
  65 #define ERRCODE_TO_CATEGORY(ec)  ((ec) & ((1 << 12) - 1))
  66 #define ERRCODE_IS_CATEGORY(ec)  (((ec) & ~((1 << 12) - 1)) == 0)
  67
  68 /* SQLSTATE codes for errors are defined in a separate file */
  69 #include "utils/errcodes.h"
  70
  71
  72 /* Which __func__ symbol do we have, if any? */
  73 #ifdef HAVE_FUNCNAME__FUNC
  74 #define PG_FUNCNAME_MACRO       __func__
  75 #else
  76 #ifdef HAVE_FUNCNAME__FUNCTION
  77 #define PG_FUNCNAME_MACRO       __FUNCTION__
  78 #else
  79 #define PG_FUNCNAME_MACRO       NULL
  80 #endif
  81 #endif
  82
  83
  84 /*----------
  85  * New-style error reporting API: to be used in this way:
  86  *              ereport(ERROR,
  87  *                              (errcode(ERRCODE_UNDEFINED_CURSOR),
  88  *                               errmsg("portal \"%s\" not found", stmt->portalname),
  89  *                               ... other errxxx() fields as needed ...));
  90  *
  91  * The error level is required, and so is a primary error message (errmsg
  92  * or errmsg_internal).  All else is optional.  errcode() defaults to
  93  * ERRCODE_INTERNAL_ERROR if elevel is ERROR or more, ERRCODE_WARNING
  94  * if elevel is WARNING, or ERRCODE_SUCCESSFUL_COMPLETION if elevel is
  95  * NOTICE or below.
  96  *
  97  * ereport_domain() allows a message domain to be specified, for modules that
  98  * wish to use a different message catalog from the backend's.  To avoid having
  99  * one copy of the default text domain per .o file, we define it as NULL here
 100  * and have errstart insert the default text domain.  Modules can either use
 101  * ereport_domain() directly, or preferably they can override the TEXTDOMAIN
 102  * macro.
 103  *----------
 104  */
 105 #define ereport_domain(elevel, domain, rest)    \
 106         (errstart(elevel, __FILE__, __LINE__, PG_FUNCNAME_MACRO, domain) ? \
 107          (errfinish rest) : (void) 0)
 108
 109 #define ereport(elevel, rest)   \
 110         ereport_domain(elevel, TEXTDOMAIN, rest)
 111
 112 #define TEXTDOMAIN NULL
 113
 114 extern bool errstart(int elevel, const char *filename, int lineno,
 115                  const char *funcname, const char *domain);
 116 extern void errfinish(int dummy,...);
 117
 118 extern int      errcode(int sqlerrcode);
 119
 120 extern int      errcode_for_file_access(void);
 121 extern int      errcode_for_socket_access(void);
 122
 123 extern int
 124 errmsg(const char *fmt,...)
 125 /* This extension allows gcc to check the format string for consistency with
 126    the supplied arguments. */
 127 __attribute__((format(printf, 1, 2)));
 128
 129 extern int
 130 errmsg_internal(const char *fmt,...)
 131 /* This extension allows gcc to check the format string for consistency with
 132    the supplied arguments. */
 133 __attribute__((format(printf, 1, 2)));
 134
 135 extern int
 136 errmsg_plural(const char *fmt_singular, const char *fmt_plural,
 137                           unsigned long n,...)
 138 /* This extension allows gcc to check the format string for consistency with
 139    the supplied arguments. */
 140 __attribute__((format(printf, 1, 4)))
 141 __attribute__((format(printf, 2, 4)));
 142
 143 extern int
 144 errdetail(const char *fmt,...)
 145 /* This extension allows gcc to check the format string for consistency with
 146    the supplied arguments. */
 147 __attribute__((format(printf, 1, 2)));
 148
 149 extern int
 150 errdetail_log(const char *fmt,...)
 151 /* This extension allows gcc to check the format string for consistency with
 152    the supplied arguments. */
 153 __attribute__((format(printf, 1, 2)));
 154
 155 extern int
 156 errdetail_plural(const char *fmt_singular, const char *fmt_plural,
 157                                  unsigned long n,...)
 158 /* This extension allows gcc to check the format string for consistency with
 159    the supplied arguments. */
 160 __attribute__((format(printf, 1, 4)))
 161 __attribute__((format(printf, 2, 4)));
 162
 163 extern int
 164 errhint(const char *fmt,...)
 165 /* This extension allows gcc to check the format string for consistency with
 166    the supplied arguments. */
 167 __attribute__((format(printf, 1, 2)));
 168
 169 extern int
 170 errcontext(const char *fmt,...)
 171 /* This extension allows gcc to check the format string for consistency with
 172    the supplied arguments. */
 173 __attribute__((format(printf, 1, 2)));
 174
 175 extern int      errhidestmt(bool hide_stmt);
 176
 177 extern int      errfunction(const char *funcname);
 178 extern int      errposition(int cursorpos);
 179
 180 extern int      internalerrposition(int cursorpos);
 181 extern int      internalerrquery(const char *query);
 182
 183 extern int      geterrcode(void);
 184 extern int      geterrposition(void);
 185 extern int      getinternalerrposition(void);
 186
 187
 188 /*----------
 189  * Old-style error reporting API: to be used in this way:
 190  *              elog(ERROR, "portal \"%s\" not found", stmt->portalname);
 191  *----------
 192  */
 193 #define elog    elog_start(__FILE__, __LINE__, PG_FUNCNAME_MACRO), elog_finish
 194
 195 extern void elog_start(const char *filename, int lineno, const char *funcname);
 196 extern void
 197 elog_finish(int elevel, const char *fmt,...)
 198 /* This extension allows gcc to check the format string for consistency with
 199    the supplied arguments. */
 200 __attribute__((format(printf, 2, 3)));
 201
 202
 203 /* Support for attaching context information to error reports */
 204
 205 typedef struct ErrorContextCallback
 206 {
 207         struct ErrorContextCallback *previous;
 208         void            (*callback) (void *arg);
 209         void       *arg;
 210 } ErrorContextCallback;
 211
 212 extern PGDLLIMPORT ErrorContextCallback *error_context_stack;
 213
 214
 215 /*----------
 216  * API for catching ereport(ERROR) exits.  Use these macros like so:
 217  *
 218  *              PG_TRY();
 219  *              {
 220  *                      ... code that might throw ereport(ERROR) ...
 221  *              }
 222  *              PG_CATCH();
 223  *              {
 224  *                      ... error recovery code ...
 225  *              }
 226  *              PG_END_TRY();
 227  *
 228  * (The braces are not actually necessary, but are recommended so that
 229  * pg_indent will indent the construct nicely.)  The error recovery code
 230  * can optionally do PG_RE_THROW() to propagate the same error outwards.
 231  *
 232  * Note: while the system will correctly propagate any new ereport(ERROR)
 233  * occurring in the recovery section, there is a small limit on the number
 234  * of levels this will work for.  It's best to keep the error recovery
 235  * section simple enough that it can't generate any new errors, at least
 236  * not before popping the error stack.
 237  *
 238  * Note: an ereport(FATAL) will not be caught by this construct; control will
 239  * exit straight through proc_exit().  Therefore, do NOT put any cleanup
 240  * of non-process-local resources into the error recovery section, at least
 241  * not without taking thought for what will happen during ereport(FATAL).
 242  * The PG_ENSURE_ERROR_CLEANUP macros provided by storage/ipc.h may be
 243  * helpful in such cases.
 244  *----------
 245  */
 246 #define PG_TRY()  \
 247         do { \
 248                 sigjmp_buf *save_exception_stack = PG_exception_stack; \
 249                 ErrorContextCallback *save_context_stack = error_context_stack; \
 250                 sigjmp_buf local_sigjmp_buf; \
 251                 if (sigsetjmp(local_sigjmp_buf, 0) == 0) \
 252                 { \
 253                         PG_exception_stack = &local_sigjmp_buf
 254
 255 #define PG_CATCH()      \
 256                 } \
 257                 else \
 258                 { \
 259                         PG_exception_stack = save_exception_stack; \
 260                         error_context_stack = save_context_stack
 261
 262 #define PG_END_TRY()  \
 263                 } \
 264                 PG_exception_stack = save_exception_stack; \
 265                 error_context_stack = save_context_stack; \
 266         } while (0)
 267
 268 /*
 269  * gcc understands __attribute__((noreturn)); for other compilers, insert
 270  * a useless exit() call so that the compiler gets the point.
 271  */
 272 #ifdef __GNUC__
 273 #define PG_RE_THROW()  \
 274         pg_re_throw()
 275 #else
 276 #define PG_RE_THROW()  \
 277         (pg_re_throw(), exit(1))
 278 #endif
 279
 280 extern PGDLLIMPORT sigjmp_buf *PG_exception_stack;
 281
 282
 283 /* Stuff that error handlers might want to use */
 284
 285 /*
 286  * ErrorData holds the data accumulated during any one ereport() cycle.
 287  * Any non-NULL pointers must point to palloc'd data.
 288  * (The const pointers are an exception; we assume they point at non-freeable
 289  * constant strings.)
 290  */
 291 typedef struct ErrorData
 292 {
 293         int                     elevel;                 /* error level */
 294         bool            output_to_server;               /* will report to server log? */
 295         bool            output_to_client;               /* will report to client? */
 296         bool            show_funcname;  /* true to force funcname inclusion */
 297         bool            hide_stmt;              /* true to prevent STATEMENT: inclusion */
 298         const char *filename;           /* __FILE__ of ereport() call */
 299         int                     lineno;                 /* __LINE__ of ereport() call */
 300         const char *funcname;           /* __func__ of ereport() call */
 301         const char *domain;                     /* message domain */
 302         int                     sqlerrcode;             /* encoded ERRSTATE */
 303         char       *message;            /* primary error message */
 304         char       *detail;                     /* detail error message */
 305         char       *detail_log;         /* detail error message for server log only */
 306         char       *hint;                       /* hint message */
 307         char       *context;            /* context message */
 308         int                     cursorpos;              /* cursor index into query string */
 309         int                     internalpos;    /* cursor index into internalquery */
 310         char       *internalquery;      /* text of internally-generated query */
 311         int                     saved_errno;    /* errno at entry */
 312 } ErrorData;
 313
 314 extern void EmitErrorReport(void);
 315 extern ErrorData *CopyErrorData(void);
 316 extern void FreeErrorData(ErrorData *edata);
 317 extern void FlushErrorState(void);
 318 extern void ReThrowError(ErrorData *edata);
 319 extern void pg_re_throw(void) __attribute__((noreturn));
 320
 321
 322 /* GUC-configurable parameters */
 323
 324 typedef enum
 325 {
 326         PGERROR_TERSE,                          /* single-line error messages */
 327         PGERROR_DEFAULT,                        /* recommended style */
 328         PGERROR_VERBOSE                         /* all the facts, ma'am */
 329 } PGErrorVerbosity;
 330
 331 extern int      Log_error_verbosity;
 332 extern char *Log_line_prefix;
 333 extern int      Log_destination;
 334
 335 /* Log destination bitmap */
 336 #define LOG_DESTINATION_STDERR   1
 337 #define LOG_DESTINATION_SYSLOG   2
 338 #define LOG_DESTINATION_EVENTLOG 4
 339 #define LOG_DESTINATION_CSVLOG   8
 340
 341 /* Other exported functions */
 342 extern void DebugFileOpen(void);
 343 extern char *unpack_sql_state(int sql_state);
 344 extern bool in_error_recursion_trouble(void);
 345
 346 #ifdef HAVE_SYSLOG
 347 extern void set_syslog_parameters(const char *ident, int facility);
 348 #endif
 349
 350 /*
 351  * Write errors to stderr (or by equal means when stderr is
 352  * not available). Used before ereport/elog can be used
 353  * safely (memory context, GUC load etc)
 354  */
 355 extern void
 356 write_stderr(const char *fmt,...)
 357 /* This extension allows gcc to check the format string for consistency with
 358    the supplied arguments. */
 359 __attribute__((format(printf, 1, 2)));
 360
 361 #endif   /* ELOG_H */