Adding upstream version 15.5.upstream/15.5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-04 12:17:33 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-04 12:17:33 +0000
commit: 5e45211a64149b3c659b90ff2de6fa982a5a93ed (patch)
tree: 739caf8c461053357daa9f162bef34516c7bf452 /doc/src/sgml/html/error-message-reporting.html
parent: Initial commit. (diff)
download: postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.tar.xz
postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.zip
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
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-04 12:17:33 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-04 12:17:33 +0000
commit	5e45211a64149b3c659b90ff2de6fa982a5a93ed (patch)
tree	739caf8c461053357daa9f162bef34516c7bf452 /doc/src/sgml/html/error-message-reporting.html
parent	Initial commit. (diff)
download	postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.tar.xz postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.zip