diff options
Diffstat (limited to 'doc/src/sgml/html/error-message-reporting.html')
| -rw-r--r-- | doc/src/sgml/html/error-message-reporting.html | 250 |
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 |