elog.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470
  1. /*-------------------------------------------------------------------------
  2. *
  3. * elog.h
  4. * POSTGRES error reporting/logging definitions.
  5. *
  6. *
  7. * Portions Copyright (c) 1996-2022, 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. #include <setjmp.h>
  17. /* Error level codes */
  18. #define DEBUG5 10 /* Debugging messages, in categories of
  19. * decreasing detail. */
  20. #define DEBUG4 11
  21. #define DEBUG3 12
  22. #define DEBUG2 13
  23. #define DEBUG1 14 /* used by GUC debug_* variables */
  24. #define LOG 15 /* Server operational messages; sent only to
  25. * server log by default. */
  26. #define LOG_SERVER_ONLY 16 /* Same as LOG for server reporting, but never
  27. * sent to client. */
  28. #define COMMERROR LOG_SERVER_ONLY /* Client communication problems; same as
  29. * LOG for server reporting, but never
  30. * sent to 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 not to server
  37. * log by 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 PGWARNING 19 /* Must equal WARNING; see NOTE below. */
  42. #define WARNING_CLIENT_ONLY 20 /* Warnings to be sent to client as usual, but
  43. * never to the server log. */
  44. #define ERROR 21 /* user error - abort transaction; return to
  45. * known state */
  46. #define PGERROR 21 /* Must equal ERROR; see NOTE below. */
  47. #define FATAL 22 /* fatal error - abort process */
  48. #define PANIC 23 /* take down the other backends with me */
  49. /*
  50. * NOTE: the alternate names PGWARNING and PGERROR are useful for dealing
  51. * with third-party headers that make other definitions of WARNING and/or
  52. * ERROR. One can, for example, re-define ERROR as PGERROR after including
  53. * such a header.
  54. */
  55. /* macros for representing SQLSTATE strings compactly */
  56. #define PGSIXBIT(ch) (((ch) - '0') & 0x3F)
  57. #define PGUNSIXBIT(val) (((val) & 0x3F) + '0')
  58. #define MAKE_SQLSTATE(ch1,ch2,ch3,ch4,ch5) \
  59. (PGSIXBIT(ch1) + (PGSIXBIT(ch2) << 6) + (PGSIXBIT(ch3) << 12) + \
  60. (PGSIXBIT(ch4) << 18) + (PGSIXBIT(ch5) << 24))
  61. /* These macros depend on the fact that '0' becomes a zero in PGSIXBIT */
  62. #define ERRCODE_TO_CATEGORY(ec) ((ec) & ((1 << 12) - 1))
  63. #define ERRCODE_IS_CATEGORY(ec) (((ec) & ~((1 << 12) - 1)) == 0)
  64. /* SQLSTATE codes for errors are defined in a separate file */
  65. #include "utils/errcodes.h"
  66. /*
  67. * Provide a way to prevent "errno" from being accidentally used inside an
  68. * elog() or ereport() invocation. Since we know that some operating systems
  69. * define errno as something involving a function call, we'll put a local
  70. * variable of the same name as that function in the local scope to force a
  71. * compile error. On platforms that don't define errno in that way, nothing
  72. * happens, so we get no warning ... but we can live with that as long as it
  73. * happens on some popular platforms.
  74. */
  75. #if defined(errno) && defined(__linux__)
  76. #define pg_prevent_errno_in_scope() int __errno_location pg_attribute_unused()
  77. #elif defined(errno) && (defined(__darwin__) || defined(__freebsd__))
  78. #define pg_prevent_errno_in_scope() int __error pg_attribute_unused()
  79. #else
  80. #define pg_prevent_errno_in_scope()
  81. #endif
  82. /*----------
  83. * New-style error reporting API: to be used in this way:
  84. * ereport(ERROR,
  85. * errcode(ERRCODE_UNDEFINED_CURSOR),
  86. * errmsg("portal \"%s\" not found", stmt->portalname),
  87. * ... other errxxx() fields as needed ...);
  88. *
  89. * The error level is required, and so is a primary error message (errmsg
  90. * or errmsg_internal). All else is optional. errcode() defaults to
  91. * ERRCODE_INTERNAL_ERROR if elevel is ERROR or more, ERRCODE_WARNING
  92. * if elevel is WARNING, or ERRCODE_SUCCESSFUL_COMPLETION if elevel is
  93. * NOTICE or below.
  94. *
  95. * Before Postgres v12, extra parentheses were required around the
  96. * list of auxiliary function calls; that's now optional.
  97. *
  98. * ereport_domain() allows a message domain to be specified, for modules that
  99. * wish to use a different message catalog from the backend's. To avoid having
  100. * one copy of the default text domain per .o file, we define it as NULL here
  101. * and have errstart insert the default text domain. Modules can either use
  102. * ereport_domain() directly, or preferably they can override the TEXTDOMAIN
  103. * macro.
  104. *
  105. * When __builtin_constant_p is available and elevel >= ERROR we make a call
  106. * to errstart_cold() instead of errstart(). This version of the function is
  107. * marked with pg_attribute_cold which will coax supporting compilers into
  108. * generating code which is more optimized towards non-ERROR cases. Because
  109. * we use __builtin_constant_p() in the condition, when elevel is not a
  110. * compile-time constant, or if it is, but it's < ERROR, the compiler has no
  111. * need to generate any code for this branch. It can simply call errstart()
  112. * unconditionally.
  113. *
  114. * If elevel >= ERROR, the call will not return; we try to inform the compiler
  115. * of that via pg_unreachable(). However, no useful optimization effect is
  116. * obtained unless the compiler sees elevel as a compile-time constant, else
  117. * we're just adding code bloat. So, if __builtin_constant_p is available,
  118. * use that to cause the second if() to vanish completely for non-constant
  119. * cases. We avoid using a local variable because it's not necessary and
  120. * prevents gcc from making the unreachability deduction at optlevel -O0.
  121. *----------
  122. */
  123. #ifdef HAVE__BUILTIN_CONSTANT_P
  124. #define ereport_domain(elevel, domain, ...) \
  125. do { \
  126. pg_prevent_errno_in_scope(); \
  127. if (__builtin_constant_p(elevel) && (elevel) >= ERROR ? \
  128. errstart_cold(elevel, domain) : \
  129. errstart(elevel, domain)) \
  130. __VA_ARGS__, errfinish(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
  131. if (__builtin_constant_p(elevel) && (elevel) >= ERROR) \
  132. pg_unreachable(); \
  133. } while(0)
  134. #else /* !HAVE__BUILTIN_CONSTANT_P */
  135. #define ereport_domain(elevel, domain, ...) \
  136. do { \
  137. const int elevel_ = (elevel); \
  138. pg_prevent_errno_in_scope(); \
  139. if (errstart(elevel_, domain)) \
  140. __VA_ARGS__, errfinish(__FILE__, __LINE__, PG_FUNCNAME_MACRO); \
  141. if (elevel_ >= ERROR) \
  142. pg_unreachable(); \
  143. } while(0)
  144. #endif /* HAVE__BUILTIN_CONSTANT_P */
  145. #define ereport(elevel, ...) \
  146. ereport_domain(elevel, TEXTDOMAIN, __VA_ARGS__)
  147. #define TEXTDOMAIN NULL
  148. extern bool message_level_is_interesting(int elevel);
  149. extern bool errstart(int elevel, const char *domain);
  150. extern pg_attribute_cold bool errstart_cold(int elevel, const char *domain);
  151. extern void errfinish(const char *filename, int lineno, const char *funcname);
  152. extern int errcode(int sqlerrcode);
  153. extern int errcode_for_file_access(void);
  154. extern int errcode_for_socket_access(void);
  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. extern int errmsg_plural(const char *fmt_singular, const char *fmt_plural,
  158. unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
  159. extern int errdetail(const char *fmt,...) pg_attribute_printf(1, 2);
  160. extern int errdetail_internal(const char *fmt,...) pg_attribute_printf(1, 2);
  161. extern int errdetail_log(const char *fmt,...) pg_attribute_printf(1, 2);
  162. extern int errdetail_log_plural(const char *fmt_singular,
  163. const char *fmt_plural,
  164. unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
  165. extern int errdetail_plural(const char *fmt_singular, const char *fmt_plural,
  166. unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
  167. extern int errhint(const char *fmt,...) pg_attribute_printf(1, 2);
  168. extern int errhint_plural(const char *fmt_singular, const char *fmt_plural,
  169. unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);
  170. /*
  171. * errcontext() is typically called in error context callback functions, not
  172. * within an ereport() invocation. The callback function can be in a different
  173. * module than the ereport() call, so the message domain passed in errstart()
  174. * is not usually the correct domain for translating the context message.
  175. * set_errcontext_domain() first sets the domain to be used, and
  176. * errcontext_msg() passes the actual message.
  177. */
  178. #define errcontext set_errcontext_domain(TEXTDOMAIN), errcontext_msg
  179. extern int set_errcontext_domain(const char *domain);
  180. extern int errcontext_msg(const char *fmt,...) pg_attribute_printf(1, 2);
  181. extern int errhidestmt(bool hide_stmt);
  182. extern int errhidecontext(bool hide_ctx);
  183. extern int errbacktrace(void);
  184. extern int errposition(int cursorpos);
  185. extern int internalerrposition(int cursorpos);
  186. extern int internalerrquery(const char *query);
  187. extern int err_generic_string(int field, const char *str);
  188. extern int geterrcode(void);
  189. extern int geterrposition(void);
  190. extern int getinternalerrposition(void);
  191. /*----------
  192. * Old-style error reporting API: to be used in this way:
  193. * elog(ERROR, "portal \"%s\" not found", stmt->portalname);
  194. *----------
  195. */
  196. #define elog(elevel, ...) \
  197. ereport(elevel, errmsg_internal(__VA_ARGS__))
  198. /* Support for constructing error strings separately from ereport() calls */
  199. extern void pre_format_elog_string(int errnumber, const char *domain);
  200. extern char *format_elog_string(const char *fmt,...) pg_attribute_printf(1, 2);
  201. /* Support for attaching context information to error reports */
  202. typedef struct ErrorContextCallback
  203. {
  204. struct ErrorContextCallback *previous;
  205. void (*callback) (void *arg);
  206. void *arg;
  207. } ErrorContextCallback;
  208. extern PGDLLIMPORT ErrorContextCallback *error_context_stack;
  209. /*----------
  210. * API for catching ereport(ERROR) exits. Use these macros like so:
  211. *
  212. * PG_TRY();
  213. * {
  214. * ... code that might throw ereport(ERROR) ...
  215. * }
  216. * PG_CATCH();
  217. * {
  218. * ... error recovery code ...
  219. * }
  220. * PG_END_TRY();
  221. *
  222. * (The braces are not actually necessary, but are recommended so that
  223. * pgindent will indent the construct nicely.) The error recovery code
  224. * can either do PG_RE_THROW to propagate the error outwards, or do a
  225. * (sub)transaction abort. Failure to do so may leave the system in an
  226. * inconsistent state for further processing.
  227. *
  228. * For the common case that the error recovery code and the cleanup in the
  229. * normal code path are identical, the following can be used instead:
  230. *
  231. * PG_TRY();
  232. * {
  233. * ... code that might throw ereport(ERROR) ...
  234. * }
  235. * PG_FINALLY();
  236. * {
  237. * ... cleanup code ...
  238. * }
  239. * PG_END_TRY();
  240. *
  241. * The cleanup code will be run in either case, and any error will be rethrown
  242. * afterwards.
  243. *
  244. * You cannot use both PG_CATCH() and PG_FINALLY() in the same
  245. * PG_TRY()/PG_END_TRY() block.
  246. *
  247. * Note: while the system will correctly propagate any new ereport(ERROR)
  248. * occurring in the recovery section, there is a small limit on the number
  249. * of levels this will work for. It's best to keep the error recovery
  250. * section simple enough that it can't generate any new errors, at least
  251. * not before popping the error stack.
  252. *
  253. * Note: an ereport(FATAL) will not be caught by this construct; control will
  254. * exit straight through proc_exit(). Therefore, do NOT put any cleanup
  255. * of non-process-local resources into the error recovery section, at least
  256. * not without taking thought for what will happen during ereport(FATAL).
  257. * The PG_ENSURE_ERROR_CLEANUP macros provided by storage/ipc.h may be
  258. * helpful in such cases.
  259. *
  260. * Note: if a local variable of the function containing PG_TRY is modified
  261. * in the PG_TRY section and used in the PG_CATCH section, that variable
  262. * must be declared "volatile" for POSIX compliance. This is not mere
  263. * pedantry; we have seen bugs from compilers improperly optimizing code
  264. * away when such a variable was not marked. Beware that gcc's -Wclobbered
  265. * warnings are just about entirely useless for catching such oversights.
  266. *----------
  267. */
  268. #define PG_TRY() \
  269. do { \
  270. sigjmp_buf *_save_exception_stack = PG_exception_stack; \
  271. ErrorContextCallback *_save_context_stack = error_context_stack; \
  272. sigjmp_buf _local_sigjmp_buf; \
  273. bool _do_rethrow = false; \
  274. if (sigsetjmp(_local_sigjmp_buf, 0) == 0) \
  275. { \
  276. PG_exception_stack = &_local_sigjmp_buf
  277. #define PG_CATCH() \
  278. } \
  279. else \
  280. { \
  281. PG_exception_stack = _save_exception_stack; \
  282. error_context_stack = _save_context_stack
  283. #define PG_FINALLY() \
  284. } \
  285. else \
  286. _do_rethrow = true; \
  287. { \
  288. PG_exception_stack = _save_exception_stack; \
  289. error_context_stack = _save_context_stack
  290. #define PG_END_TRY() \
  291. } \
  292. if (_do_rethrow) \
  293. PG_RE_THROW(); \
  294. PG_exception_stack = _save_exception_stack; \
  295. error_context_stack = _save_context_stack; \
  296. } while (0)
  297. /*
  298. * Some compilers understand pg_attribute_noreturn(); for other compilers,
  299. * insert pg_unreachable() so that the compiler gets the point.
  300. */
  301. #ifdef HAVE_PG_ATTRIBUTE_NORETURN
  302. #define PG_RE_THROW() \
  303. pg_re_throw()
  304. #else
  305. #define PG_RE_THROW() \
  306. (pg_re_throw(), pg_unreachable())
  307. #endif
  308. extern PGDLLIMPORT sigjmp_buf *PG_exception_stack;
  309. /* Stuff that error handlers might want to use */
  310. /*
  311. * ErrorData holds the data accumulated during any one ereport() cycle.
  312. * Any non-NULL pointers must point to palloc'd data.
  313. * (The const pointers are an exception; we assume they point at non-freeable
  314. * constant strings.)
  315. */
  316. typedef struct ErrorData
  317. {
  318. int elevel; /* error level */
  319. bool output_to_server; /* will report to server log? */
  320. bool output_to_client; /* will report to client? */
  321. bool hide_stmt; /* true to prevent STATEMENT: inclusion */
  322. bool hide_ctx; /* true to prevent CONTEXT: inclusion */
  323. const char *filename; /* __FILE__ of ereport() call */
  324. int lineno; /* __LINE__ of ereport() call */
  325. const char *funcname; /* __func__ of ereport() call */
  326. const char *domain; /* message domain */
  327. const char *context_domain; /* message domain for context message */
  328. int sqlerrcode; /* encoded ERRSTATE */
  329. char *message; /* primary error message (translated) */
  330. char *detail; /* detail error message */
  331. char *detail_log; /* detail error message for server log only */
  332. char *hint; /* hint message */
  333. char *context; /* context message */
  334. char *backtrace; /* backtrace */
  335. const char *message_id; /* primary message's id (original string) */
  336. char *schema_name; /* name of schema */
  337. char *table_name; /* name of table */
  338. char *column_name; /* name of column */
  339. char *datatype_name; /* name of datatype */
  340. char *constraint_name; /* name of constraint */
  341. int cursorpos; /* cursor index into query string */
  342. int internalpos; /* cursor index into internalquery */
  343. char *internalquery; /* text of internally-generated query */
  344. int saved_errno; /* errno at entry */
  345. /* context containing associated non-constant strings */
  346. struct MemoryContextData *assoc_context;
  347. } ErrorData;
  348. extern void EmitErrorReport(void);
  349. extern ErrorData *CopyErrorData(void);
  350. extern void FreeErrorData(ErrorData *edata);
  351. extern void FlushErrorState(void);
  352. extern void ReThrowError(ErrorData *edata) pg_attribute_noreturn();
  353. extern void ThrowErrorData(ErrorData *edata);
  354. extern void pg_re_throw(void) pg_attribute_noreturn();
  355. extern char *GetErrorContextStack(void);
  356. /* Hook for intercepting messages before they are sent to the server log */
  357. typedef void (*emit_log_hook_type) (ErrorData *edata);
  358. extern PGDLLIMPORT emit_log_hook_type emit_log_hook;
  359. /* GUC-configurable parameters */
  360. typedef enum
  361. {
  362. PGERROR_TERSE, /* single-line error messages */
  363. PGERROR_DEFAULT, /* recommended style */
  364. PGERROR_VERBOSE /* all the facts, ma'am */
  365. } PGErrorVerbosity;
  366. extern PGDLLIMPORT int Log_error_verbosity;
  367. extern PGDLLIMPORT char *Log_line_prefix;
  368. extern PGDLLIMPORT int Log_destination;
  369. extern PGDLLIMPORT char *Log_destination_string;
  370. extern PGDLLIMPORT bool syslog_sequence_numbers;
  371. extern PGDLLIMPORT bool syslog_split_messages;
  372. /* Log destination bitmap */
  373. #define LOG_DESTINATION_STDERR 1
  374. #define LOG_DESTINATION_SYSLOG 2
  375. #define LOG_DESTINATION_EVENTLOG 4
  376. #define LOG_DESTINATION_CSVLOG 8
  377. #define LOG_DESTINATION_JSONLOG 16
  378. /* Other exported functions */
  379. extern void DebugFileOpen(void);
  380. extern char *unpack_sql_state(int sql_state);
  381. extern bool in_error_recursion_trouble(void);
  382. /* Common functions shared across destinations */
  383. extern void reset_formatted_start_time(void);
  384. extern char *get_formatted_start_time(void);
  385. extern char *get_formatted_log_time(void);
  386. extern const char *get_backend_type_for_log(void);
  387. extern bool check_log_of_query(ErrorData *edata);
  388. extern const char *error_severity(int elevel);
  389. extern void write_pipe_chunks(char *data, int len, int dest);
  390. /* Destination-specific functions */
  391. extern void write_csvlog(ErrorData *edata);
  392. extern void write_jsonlog(ErrorData *edata);
  393. #ifdef HAVE_SYSLOG
  394. extern void set_syslog_parameters(const char *ident, int facility);
  395. #endif
  396. /*
  397. * Write errors to stderr (or by equal means when stderr is
  398. * not available). Used before ereport/elog can be used
  399. * safely (memory context, GUC load etc)
  400. */
  401. extern void write_stderr(const char *fmt,...) pg_attribute_printf(1, 2);
  402. #endif /* ELOG_H */