Header And Logo

PostgreSQL
| The world's most advanced open source database.

elog.h

Go to the documentation of this file.
00001 /*-------------------------------------------------------------------------
00002  *
00003  * elog.h
00004  *    POSTGRES error reporting/logging definitions.
00005  *
00006  *
00007  * Portions Copyright (c) 1996-2013, PostgreSQL Global Development Group
00008  * Portions Copyright (c) 1994, Regents of the University of California
00009  *
00010  * src/include/utils/elog.h
00011  *
00012  *-------------------------------------------------------------------------
00013  */
00014 #ifndef ELOG_H
00015 #define ELOG_H
00016 
00017 #include <setjmp.h>
00018 
00019 /* Error level codes */
00020 #define DEBUG5      10          /* Debugging messages, in categories of
00021                                  * decreasing detail. */
00022 #define DEBUG4      11
00023 #define DEBUG3      12
00024 #define DEBUG2      13
00025 #define DEBUG1      14          /* used by GUC debug_* variables */
00026 #define LOG         15          /* Server operational messages; sent only to
00027                                  * server log by default. */
00028 #define COMMERROR   16          /* Client communication problems; same as LOG
00029                                  * for server reporting, but never sent to
00030                                  * client. */
00031 #define INFO        17          /* Messages specifically requested by user (eg
00032                                  * VACUUM VERBOSE output); always sent to
00033                                  * client regardless of client_min_messages,
00034                                  * but by default not sent to server log. */
00035 #define NOTICE      18          /* Helpful messages to users about query
00036                                  * operation; sent to client and server log by
00037                                  * default. */
00038 #define WARNING     19          /* Warnings.  NOTICE is for expected messages
00039                                  * like implicit sequence creation by SERIAL.
00040                                  * WARNING is for unexpected messages. */
00041 #define ERROR       20          /* user error - abort transaction; return to
00042                                  * known state */
00043 /* Save ERROR value in PGERROR so it can be restored when Win32 includes
00044  * modify it.  We have to use a constant rather than ERROR because macros
00045  * are expanded only when referenced outside macros.
00046  */
00047 #ifdef WIN32
00048 #define PGERROR     20
00049 #endif
00050 #define FATAL       21          /* fatal error - abort process */
00051 #define PANIC       22          /* take down the other backends with me */
00052 
00053  /* #define DEBUG DEBUG1 */ /* Backward compatibility with pre-7.3 */
00054 
00055 
00056 /* macros for representing SQLSTATE strings compactly */
00057 #define PGSIXBIT(ch)    (((ch) - '0') & 0x3F)
00058 #define PGUNSIXBIT(val) (((val) & 0x3F) + '0')
00059 
00060 #define MAKE_SQLSTATE(ch1,ch2,ch3,ch4,ch5)  \
00061     (PGSIXBIT(ch1) + (PGSIXBIT(ch2) << 6) + (PGSIXBIT(ch3) << 12) + \
00062      (PGSIXBIT(ch4) << 18) + (PGSIXBIT(ch5) << 24))
00063 
00064 /* These macros depend on the fact that '0' becomes a zero in SIXBIT */
00065 #define ERRCODE_TO_CATEGORY(ec)  ((ec) & ((1 << 12) - 1))
00066 #define ERRCODE_IS_CATEGORY(ec)  (((ec) & ~((1 << 12) - 1)) == 0)
00067 
00068 /* SQLSTATE codes for errors are defined in a separate file */
00069 #include "utils/errcodes.h"
00070 
00071 
00072 /* Which __func__ symbol do we have, if any? */
00073 #ifdef HAVE_FUNCNAME__FUNC
00074 #define PG_FUNCNAME_MACRO   __func__
00075 #else
00076 #ifdef HAVE_FUNCNAME__FUNCTION
00077 #define PG_FUNCNAME_MACRO   __FUNCTION__
00078 #else
00079 #define PG_FUNCNAME_MACRO   NULL
00080 #endif
00081 #endif
00082 
00083 
00084 /*----------
00085  * New-style error reporting API: to be used in this way:
00086  *      ereport(ERROR,
00087  *              (errcode(ERRCODE_UNDEFINED_CURSOR),
00088  *               errmsg("portal \"%s\" not found", stmt->portalname),
00089  *               ... other errxxx() fields as needed ...));
00090  *
00091  * The error level is required, and so is a primary error message (errmsg
00092  * or errmsg_internal).  All else is optional.  errcode() defaults to
00093  * ERRCODE_INTERNAL_ERROR if elevel is ERROR or more, ERRCODE_WARNING
00094  * if elevel is WARNING, or ERRCODE_SUCCESSFUL_COMPLETION if elevel is
00095  * NOTICE or below.
00096  *
00097  * ereport_domain() allows a message domain to be specified, for modules that
00098  * wish to use a different message catalog from the backend's.  To avoid having
00099  * one copy of the default text domain per .o file, we define it as NULL here
00100  * and have errstart insert the default text domain.  Modules can either use
00101  * ereport_domain() directly, or preferably they can override the TEXTDOMAIN
00102  * macro.
00103  *
00104  * If elevel >= ERROR, the call will not return; we try to inform the compiler
00105  * of that via pg_unreachable().  However, no useful optimization effect is
00106  * obtained unless the compiler sees elevel as a compile-time constant, else
00107  * we're just adding code bloat.  So, if __builtin_constant_p is available,
00108  * use that to cause the second if() to vanish completely for non-constant
00109  * cases.  We avoid using a local variable because it's not necessary and
00110  * prevents gcc from making the unreachability deduction at optlevel -O0.
00111  *----------
00112  */
00113 #ifdef HAVE__BUILTIN_CONSTANT_P
00114 #define ereport_domain(elevel, domain, rest)    \
00115     do { \
00116         if (errstart(elevel, __FILE__, __LINE__, PG_FUNCNAME_MACRO, domain)) \
00117             errfinish rest; \
00118         if (__builtin_constant_p(elevel) && (elevel) >= ERROR) \
00119             pg_unreachable(); \
00120     } while(0)
00121 #else /* !HAVE__BUILTIN_CONSTANT_P */
00122 #define ereport_domain(elevel, domain, rest)    \
00123     do { \
00124         const int elevel_ = (elevel); \
00125         if (errstart(elevel_, __FILE__, __LINE__, PG_FUNCNAME_MACRO, domain)) \
00126             errfinish rest; \
00127         if (elevel_ >= ERROR) \
00128             pg_unreachable(); \
00129     } while(0)
00130 #endif /* HAVE__BUILTIN_CONSTANT_P */
00131 
00132 #define ereport(elevel, rest)   \
00133     ereport_domain(elevel, TEXTDOMAIN, rest)
00134 
00135 #define TEXTDOMAIN NULL
00136 
00137 extern bool errstart(int elevel, const char *filename, int lineno,
00138          const char *funcname, const char *domain);
00139 extern void errfinish(int dummy,...);
00140 
00141 extern int  errcode(int sqlerrcode);
00142 
00143 extern int  errcode_for_file_access(void);
00144 extern int  errcode_for_socket_access(void);
00145 
00146 extern int
00147 errmsg(const char *fmt,...)
00148 /* This extension allows gcc to check the format string for consistency with
00149    the supplied arguments. */
00150 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 2)));
00151 
00152 extern int
00153 errmsg_internal(const char *fmt,...)
00154 /* This extension allows gcc to check the format string for consistency with
00155    the supplied arguments. */
00156 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 2)));
00157 
00158 extern int
00159 errmsg_plural(const char *fmt_singular, const char *fmt_plural,
00160               unsigned long n,...)
00161 /* This extension allows gcc to check the format string for consistency with
00162    the supplied arguments. */
00163 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 4)))
00164 __attribute__((format(PG_PRINTF_ATTRIBUTE, 2, 4)));
00165 
00166 extern int
00167 errdetail(const char *fmt,...)
00168 /* This extension allows gcc to check the format string for consistency with
00169    the supplied arguments. */
00170 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 2)));
00171 
00172 extern int
00173 errdetail_internal(const char *fmt,...)
00174 /* This extension allows gcc to check the format string for consistency with
00175    the supplied arguments. */
00176 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 2)));
00177 
00178 extern int
00179 errdetail_log(const char *fmt,...)
00180 /* This extension allows gcc to check the format string for consistency with
00181    the supplied arguments. */
00182 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 2)));
00183 
00184 extern int
00185 errdetail_plural(const char *fmt_singular, const char *fmt_plural,
00186                  unsigned long n,...)
00187 /* This extension allows gcc to check the format string for consistency with
00188    the supplied arguments. */
00189 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 4)))
00190 __attribute__((format(PG_PRINTF_ATTRIBUTE, 2, 4)));
00191 
00192 extern int
00193 errhint(const char *fmt,...)
00194 /* This extension allows gcc to check the format string for consistency with
00195    the supplied arguments. */
00196 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 2)));
00197 
00198 /*
00199  * errcontext() is typically called in error context callback functions, not
00200  * within an ereport() invocation. The callback function can be in a different
00201  * module than the ereport() call, so the message domain passed in errstart()
00202  * is not usually the correct domain for translating the context message.
00203  * set_errcontext_domain() first sets the domain to be used, and
00204  * errcontext_msg() passes the actual message.
00205  */
00206 #define errcontext  set_errcontext_domain(TEXTDOMAIN),  errcontext_msg
00207 
00208 extern int  set_errcontext_domain(const char *domain);
00209 extern int
00210 errcontext_msg(const char *fmt,...)
00211 /* This extension allows gcc to check the format string for consistency with
00212    the supplied arguments. */
00213 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 2)));
00214 
00215 extern int  errhidestmt(bool hide_stmt);
00216 
00217 extern int  errfunction(const char *funcname);
00218 extern int  errposition(int cursorpos);
00219 
00220 extern int  internalerrposition(int cursorpos);
00221 extern int  internalerrquery(const char *query);
00222 
00223 extern int  err_generic_string(int field, const char *str);
00224 
00225 extern int  geterrcode(void);
00226 extern int  geterrposition(void);
00227 extern int  getinternalerrposition(void);
00228 
00229 
00230 /*----------
00231  * Old-style error reporting API: to be used in this way:
00232  *      elog(ERROR, "portal \"%s\" not found", stmt->portalname);
00233  *----------
00234  */
00235 #ifdef HAVE__VA_ARGS
00236 /*
00237  * If we have variadic macros, we can give the compiler a hint about the
00238  * call not returning when elevel >= ERROR.  See comments for ereport().
00239  * Note that historically elog() has called elog_start (which saves errno)
00240  * before evaluating "elevel", so we preserve that behavior here.
00241  */
00242 #ifdef HAVE__BUILTIN_CONSTANT_P
00243 #define elog(elevel, ...)  \
00244     do { \
00245         elog_start(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
00246         elog_finish(elevel, __VA_ARGS__); \
00247         if (__builtin_constant_p(elevel) && (elevel) >= ERROR) \
00248             pg_unreachable(); \
00249     } while(0)
00250 #else /* !HAVE__BUILTIN_CONSTANT_P */
00251 #define elog(elevel, ...)  \
00252     do { \
00253         int     elevel_; \
00254         elog_start(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
00255         elevel_ = (elevel); \
00256         elog_finish(elevel_, __VA_ARGS__); \
00257         if (elevel_ >= ERROR) \
00258             pg_unreachable(); \
00259     } while(0)
00260 #endif /* HAVE__BUILTIN_CONSTANT_P */
00261 #else /* !HAVE__VA_ARGS */
00262 #define elog  \
00263     elog_start(__FILE__, __LINE__, PG_FUNCNAME_MACRO), \
00264     elog_finish
00265 #endif /* HAVE__VA_ARGS */
00266 
00267 extern void elog_start(const char *filename, int lineno, const char *funcname);
00268 extern void
00269 elog_finish(int elevel, const char *fmt,...)
00270 /* This extension allows gcc to check the format string for consistency with
00271    the supplied arguments. */
00272 __attribute__((format(PG_PRINTF_ATTRIBUTE, 2, 3)));
00273 
00274 
00275 /* Support for constructing error strings separately from ereport() calls */
00276 
00277 extern void pre_format_elog_string(int errnumber, const char *domain);
00278 extern char *
00279 format_elog_string(const char *fmt,...)
00280 /* This extension allows gcc to check the format string for consistency with
00281    the supplied arguments. */
00282 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 2)));
00283 
00284 
00285 /* Support for attaching context information to error reports */
00286 
00287 typedef struct ErrorContextCallback
00288 {
00289     struct ErrorContextCallback *previous;
00290     void        (*callback) (void *arg);
00291     void       *arg;
00292 } ErrorContextCallback;
00293 
00294 extern PGDLLIMPORT ErrorContextCallback *error_context_stack;
00295 
00296 
00297 /*----------
00298  * API for catching ereport(ERROR) exits.  Use these macros like so:
00299  *
00300  *      PG_TRY();
00301  *      {
00302  *          ... code that might throw ereport(ERROR) ...
00303  *      }
00304  *      PG_CATCH();
00305  *      {
00306  *          ... error recovery code ...
00307  *      }
00308  *      PG_END_TRY();
00309  *
00310  * (The braces are not actually necessary, but are recommended so that
00311  * pg_indent will indent the construct nicely.)  The error recovery code
00312  * can optionally do PG_RE_THROW() to propagate the same error outwards.
00313  *
00314  * Note: while the system will correctly propagate any new ereport(ERROR)
00315  * occurring in the recovery section, there is a small limit on the number
00316  * of levels this will work for.  It's best to keep the error recovery
00317  * section simple enough that it can't generate any new errors, at least
00318  * not before popping the error stack.
00319  *
00320  * Note: an ereport(FATAL) will not be caught by this construct; control will
00321  * exit straight through proc_exit().  Therefore, do NOT put any cleanup
00322  * of non-process-local resources into the error recovery section, at least
00323  * not without taking thought for what will happen during ereport(FATAL).
00324  * The PG_ENSURE_ERROR_CLEANUP macros provided by storage/ipc.h may be
00325  * helpful in such cases.
00326  *----------
00327  */
00328 #define PG_TRY()  \
00329     do { \
00330         sigjmp_buf *save_exception_stack = PG_exception_stack; \
00331         ErrorContextCallback *save_context_stack = error_context_stack; \
00332         sigjmp_buf local_sigjmp_buf; \
00333         if (sigsetjmp(local_sigjmp_buf, 0) == 0) \
00334         { \
00335             PG_exception_stack = &local_sigjmp_buf
00336 
00337 #define PG_CATCH()  \
00338         } \
00339         else \
00340         { \
00341             PG_exception_stack = save_exception_stack; \
00342             error_context_stack = save_context_stack
00343 
00344 #define PG_END_TRY()  \
00345         } \
00346         PG_exception_stack = save_exception_stack; \
00347         error_context_stack = save_context_stack; \
00348     } while (0)
00349 
00350 /*
00351  * gcc understands __attribute__((noreturn)); for other compilers, insert
00352  * pg_unreachable() so that the compiler gets the point.
00353  */
00354 #ifdef __GNUC__
00355 #define PG_RE_THROW()  \
00356     pg_re_throw()
00357 #else
00358 #define PG_RE_THROW()  \
00359     (pg_re_throw(), pg_unreachable())
00360 #endif
00361 
00362 extern PGDLLIMPORT sigjmp_buf *PG_exception_stack;
00363 
00364 
00365 /* Stuff that error handlers might want to use */
00366 
00367 /*
00368  * ErrorData holds the data accumulated during any one ereport() cycle.
00369  * Any non-NULL pointers must point to palloc'd data.
00370  * (The const pointers are an exception; we assume they point at non-freeable
00371  * constant strings.)
00372  */
00373 typedef struct ErrorData
00374 {
00375     int         elevel;         /* error level */
00376     bool        output_to_server;       /* will report to server log? */
00377     bool        output_to_client;       /* will report to client? */
00378     bool        show_funcname;  /* true to force funcname inclusion */
00379     bool        hide_stmt;      /* true to prevent STATEMENT: inclusion */
00380     const char *filename;       /* __FILE__ of ereport() call */
00381     int         lineno;         /* __LINE__ of ereport() call */
00382     const char *funcname;       /* __func__ of ereport() call */
00383     const char *domain;         /* message domain */
00384     const char *context_domain; /* message domain for context message */
00385     int         sqlerrcode;     /* encoded ERRSTATE */
00386     char       *message;        /* primary error message */
00387     char       *detail;         /* detail error message */
00388     char       *detail_log;     /* detail error message for server log only */
00389     char       *hint;           /* hint message */
00390     char       *context;        /* context message */
00391     char       *schema_name;    /* name of schema */
00392     char       *table_name;     /* name of table */
00393     char       *column_name;    /* name of column */
00394     char       *datatype_name;  /* name of datatype */
00395     char       *constraint_name;    /* name of constraint */
00396     int         cursorpos;      /* cursor index into query string */
00397     int         internalpos;    /* cursor index into internalquery */
00398     char       *internalquery;  /* text of internally-generated query */
00399     int         saved_errno;    /* errno at entry */
00400 } ErrorData;
00401 
00402 extern void EmitErrorReport(void);
00403 extern ErrorData *CopyErrorData(void);
00404 extern void FreeErrorData(ErrorData *edata);
00405 extern void FlushErrorState(void);
00406 extern void ReThrowError(ErrorData *edata) __attribute__((noreturn));
00407 extern void pg_re_throw(void) __attribute__((noreturn));
00408 
00409 /* Hook for intercepting messages before they are sent to the server log */
00410 typedef void (*emit_log_hook_type) (ErrorData *edata);
00411 extern PGDLLIMPORT emit_log_hook_type emit_log_hook;
00412 
00413 
00414 /* GUC-configurable parameters */
00415 
00416 typedef enum
00417 {
00418     PGERROR_TERSE,              /* single-line error messages */
00419     PGERROR_DEFAULT,            /* recommended style */
00420     PGERROR_VERBOSE             /* all the facts, ma'am */
00421 }   PGErrorVerbosity;
00422 
00423 extern int  Log_error_verbosity;
00424 extern char *Log_line_prefix;
00425 extern int  Log_destination;
00426 
00427 /* Log destination bitmap */
00428 #define LOG_DESTINATION_STDERR   1
00429 #define LOG_DESTINATION_SYSLOG   2
00430 #define LOG_DESTINATION_EVENTLOG 4
00431 #define LOG_DESTINATION_CSVLOG   8
00432 
00433 /* Other exported functions */
00434 extern void DebugFileOpen(void);
00435 extern char *unpack_sql_state(int sql_state);
00436 extern bool in_error_recursion_trouble(void);
00437 
00438 #ifdef HAVE_SYSLOG
00439 extern void set_syslog_parameters(const char *ident, int facility);
00440 #endif
00441 
00442 /*
00443  * Write errors to stderr (or by equal means when stderr is
00444  * not available). Used before ereport/elog can be used
00445  * safely (memory context, GUC load etc)
00446  */
00447 extern void
00448 write_stderr(const char *fmt,...)
00449 /* This extension allows gcc to check the format string for consistency with
00450    the supplied arguments. */
00451 __attribute__((format(PG_PRINTF_ATTRIBUTE, 1, 2)));
00452 
00453 #endif   /* ELOG_H */