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