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-2003, 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.71 2004/07/31 00:45:43 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
  27                                                                  * to server log by default. */
  28 #define COMMERROR       16                      /* Client communication problems; same as
  29                                                                  * LOG for server reporting, but never
  30                                                                  * sent to client. */
  31 #define INFO            17                      /* Informative messages that are always
  32                                                                  * sent 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
  36                                                                  * log 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                                                                  */
  41 #define ERROR           20                      /* user error - abort transaction; return
  42                                                                  * to 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 /* SQLSTATE codes for errors are defined in a separate file */
  65 #include "utils/errcodes.h"
  66
  67
  68 /* Which __func__ symbol do we have, if any? */
  69 #ifdef HAVE_FUNCNAME__FUNC
  70 #define PG_FUNCNAME_MACRO       __func__
  71 #else
  72 #ifdef HAVE_FUNCNAME__FUNCTION
  73 #define PG_FUNCNAME_MACRO       __FUNCTION__
  74 #else
  75 #define PG_FUNCNAME_MACRO       NULL
  76 #endif
  77 #endif
  78
  79
  80 /*----------
  81  * New-style error reporting API: to be used in this way:
  82  *              ereport(ERROR,
  83  *                              (errcode(ERRCODE_UNDEFINED_CURSOR),
  84  *                               errmsg("portal \"%s\" not found", stmt->portalname),
  85  *                               ... other errxxx() fields as needed ...));
  86  *
  87  * The error level is required, and so is a primary error message (errmsg
  88  * or errmsg_internal).  All else is optional.  errcode() defaults to
  89  * ERRCODE_INTERNAL_ERROR if elevel is ERROR or more, ERRCODE_WARNING
  90  * if elevel is WARNING, or ERRCODE_SUCCESSFUL_COMPLETION if elevel is
  91  * NOTICE or below.
  92  *----------
  93  */
  94 #define ereport(elevel, rest)  \
  95         (errstart(elevel, __FILE__, __LINE__, PG_FUNCNAME_MACRO) ? \
  96          (errfinish rest) : (void) 0)
  97
  98 extern bool errstart(int elevel, const char *filename, int lineno,
  99                  const char *funcname);
 100 extern void errfinish(int dummy,...);
 101
 102 extern int      errcode(int sqlerrcode);
 103
 104 extern int      errcode_for_file_access(void);
 105 extern int      errcode_for_socket_access(void);
 106
 107 extern int
 108 errmsg(const char *fmt,...)
 109 /* This extension allows gcc to check the format string for consistency with
 110    the supplied arguments. */
 111 __attribute__((format(printf, 1, 2)));
 112
 113 extern int
 114 errmsg_internal(const char *fmt,...)
 115 /* This extension allows gcc to check the format string for consistency with
 116    the supplied arguments. */
 117 __attribute__((format(printf, 1, 2)));
 118
 119 extern int
 120 errdetail(const char *fmt,...)
 121 /* This extension allows gcc to check the format string for consistency with
 122    the supplied arguments. */
 123 __attribute__((format(printf, 1, 2)));
 124
 125 extern int
 126 errhint(const char *fmt,...)
 127 /* This extension allows gcc to check the format string for consistency with
 128    the supplied arguments. */
 129 __attribute__((format(printf, 1, 2)));
 130
 131 extern int
 132 errcontext(const char *fmt,...)
 133 /* This extension allows gcc to check the format string for consistency with
 134    the supplied arguments. */
 135 __attribute__((format(printf, 1, 2)));
 136
 137 extern int      errfunction(const char *funcname);
 138 extern int      errposition(int cursorpos);
 139
 140 extern int      internalerrposition(int cursorpos);
 141 extern int      internalerrquery(const char *query);
 142
 143 extern int      geterrposition(void);
 144 extern int      getinternalerrposition(void);
 145
 146
 147 /*----------
 148  * Old-style error reporting API: to be used in this way:
 149  *              elog(ERROR, "portal \"%s\" not found", stmt->portalname);
 150  *----------
 151  */
 152 #define elog    errstart(ERROR, __FILE__, __LINE__, PG_FUNCNAME_MACRO), elog_finish
 153
 154 extern void
 155 elog_finish(int elevel, const char *fmt,...)
 156 /* This extension allows gcc to check the format string for consistency with
 157    the supplied arguments. */
 158 __attribute__((format(printf, 2, 3)));
 159
 160
 161 /* Support for attaching context information to error reports */
 162
 163 typedef struct ErrorContextCallback
 164 {
 165         struct ErrorContextCallback *previous;
 166         void            (*callback) (void *arg);
 167         void       *arg;
 168 } ErrorContextCallback;
 169
 170 extern DLLIMPORT ErrorContextCallback *error_context_stack;
 171
 172
 173 /*----------
 174  * API for catching ereport(ERROR) exits.  Use these macros like so:
 175  *
 176  *              PG_TRY();
 177  *              {
 178  *                      ... code that might throw ereport(ERROR) ...
 179  *              }
 180  *              PG_CATCH();
 181  *              {
 182  *                      ... error recovery code ...
 183  *              }
 184  *              PG_END_TRY();
 185  *
 186  * (The braces are not actually necessary, but are recommended so that
 187  * pg_indent will indent the construct nicely.)  The error recovery code
 188  * can optionally do PG_RE_THROW() to propagate the same error outwards.
 189  *
 190  * Note: while the system will correctly propagate any new ereport(ERROR)
 191  * occurring in the recovery section, there is a small limit on the number
 192  * of levels this will work for.  It's best to keep the error recovery
 193  * section simple enough that it can't generate any new errors, at least
 194  * not before popping the error stack.
 195  *----------
 196  */
 197 #define PG_TRY()  \
 198         do { \
 199                 sigjmp_buf *save_exception_stack = PG_exception_stack; \
 200                 ErrorContextCallback *save_context_stack = error_context_stack; \
 201                 sigjmp_buf local_sigjmp_buf; \
 202                 if (sigsetjmp(local_sigjmp_buf, 1) == 0) \
 203                 { \
 204                         PG_exception_stack = &local_sigjmp_buf
 205
 206 #define PG_CATCH()  \
 207                 } \
 208                 else \
 209                 { \
 210                         PG_exception_stack = save_exception_stack; \
 211                         error_context_stack = save_context_stack
 212
 213 #define PG_END_TRY()  \
 214                 } \
 215                 PG_exception_stack = save_exception_stack; \
 216                 error_context_stack = save_context_stack; \
 217         } while (0)
 218
 219 #define PG_RE_THROW()  \
 220         siglongjmp(*PG_exception_stack, 1)
 221
 222 extern DLLIMPORT sigjmp_buf *PG_exception_stack;
 223
 224
 225 /* Stuff that error handlers might want to use */
 226
 227 /*
 228  * ErrorData holds the data accumulated during any one ereport() cycle.
 229  * Any non-NULL pointers must point to palloc'd data.
 230  * (The const pointers are an exception; we assume they point at non-freeable
 231  * constant strings.)
 232  */
 233 typedef struct ErrorData
 234 {
 235         int                     elevel;                 /* error level */
 236         bool            output_to_server;               /* will report to server log? */
 237         bool            output_to_client;               /* will report to client? */
 238         bool            show_funcname;  /* true to force funcname inclusion */
 239         const char *filename;           /* __FILE__ of ereport() call */
 240         int                     lineno;                 /* __LINE__ of ereport() call */
 241         const char *funcname;           /* __func__ of ereport() call */
 242         int                     sqlerrcode;             /* encoded ERRSTATE */
 243         char       *message;            /* primary error message */
 244         char       *detail;                     /* detail error message */
 245         char       *hint;                       /* hint message */
 246         char       *context;            /* context message */
 247         int                     cursorpos;              /* cursor index into query string */
 248         int                     internalpos;    /* cursor index into internalquery */
 249         char       *internalquery;      /* text of internally-generated query */
 250         int                     saved_errno;    /* errno at entry */
 251 } ErrorData;
 252
 253 extern void EmitErrorReport(void);
 254 extern ErrorData *CopyErrorData(void);
 255 extern void FreeErrorData(ErrorData *edata);
 256 extern void FlushErrorState(void);
 257 extern void ReThrowError(ErrorData *edata);
 258
 259
 260 /* GUC-configurable parameters */
 261
 262 typedef enum
 263 {
 264         PGERROR_TERSE,                          /* single-line error messages */
 265         PGERROR_DEFAULT,                        /* recommended style */
 266         PGERROR_VERBOSE                         /* all the facts, ma'am */
 267 } PGErrorVerbosity;
 268
 269 extern PGErrorVerbosity Log_error_verbosity;
 270 extern char *Log_line_prefix;
 271 extern unsigned int Log_destination;
 272
 273 /* Log destination bitmap */
 274 #define LOG_DESTINATION_STDERR   1
 275 #define LOG_DESTINATION_SYSLOG   2
 276 #define LOG_DESTINATION_EVENTLOG 4
 277
 278 /* Other exported functions */
 279 extern void DebugFileOpen(void);
 280
 281 /*
 282  * Write errors to stderr (or by equal means when stderr is
 283  * not available). Used before ereport/elog can be used
 284  * safely (memory context, GUC load etc)
 285  */
 286 extern void write_stderr(const char *fmt,...)
 287 /* This extension allows gcc to check the format string for consistency with
 288    the supplied arguments. */
 289 __attribute__((format(printf, 1, 2)));
 290
 291 #endif   /* ELOG_H */