summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/error-message-reporting.html
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:17:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:17:33 +0000
commit5e45211a64149b3c659b90ff2de6fa982a5a93ed (patch)
tree739caf8c461053357daa9f162bef34516c7bf452 /doc/src/sgml/html/error-message-reporting.html
parentInitial commit. (diff)
downloadpostgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.tar.xz
postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.zip
Adding upstream version 15.5.upstream/15.5
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/src/sgml/html/error-message-reporting.html')
-rw-r--r--doc/src/sgml/html/error-message-reporting.html250
1 files changed, 250 insertions, 0 deletions
diff --git a/doc/src/sgml/html/error-message-reporting.html b/doc/src/sgml/html/error-message-reporting.html
new file mode 100644
index 0000000..b14244f
--- /dev/null
+++ b/doc/src/sgml/html/error-message-reporting.html
@@ -0,0 +1,250 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>56.2. Reporting Errors Within the Server</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="source-format.html" title="56.1. Formatting" /><link rel="next" href="error-style-guide.html" title="56.3. Error Message Style Guide" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">56.2. Reporting Errors Within the Server</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="source-format.html" title="56.1. Formatting">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><th width="60%" align="center">Chapter 56. PostgreSQL Coding Conventions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="error-style-guide.html" title="56.3. Error Message Style Guide">Next</a></td></tr></table><hr /></div><div class="sect1" id="ERROR-MESSAGE-REPORTING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">56.2. Reporting Errors Within the Server</h2></div></div></div><a id="id-1.10.7.3.2" class="indexterm"></a><a id="id-1.10.7.3.3" class="indexterm"></a><p>
+ Error, warning, and log messages generated within the server code
+ should be created using <code class="function">ereport</code>, or its older cousin
+ <code class="function">elog</code>. The use of this function is complex enough to
+ require some explanation.
+ </p><p>
+ There are two required elements for every message: a severity level
+ (ranging from <code class="literal">DEBUG</code> to <code class="literal">PANIC</code>) and a primary
+ message text. In addition there are optional elements, the most
+ common of which is an error identifier code that follows the SQL spec's
+ SQLSTATE conventions.
+ <code class="function">ereport</code> itself is just a shell macro that exists
+ mainly for the syntactic convenience of making message generation
+ look like a single function call in the C source code. The only parameter
+ accepted directly by <code class="function">ereport</code> is the severity level.
+ The primary message text and any optional message elements are
+ generated by calling auxiliary functions, such as <code class="function">errmsg</code>,
+ within the <code class="function">ereport</code> call.
+ </p><p>
+ A typical call to <code class="function">ereport</code> might look like this:
+</p><pre class="programlisting">
+ereport(ERROR,
+ errcode(ERRCODE_DIVISION_BY_ZERO),
+ errmsg("division by zero"));
+</pre><p>
+ This specifies error severity level <code class="literal">ERROR</code> (a run-of-the-mill
+ error). The <code class="function">errcode</code> call specifies the SQLSTATE error code
+ using a macro defined in <code class="filename">src/include/utils/errcodes.h</code>. The
+ <code class="function">errmsg</code> call provides the primary message text.
+ </p><p>
+ You will also frequently see this older style, with an extra set of
+ parentheses surrounding the auxiliary function calls:
+</p><pre class="programlisting">
+ereport(ERROR,
+ (errcode(ERRCODE_DIVISION_BY_ZERO),
+ errmsg("division by zero")));
+</pre><p>
+ The extra parentheses were required
+ before <span class="productname">PostgreSQL</span> version 12, but are now
+ optional.
+ </p><p>
+ Here is a more complex example:
+</p><pre class="programlisting">
+ereport(ERROR,
+ errcode(ERRCODE_AMBIGUOUS_FUNCTION),
+ errmsg("function %s is not unique",
+ func_signature_string(funcname, nargs,
+ NIL, actual_arg_types)),
+ errhint("Unable to choose a best candidate function. "
+ "You might need to add explicit typecasts."));
+</pre><p>
+ This illustrates the use of format codes to embed run-time values into
+ a message text. Also, an optional <span class="quote">“<span class="quote">hint</span>”</span> message is provided.
+ The auxiliary function calls can be written in any order, but
+ conventionally <code class="function">errcode</code>
+ and <code class="function">errmsg</code> appear first.
+ </p><p>
+ If the severity level is <code class="literal">ERROR</code> or higher,
+ <code class="function">ereport</code> aborts execution of the current query
+ and does not return to the caller. If the severity level is
+ lower than <code class="literal">ERROR</code>, <code class="function">ereport</code> returns normally.
+ </p><p>
+ The available auxiliary routines for <code class="function">ereport</code> are:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ <code class="function">errcode(sqlerrcode)</code> specifies the SQLSTATE error identifier
+ code for the condition. If this routine is not called, the error
+ identifier defaults to
+ <code class="literal">ERRCODE_INTERNAL_ERROR</code> when the error severity level is
+ <code class="literal">ERROR</code> or higher, <code class="literal">ERRCODE_WARNING</code> when the
+ error level is <code class="literal">WARNING</code>, otherwise (for <code class="literal">NOTICE</code>
+ and below) <code class="literal">ERRCODE_SUCCESSFUL_COMPLETION</code>.
+ While these defaults are often convenient, always think whether they
+ are appropriate before omitting the <code class="function">errcode()</code> call.
+ </p></li><li class="listitem"><p>
+ <code class="function">errmsg(const char *msg, ...)</code> specifies the primary error
+ message text, and possibly run-time values to insert into it. Insertions
+ are specified by <code class="function">sprintf</code>-style format codes. In addition to
+ the standard format codes accepted by <code class="function">sprintf</code>, the format
+ code <code class="literal">%m</code> can be used to insert the error message returned
+ by <code class="function">strerror</code> for the current value of <code class="literal">errno</code>.
+ <a href="#ftn.id-1.10.7.3.10.2.2.1.7" class="footnote"><sup class="footnote" id="id-1.10.7.3.10.2.2.1.7">[16]</sup></a>
+ <code class="literal">%m</code> does not require any
+ corresponding entry in the parameter list for <code class="function">errmsg</code>.
+ Note that the message string will be run through <code class="function">gettext</code>
+ for possible localization before format codes are processed.
+ </p></li><li class="listitem"><p>
+ <code class="function">errmsg_internal(const char *msg, ...)</code> is the same as
+ <code class="function">errmsg</code>, except that the message string will not be
+ translated nor included in the internationalization message dictionary.
+ This should be used for <span class="quote">“<span class="quote">cannot happen</span>”</span> cases that are probably
+ not worth expending translation effort on.
+ </p></li><li class="listitem"><p>
+ <code class="function">errmsg_plural(const char *fmt_singular, const char *fmt_plural,
+ unsigned long n, ...)</code> is like <code class="function">errmsg</code>, but with
+ support for various plural forms of the message.
+ <em class="replaceable"><code>fmt_singular</code></em> is the English singular format,
+ <em class="replaceable"><code>fmt_plural</code></em> is the English plural format,
+ <em class="replaceable"><code>n</code></em> is the integer value that determines which plural
+ form is needed, and the remaining arguments are formatted according
+ to the selected format string. For more information see
+ <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail(const char *msg, ...)</code> supplies an optional
+ <span class="quote">“<span class="quote">detail</span>”</span> message; this is to be used when there is additional
+ information that seems inappropriate to put in the primary message.
+ The message string is processed in just the same way as for
+ <code class="function">errmsg</code>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail_internal(const char *msg, ...)</code> is the same
+ as <code class="function">errdetail</code>, except that the message string will not be
+ translated nor included in the internationalization message dictionary.
+ This should be used for detail messages that are not worth expending
+ translation effort on, for instance because they are too technical to be
+ useful to most users.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail_plural(const char *fmt_singular, const char *fmt_plural,
+ unsigned long n, ...)</code> is like <code class="function">errdetail</code>, but with
+ support for various plural forms of the message.
+ For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail_log(const char *msg, ...)</code> is the same as
+ <code class="function">errdetail</code> except that this string goes only to the server
+ log, never to the client. If both <code class="function">errdetail</code> (or one of
+ its equivalents above) and
+ <code class="function">errdetail_log</code> are used then one string goes to the client
+ and the other to the log. This is useful for error details that are
+ too security-sensitive or too bulky to include in the report
+ sent to the client.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdetail_log_plural(const char *fmt_singular, const char
+ *fmt_plural, unsigned long n, ...)</code> is like
+ <code class="function">errdetail_log</code>, but with support for various plural forms of
+ the message.
+ For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errhint(const char *msg, ...)</code> supplies an optional
+ <span class="quote">“<span class="quote">hint</span>”</span> message; this is to be used when offering suggestions
+ about how to fix the problem, as opposed to factual details about
+ what went wrong.
+ The message string is processed in just the same way as for
+ <code class="function">errmsg</code>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errhint_plural(const char *fmt_singular, const char *fmt_plural,
+ unsigned long n, ...)</code> is like <code class="function">errhint</code>, but with
+ support for various plural forms of the message.
+ For more information see <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errcontext(const char *msg, ...)</code> is not normally called
+ directly from an <code class="function">ereport</code> message site; rather it is used
+ in <code class="literal">error_context_stack</code> callback functions to provide
+ information about the context in which an error occurred, such as the
+ current location in a PL function.
+ The message string is processed in just the same way as for
+ <code class="function">errmsg</code>. Unlike the other auxiliary functions, this can
+ be called more than once per <code class="function">ereport</code> call; the successive
+ strings thus supplied are concatenated with separating newlines.
+ </p></li><li class="listitem"><p>
+ <code class="function">errposition(int cursorpos)</code> specifies the textual location
+ of an error within a query string. Currently it is only useful for
+ errors detected in the lexical and syntactic analysis phases of
+ query processing.
+ </p></li><li class="listitem"><p>
+ <code class="function">errtable(Relation rel)</code> specifies a relation whose
+ name and schema name should be included as auxiliary fields in the error
+ report.
+ </p></li><li class="listitem"><p>
+ <code class="function">errtablecol(Relation rel, int attnum)</code> specifies
+ a column whose name, table name, and schema name should be included as
+ auxiliary fields in the error report.
+ </p></li><li class="listitem"><p>
+ <code class="function">errtableconstraint(Relation rel, const char *conname)</code>
+ specifies a table constraint whose name, table name, and schema name
+ should be included as auxiliary fields in the error report. Indexes
+ should be considered to be constraints for this purpose, whether or
+ not they have an associated <code class="structname">pg_constraint</code> entry. Be
+ careful to pass the underlying heap relation, not the index itself, as
+ <code class="literal">rel</code>.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdatatype(Oid datatypeOid)</code> specifies a data
+ type whose name and schema name should be included as auxiliary fields
+ in the error report.
+ </p></li><li class="listitem"><p>
+ <code class="function">errdomainconstraint(Oid datatypeOid, const char *conname)</code>
+ specifies a domain constraint whose name, domain name, and schema name
+ should be included as auxiliary fields in the error report.
+ </p></li><li class="listitem"><p>
+ <code class="function">errcode_for_file_access()</code> is a convenience function that
+ selects an appropriate SQLSTATE error identifier for a failure in a
+ file-access-related system call. It uses the saved
+ <code class="literal">errno</code> to determine which error code to generate.
+ Usually this should be used in combination with <code class="literal">%m</code> in the
+ primary error message text.
+ </p></li><li class="listitem"><p>
+ <code class="function">errcode_for_socket_access()</code> is a convenience function that
+ selects an appropriate SQLSTATE error identifier for a failure in a
+ socket-related system call.
+ </p></li><li class="listitem"><p>
+ <code class="function">errhidestmt(bool hide_stmt)</code> can be called to specify
+ suppression of the <code class="literal">STATEMENT:</code> portion of a message in the
+ postmaster log. Generally this is appropriate if the message text
+ includes the current statement already.
+ </p></li><li class="listitem"><p>
+ <code class="function">errhidecontext(bool hide_ctx)</code> can be called to
+ specify suppression of the <code class="literal">CONTEXT:</code> portion of a message in
+ the postmaster log. This should only be used for verbose debugging
+ messages where the repeated inclusion of context would bloat the log
+ too much.
+ </p></li></ul></div><p>
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ At most one of the functions <code class="function">errtable</code>,
+ <code class="function">errtablecol</code>, <code class="function">errtableconstraint</code>,
+ <code class="function">errdatatype</code>, or <code class="function">errdomainconstraint</code> should
+ be used in an <code class="function">ereport</code> call. These functions exist to
+ allow applications to extract the name of a database object associated
+ with the error condition without having to examine the
+ potentially-localized error message text.
+ These functions should be used in error reports for which it's likely
+ that applications would wish to have automatic error handling. As of
+ <span class="productname">PostgreSQL</span> 9.3, complete coverage exists only for
+ errors in SQLSTATE class 23 (integrity constraint violation), but this
+ is likely to be expanded in future.
+ </p></div><p>
+ There is an older function <code class="function">elog</code> that is still heavily used.
+ An <code class="function">elog</code> call:
+</p><pre class="programlisting">
+elog(level, "format string", ...);
+</pre><p>
+ is exactly equivalent to:
+</p><pre class="programlisting">
+ereport(level, errmsg_internal("format string", ...));
+</pre><p>
+ Notice that the SQLSTATE error code is always defaulted, and the message
+ string is not subject to translation.
+ Therefore, <code class="function">elog</code> should be used only for internal errors and
+ low-level debug logging. Any message that is likely to be of interest to
+ ordinary users should go through <code class="function">ereport</code>. Nonetheless,
+ there are enough internal <span class="quote">“<span class="quote">cannot happen</span>”</span> error checks in the
+ system that <code class="function">elog</code> is still widely used; it is preferred for
+ those messages for its notational simplicity.
+ </p><p>
+ Advice about writing good error messages can be found in
+ <a class="xref" href="error-style-guide.html" title="56.3. Error Message Style Guide">Section 56.3</a>.
+ </p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.10.7.3.10.2.2.1.7" class="footnote"><p><a href="#id-1.10.7.3.10.2.2.1.7" class="para"><sup class="para">[16] </sup></a>
+ That is, the value that was current when the <code class="function">ereport</code> call
+ was reached; changes of <code class="literal">errno</code> within the auxiliary reporting
+ routines will not affect it. That would not be true if you were to
+ write <code class="literal">strerror(errno)</code> explicitly in <code class="function">errmsg</code>'s
+ parameter list; accordingly, do not do so.
+ </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source-format.html" title="56.1. Formatting">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="source.html" title="Chapter 56. PostgreSQL Coding Conventions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="error-style-guide.html" title="56.3. Error Message Style Guide">Next</a></td></tr><tr><td width="40%" align="left" valign="top">56.1. Formatting </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 56.3. Error Message Style Guide</td></tr></table></div></body></html> \ No newline at end of file