codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * elog.h4 *	  POSTGRES error reporting/logging definitions.5 *6 *7 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group8 * Portions Copyright (c) 1994, Regents of the University of California9 *10 * src/include/utils/elog.h11 *12 *-------------------------------------------------------------------------13 */14#ifndef ELOG_H15#define ELOG_H16 17#include <setjmp.h>18 19#include "lib/stringinfo.h"20 21/* We cannot include nodes.h yet, so forward-declare struct Node */22struct Node;23 24 25/* Error level codes */26#define DEBUG5		10			/* Debugging messages, in categories of27								 * decreasing detail. */28#define DEBUG4		1129#define DEBUG3		1230#define DEBUG2		1331#define DEBUG1		14			/* used by GUC debug_* variables */32#define LOG			15			/* Server operational messages; sent only to33								 * server log by default. */34#define LOG_SERVER_ONLY 16		/* Same as LOG for server reporting, but never35								 * sent to client. */36#define COMMERROR	LOG_SERVER_ONLY /* Client communication problems; same as37									 * LOG for server reporting, but never38									 * sent to client. */39#define INFO		17			/* Messages specifically requested by user (eg40								 * VACUUM VERBOSE output); always sent to41								 * client regardless of client_min_messages,42								 * but by default not sent to server log. */43#define NOTICE		18			/* Helpful messages to users about query44								 * operation; sent to client and not to server45								 * log by default. */46#define WARNING		19			/* Warnings.  NOTICE is for expected messages47								 * like implicit sequence creation by SERIAL.48								 * WARNING is for unexpected messages. */49#define PGWARNING	19			/* Must equal WARNING; see NOTE below. */50#define WARNING_CLIENT_ONLY	20	/* Warnings to be sent to client as usual, but51								 * never to the server log. */52#define ERROR		21			/* user error - abort transaction; return to53								 * known state */54#define PGERROR		21			/* Must equal ERROR; see NOTE below. */55#define FATAL		22			/* fatal error - abort process */56#define PANIC		23			/* take down the other backends with me */57 58/*59 * NOTE: the alternate names PGWARNING and PGERROR are useful for dealing60 * with third-party headers that make other definitions of WARNING and/or61 * ERROR.  One can, for example, re-define ERROR as PGERROR after including62 * such a header.63 */64 65 66/* macros for representing SQLSTATE strings compactly */67#define PGSIXBIT(ch)	(((ch) - '0') & 0x3F)68#define PGUNSIXBIT(val) (((val) & 0x3F) + '0')69 70#define MAKE_SQLSTATE(ch1,ch2,ch3,ch4,ch5)	\71	(PGSIXBIT(ch1) + (PGSIXBIT(ch2) << 6) + (PGSIXBIT(ch3) << 12) + \72	 (PGSIXBIT(ch4) << 18) + (PGSIXBIT(ch5) << 24))73 74/* These macros depend on the fact that '0' becomes a zero in PGSIXBIT */75#define ERRCODE_TO_CATEGORY(ec)  ((ec) & ((1 << 12) - 1))76#define ERRCODE_IS_CATEGORY(ec)  (((ec) & ~((1 << 12) - 1)) == 0)77 78/* SQLSTATE codes for errors are defined in a separate file */79#include "utils/errcodes.h"80 81/*82 * Provide a way to prevent "errno" from being accidentally used inside an83 * elog() or ereport() invocation.  Since we know that some operating systems84 * define errno as something involving a function call, we'll put a local85 * variable of the same name as that function in the local scope to force a86 * compile error.  On platforms that don't define errno in that way, nothing87 * happens, so we get no warning ... but we can live with that as long as it88 * happens on some popular platforms.89 */90#if defined(errno) && defined(__linux__)91#define pg_prevent_errno_in_scope() int __errno_location pg_attribute_unused()92#elif defined(errno) && (defined(__darwin__) || defined(__FreeBSD__))93#define pg_prevent_errno_in_scope() int __error pg_attribute_unused()94#else95#define pg_prevent_errno_in_scope()96#endif97 98 99/*----------100 * New-style error reporting API: to be used in this way:101 *		ereport(ERROR,102 *				errcode(ERRCODE_UNDEFINED_CURSOR),103 *				errmsg("portal \"%s\" not found", stmt->portalname),104 *				... other errxxx() fields as needed ...);105 *106 * The error level is required, and so is a primary error message (errmsg107 * or errmsg_internal).  All else is optional.  errcode() defaults to108 * ERRCODE_INTERNAL_ERROR if elevel is ERROR or more, ERRCODE_WARNING109 * if elevel is WARNING, or ERRCODE_SUCCESSFUL_COMPLETION if elevel is110 * NOTICE or below.111 *112 * Before Postgres v12, extra parentheses were required around the113 * list of auxiliary function calls; that's now optional.114 *115 * ereport_domain() allows a message domain to be specified, for modules that116 * wish to use a different message catalog from the backend's.  To avoid having117 * one copy of the default text domain per .o file, we define it as NULL here118 * and have errstart insert the default text domain.  Modules can either use119 * ereport_domain() directly, or preferably they can override the TEXTDOMAIN120 * macro.121 *122 * When __builtin_constant_p is available and elevel >= ERROR we make a call123 * to errstart_cold() instead of errstart().  This version of the function is124 * marked with pg_attribute_cold which will coax supporting compilers into125 * generating code which is more optimized towards non-ERROR cases.  Because126 * we use __builtin_constant_p() in the condition, when elevel is not a127 * compile-time constant, or if it is, but it's < ERROR, the compiler has no128 * need to generate any code for this branch.  It can simply call errstart()129 * unconditionally.130 *131 * If elevel >= ERROR, the call will not return; we try to inform the compiler132 * of that via pg_unreachable().  However, no useful optimization effect is133 * obtained unless the compiler sees elevel as a compile-time constant, else134 * we're just adding code bloat.  So, if __builtin_constant_p is available,135 * use that to cause the second if() to vanish completely for non-constant136 * cases.  We avoid using a local variable because it's not necessary and137 * prevents gcc from making the unreachability deduction at optlevel -O0.138 *----------139 */140#ifdef HAVE__BUILTIN_CONSTANT_P141#define ereport_domain(elevel, domain, ...)	\142	do { \143		pg_prevent_errno_in_scope(); \144		if (__builtin_constant_p(elevel) && (elevel) >= ERROR ? \145			errstart_cold(elevel, domain) : \146			errstart(elevel, domain)) \147			__VA_ARGS__, errfinish(__FILE__, __LINE__, __func__); \148		if (__builtin_constant_p(elevel) && (elevel) >= ERROR) \149			pg_unreachable(); \150	} while(0)151#else							/* !HAVE__BUILTIN_CONSTANT_P */152#define ereport_domain(elevel, domain, ...)	\153	do { \154		const int elevel_ = (elevel); \155		pg_prevent_errno_in_scope(); \156		if (errstart(elevel_, domain)) \157			__VA_ARGS__, errfinish(__FILE__, __LINE__, __func__); \158		if (elevel_ >= ERROR) \159			pg_unreachable(); \160	} while(0)161#endif							/* HAVE__BUILTIN_CONSTANT_P */162 163#define ereport(elevel, ...)	\164	ereport_domain(elevel, TEXTDOMAIN, __VA_ARGS__)165 166#define TEXTDOMAIN NULL167 168extern bool message_level_is_interesting(int elevel);169 170extern bool errstart(int elevel, const char *domain);171extern pg_attribute_cold bool errstart_cold(int elevel, const char *domain);172extern void errfinish(const char *filename, int lineno, const char *funcname);173 174extern int	errcode(int sqlerrcode);175 176extern int	errcode_for_file_access(void);177extern int	errcode_for_socket_access(void);178 179extern int	errmsg(const char *fmt,...) pg_attribute_printf(1, 2);180extern int	errmsg_internal(const char *fmt,...) pg_attribute_printf(1, 2);181 182extern int	errmsg_plural(const char *fmt_singular, const char *fmt_plural,183						  unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);184 185extern int	errdetail(const char *fmt,...) pg_attribute_printf(1, 2);186extern int	errdetail_internal(const char *fmt,...) pg_attribute_printf(1, 2);187 188extern int	errdetail_log(const char *fmt,...) pg_attribute_printf(1, 2);189 190extern int	errdetail_log_plural(const char *fmt_singular,191								 const char *fmt_plural,192								 unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);193 194extern int	errdetail_plural(const char *fmt_singular, const char *fmt_plural,195							 unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);196 197extern int	errhint(const char *fmt,...) pg_attribute_printf(1, 2);198 199extern int	errhint_plural(const char *fmt_singular, const char *fmt_plural,200						   unsigned long n,...) pg_attribute_printf(1, 4) pg_attribute_printf(2, 4);201 202/*203 * errcontext() is typically called in error context callback functions, not204 * within an ereport() invocation. The callback function can be in a different205 * module than the ereport() call, so the message domain passed in errstart()206 * is not usually the correct domain for translating the context message.207 * set_errcontext_domain() first sets the domain to be used, and208 * errcontext_msg() passes the actual message.209 */210#define errcontext	set_errcontext_domain(TEXTDOMAIN),	errcontext_msg211 212extern int	set_errcontext_domain(const char *domain);213 214extern int	errcontext_msg(const char *fmt,...) pg_attribute_printf(1, 2);215 216extern int	errhidestmt(bool hide_stmt);217extern int	errhidecontext(bool hide_ctx);218 219extern int	errbacktrace(void);220 221extern int	errposition(int cursorpos);222 223extern int	internalerrposition(int cursorpos);224extern int	internalerrquery(const char *query);225 226extern int	err_generic_string(int field, const char *str);227 228extern int	geterrcode(void);229extern int	geterrposition(void);230extern int	getinternalerrposition(void);231 232 233/*----------234 * Old-style error reporting API: to be used in this way:235 *		elog(ERROR, "portal \"%s\" not found", stmt->portalname);236 *----------237 */238#define elog(elevel, ...)  \239	ereport(elevel, errmsg_internal(__VA_ARGS__))240 241 242/*----------243 * Support for reporting "soft" errors that don't require a full transaction244 * abort to clean up.  This is to be used in this way:245 *		errsave(context,246 *				errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),247 *				errmsg("invalid input syntax for type %s: \"%s\"",248 *					   "boolean", in_str),249 *				... other errxxx() fields as needed ...);250 *251 * "context" is a node pointer or NULL, and the remaining auxiliary calls252 * provide the same error details as in ereport().  If context is not a253 * pointer to an ErrorSaveContext node, then errsave(context, ...)254 * behaves identically to ereport(ERROR, ...).  If context is a pointer255 * to an ErrorSaveContext node, then the information provided by the256 * auxiliary calls is stored in the context node and control returns257 * normally.  The caller of errsave() must then do any required cleanup258 * and return control back to its caller.  That caller must check the259 * ErrorSaveContext node to see whether an error occurred before260 * it can trust the function's result to be meaningful.261 *262 * errsave_domain() allows a message domain to be specified; it is263 * precisely analogous to ereport_domain().264 *----------265 */266#define errsave_domain(context, domain, ...)	\267	do { \268		struct Node *context_ = (context); \269		pg_prevent_errno_in_scope(); \270		if (errsave_start(context_, domain)) \271			__VA_ARGS__, errsave_finish(context_, __FILE__, __LINE__, __func__); \272	} while(0)273 274#define errsave(context, ...)	\275	errsave_domain(context, TEXTDOMAIN, __VA_ARGS__)276 277/*278 * "ereturn(context, dummy_value, ...);" is exactly the same as279 * "errsave(context, ...); return dummy_value;".  This saves a bit280 * of typing in the common case where a function has no cleanup281 * actions to take after reporting a soft error.  "dummy_value"282 * can be empty if the function returns void.283 */284#define ereturn_domain(context, dummy_value, domain, ...)	\285	do { \286		errsave_domain(context, domain, __VA_ARGS__); \287		return dummy_value; \288	} while(0)289 290#define ereturn(context, dummy_value, ...)	\291	ereturn_domain(context, dummy_value, TEXTDOMAIN, __VA_ARGS__)292 293extern bool errsave_start(struct Node *context, const char *domain);294extern void errsave_finish(struct Node *context,295						   const char *filename, int lineno,296						   const char *funcname);297 298 299/* Support for constructing error strings separately from ereport() calls */300 301extern void pre_format_elog_string(int errnumber, const char *domain);302extern char *format_elog_string(const char *fmt,...) pg_attribute_printf(1, 2);303 304 305/* Support for attaching context information to error reports */306 307typedef struct ErrorContextCallback308{309	struct ErrorContextCallback *previous;310	void		(*callback) (void *arg);311	void	   *arg;312} ErrorContextCallback;313 314extern PGDLLIMPORT ErrorContextCallback *error_context_stack;315 316 317/*----------318 * API for catching ereport(ERROR) exits.  Use these macros like so:319 *320 *		PG_TRY();321 *		{322 *			... code that might throw ereport(ERROR) ...323 *		}324 *		PG_CATCH();325 *		{326 *			... error recovery code ...327 *		}328 *		PG_END_TRY();329 *330 * (The braces are not actually necessary, but are recommended so that331 * pgindent will indent the construct nicely.)  The error recovery code332 * can either do PG_RE_THROW to propagate the error outwards, or do a333 * (sub)transaction abort. Failure to do so may leave the system in an334 * inconsistent state for further processing.335 *336 * For the common case that the error recovery code and the cleanup in the337 * normal code path are identical, the following can be used instead:338 *339 *		PG_TRY();340 *		{341 *			... code that might throw ereport(ERROR) ...342 *		}343 *		PG_FINALLY();344 *		{345 *			... cleanup code ...346 *		}347 *      PG_END_TRY();348 *349 * The cleanup code will be run in either case, and any error will be rethrown350 * afterwards.351 *352 * You cannot use both PG_CATCH() and PG_FINALLY() in the same353 * PG_TRY()/PG_END_TRY() block.354 *355 * Note: while the system will correctly propagate any new ereport(ERROR)356 * occurring in the recovery section, there is a small limit on the number357 * of levels this will work for.  It's best to keep the error recovery358 * section simple enough that it can't generate any new errors, at least359 * not before popping the error stack.360 *361 * Note: an ereport(FATAL) will not be caught by this construct; control will362 * exit straight through proc_exit().  Therefore, do NOT put any cleanup363 * of non-process-local resources into the error recovery section, at least364 * not without taking thought for what will happen during ereport(FATAL).365 * The PG_ENSURE_ERROR_CLEANUP macros provided by storage/ipc.h may be366 * helpful in such cases.367 *368 * Note: if a local variable of the function containing PG_TRY is modified369 * in the PG_TRY section and used in the PG_CATCH section, that variable370 * must be declared "volatile" for POSIX compliance.  This is not mere371 * pedantry; we have seen bugs from compilers improperly optimizing code372 * away when such a variable was not marked.  Beware that gcc's -Wclobbered373 * warnings are just about entirely useless for catching such oversights.374 *375 * Each of these macros accepts an optional argument which can be specified376 * to apply a suffix to the variables declared within the macros.  This suffix377 * can be used to avoid the compiler emitting warnings about shadowed378 * variables when compiling with -Wshadow in situations where nested PG_TRY()379 * statements are required.  The optional suffix may contain any character380 * that's allowed in a variable name.  The suffix, if specified, must be the381 * same within each component macro of the given PG_TRY() statement.382 *----------383 */384#define PG_TRY(...)  \385	do { \386		sigjmp_buf *_save_exception_stack##__VA_ARGS__ = PG_exception_stack; \387		ErrorContextCallback *_save_context_stack##__VA_ARGS__ = error_context_stack; \388		sigjmp_buf _local_sigjmp_buf##__VA_ARGS__; \389		bool _do_rethrow##__VA_ARGS__ = false; \390		if (sigsetjmp(_local_sigjmp_buf##__VA_ARGS__, 0) == 0) \391		{ \392			PG_exception_stack = &_local_sigjmp_buf##__VA_ARGS__393 394#define PG_CATCH(...)	\395		} \396		else \397		{ \398			PG_exception_stack = _save_exception_stack##__VA_ARGS__; \399			error_context_stack = _save_context_stack##__VA_ARGS__400 401#define PG_FINALLY(...) \402		} \403		else \404			_do_rethrow##__VA_ARGS__ = true; \405		{ \406			PG_exception_stack = _save_exception_stack##__VA_ARGS__; \407			error_context_stack = _save_context_stack##__VA_ARGS__408 409#define PG_END_TRY(...)  \410		} \411		if (_do_rethrow##__VA_ARGS__) \412				PG_RE_THROW(); \413		PG_exception_stack = _save_exception_stack##__VA_ARGS__; \414		error_context_stack = _save_context_stack##__VA_ARGS__; \415	} while (0)416 417/*418 * Some compilers understand pg_attribute_noreturn(); for other compilers,419 * insert pg_unreachable() so that the compiler gets the point.420 */421#ifdef HAVE_PG_ATTRIBUTE_NORETURN422#define PG_RE_THROW()  \423	pg_re_throw()424#else425#define PG_RE_THROW()  \426	(pg_re_throw(), pg_unreachable())427#endif428 429extern PGDLLIMPORT sigjmp_buf *PG_exception_stack;430 431 432/* Stuff that error handlers might want to use */433 434/*435 * ErrorData holds the data accumulated during any one ereport() cycle.436 * Any non-NULL pointers must point to palloc'd data.437 * (The const pointers are an exception; we assume they point at non-freeable438 * constant strings.)439 */440typedef struct ErrorData441{442	int			elevel;			/* error level */443	bool		output_to_server;	/* will report to server log? */444	bool		output_to_client;	/* will report to client? */445	bool		hide_stmt;		/* true to prevent STATEMENT: inclusion */446	bool		hide_ctx;		/* true to prevent CONTEXT: inclusion */447	const char *filename;		/* __FILE__ of ereport() call */448	int			lineno;			/* __LINE__ of ereport() call */449	const char *funcname;		/* __func__ of ereport() call */450	const char *domain;			/* message domain */451	const char *context_domain; /* message domain for context message */452	int			sqlerrcode;		/* encoded ERRSTATE */453	char	   *message;		/* primary error message (translated) */454	char	   *detail;			/* detail error message */455	char	   *detail_log;		/* detail error message for server log only */456	char	   *hint;			/* hint message */457	char	   *context;		/* context message */458	char	   *backtrace;		/* backtrace */459	const char *message_id;		/* primary message's id (original string) */460	char	   *schema_name;	/* name of schema */461	char	   *table_name;		/* name of table */462	char	   *column_name;	/* name of column */463	char	   *datatype_name;	/* name of datatype */464	char	   *constraint_name;	/* name of constraint */465	int			cursorpos;		/* cursor index into query string */466	int			internalpos;	/* cursor index into internalquery */467	char	   *internalquery;	/* text of internally-generated query */468	int			saved_errno;	/* errno at entry */469 470	/* context containing associated non-constant strings */471	struct MemoryContextData *assoc_context;472} ErrorData;473 474extern void EmitErrorReport(void);475extern ErrorData *CopyErrorData(void);476extern void FreeErrorData(ErrorData *edata);477extern void FlushErrorState(void);478extern void ReThrowError(ErrorData *edata) pg_attribute_noreturn();479extern void ThrowErrorData(ErrorData *edata);480extern void pg_re_throw(void) pg_attribute_noreturn();481 482extern char *GetErrorContextStack(void);483 484/* Hook for intercepting messages before they are sent to the server log */485typedef void (*emit_log_hook_type) (ErrorData *edata);486extern PGDLLIMPORT emit_log_hook_type emit_log_hook;487 488 489/* GUC-configurable parameters */490 491typedef enum492{493	PGERROR_TERSE,				/* single-line error messages */494	PGERROR_DEFAULT,			/* recommended style */495	PGERROR_VERBOSE				/* all the facts, ma'am */496}			PGErrorVerbosity;497 498extern PGDLLIMPORT int Log_error_verbosity;499extern PGDLLIMPORT char *Log_line_prefix;500extern PGDLLIMPORT int Log_destination;501extern PGDLLIMPORT char *Log_destination_string;502extern PGDLLIMPORT bool syslog_sequence_numbers;503extern PGDLLIMPORT bool syslog_split_messages;504 505/* Log destination bitmap */506#define LOG_DESTINATION_STDERR	 1507#define LOG_DESTINATION_SYSLOG	 2508#define LOG_DESTINATION_EVENTLOG 4509#define LOG_DESTINATION_CSVLOG	 8510#define LOG_DESTINATION_JSONLOG	16511 512/* Other exported functions */513extern void log_status_format(StringInfo buf, const char *format,514							  ErrorData *edata);515extern void DebugFileOpen(void);516extern char *unpack_sql_state(int sql_state);517extern bool in_error_recursion_trouble(void);518 519/* Common functions shared across destinations */520extern void reset_formatted_start_time(void);521extern char *get_formatted_start_time(void);522extern char *get_formatted_log_time(void);523extern const char *get_backend_type_for_log(void);524extern bool check_log_of_query(ErrorData *edata);525extern const char *error_severity(int elevel);526extern void write_pipe_chunks(char *data, int len, int dest);527 528/* Destination-specific functions */529extern void write_csvlog(ErrorData *edata);530extern void write_jsonlog(ErrorData *edata);531 532/*533 * Write errors to stderr (or by equal means when stderr is534 * not available). Used before ereport/elog can be used535 * safely (memory context, GUC load etc)536 */537extern void write_stderr(const char *fmt,...) pg_attribute_printf(1, 2);538 539/*540 * Write a message to STDERR using only async-signal-safe functions.  This can541 * be used to safely emit a message from a signal handler.542 */543extern void write_stderr_signal_safe(const char *fmt);544 545#endif							/* ELOG_H */546