codekingpro/portable-devtools
115k
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!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 16.3 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 <a href="#ERROR-MESSAGE-REPORTING" class="id_link">#</a></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>3 Error, warning, and log messages generated within the server code4 should be created using <code class="function">ereport</code>, or its older cousin5 <code class="function">elog</code>. The use of this function is complex enough to6 require some explanation.7 </p><p>8 There are two required elements for every message: a severity level9 (ranging from <code class="literal">DEBUG</code> to <code class="literal">PANIC</code>) and a primary10 message text. In addition there are optional elements, the most11 common of which is an error identifier code that follows the SQL spec's12 SQLSTATE conventions.13 <code class="function">ereport</code> itself is just a shell macro that exists14 mainly for the syntactic convenience of making message generation15 look like a single function call in the C source code. The only parameter16 accepted directly by <code class="function">ereport</code> is the severity level.17 The primary message text and any optional message elements are18 generated by calling auxiliary functions, such as <code class="function">errmsg</code>,19 within the <code class="function">ereport</code> call.20 </p><p>21 A typical call to <code class="function">ereport</code> might look like this:22</p><pre class="programlisting">23ereport(ERROR,24 errcode(ERRCODE_DIVISION_BY_ZERO),25 errmsg("division by zero"));26</pre><p>27 This specifies error severity level <code class="literal">ERROR</code> (a run-of-the-mill28 error). The <code class="function">errcode</code> call specifies the SQLSTATE error code29 using a macro defined in <code class="filename">src/include/utils/errcodes.h</code>. The30 <code class="function">errmsg</code> call provides the primary message text.31 </p><p>32 You will also frequently see this older style, with an extra set of33 parentheses surrounding the auxiliary function calls:34</p><pre class="programlisting">35ereport(ERROR,36 (errcode(ERRCODE_DIVISION_BY_ZERO),37 errmsg("division by zero")));38</pre><p>39 The extra parentheses were required40 before <span class="productname">PostgreSQL</span> version 12, but are now41 optional.42 </p><p>43 Here is a more complex example:44</p><pre class="programlisting">45ereport(ERROR,46 errcode(ERRCODE_AMBIGUOUS_FUNCTION),47 errmsg("function %s is not unique",48 func_signature_string(funcname, nargs,49 NIL, actual_arg_types)),50 errhint("Unable to choose a best candidate function. "51 "You might need to add explicit typecasts."));52</pre><p>53 This illustrates the use of format codes to embed run-time values into54 a message text. Also, an optional <span class="quote">“<span class="quote">hint</span>”</span> message is provided.55 The auxiliary function calls can be written in any order, but56 conventionally <code class="function">errcode</code>57 and <code class="function">errmsg</code> appear first.58 </p><p>59 If the severity level is <code class="literal">ERROR</code> or higher,60 <code class="function">ereport</code> aborts execution of the current query61 and does not return to the caller. If the severity level is62 lower than <code class="literal">ERROR</code>, <code class="function">ereport</code> returns normally.63 </p><p>64 The available auxiliary routines for <code class="function">ereport</code> are:65 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>66 <code class="function">errcode(sqlerrcode)</code> specifies the SQLSTATE error identifier67 code for the condition. If this routine is not called, the error68 identifier defaults to69 <code class="literal">ERRCODE_INTERNAL_ERROR</code> when the error severity level is70 <code class="literal">ERROR</code> or higher, <code class="literal">ERRCODE_WARNING</code> when the71 error level is <code class="literal">WARNING</code>, otherwise (for <code class="literal">NOTICE</code>72 and below) <code class="literal">ERRCODE_SUCCESSFUL_COMPLETION</code>.73 While these defaults are often convenient, always think whether they74 are appropriate before omitting the <code class="function">errcode()</code> call.75 </p></li><li class="listitem"><p>76 <code class="function">errmsg(const char *msg, ...)</code> specifies the primary error77 message text, and possibly run-time values to insert into it. Insertions78 are specified by <code class="function">sprintf</code>-style format codes. In addition to79 the standard format codes accepted by <code class="function">sprintf</code>, the format80 code <code class="literal">%m</code> can be used to insert the error message returned81 by <code class="function">strerror</code> for the current value of <code class="literal">errno</code>.82 <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>83 <code class="literal">%m</code> does not require any84 corresponding entry in the parameter list for <code class="function">errmsg</code>.85 Note that the message string will be run through <code class="function">gettext</code>86 for possible localization before format codes are processed.87 </p></li><li class="listitem"><p>88 <code class="function">errmsg_internal(const char *msg, ...)</code> is the same as89 <code class="function">errmsg</code>, except that the message string will not be90 translated nor included in the internationalization message dictionary.91 This should be used for <span class="quote">“<span class="quote">cannot happen</span>”</span> cases that are probably92 not worth expending translation effort on.93 </p></li><li class="listitem"><p>94 <code class="function">errmsg_plural(const char *fmt_singular, const char *fmt_plural,95 unsigned long n, ...)</code> is like <code class="function">errmsg</code>, but with96 support for various plural forms of the message.97 <em class="replaceable"><code>fmt_singular</code></em> is the English singular format,98 <em class="replaceable"><code>fmt_plural</code></em> is the English plural format,99 <em class="replaceable"><code>n</code></em> is the integer value that determines which plural100 form is needed, and the remaining arguments are formatted according101 to the selected format string. For more information see102 <a class="xref" href="nls-programmer.html#NLS-GUIDELINES" title="57.2.2. Message-Writing Guidelines">Section 57.2.2</a>.103 </p></li><li class="listitem"><p>104 <code class="function">errdetail(const char *msg, ...)</code> supplies an optional105 <span class="quote">“<span class="quote">detail</span>”</span> message; this is to be used when there is additional106 information that seems inappropriate to put in the primary message.107 The message string is processed in just the same way as for108 <code class="function">errmsg</code>.109 </p></li><li class="listitem"><p>110 <code class="function">errdetail_internal(const char *msg, ...)</code> is the same111 as <code class="function">errdetail</code>, except that the message string will not be112 translated nor included in the internationalization message dictionary.113 This should be used for detail messages that are not worth expending114 translation effort on, for instance because they are too technical to be115 useful to most users.116 </p></li><li class="listitem"><p>117 <code class="function">errdetail_plural(const char *fmt_singular, const char *fmt_plural,118 unsigned long n, ...)</code> is like <code class="function">errdetail</code>, but with119 support for various plural forms of the message.120 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>.121 </p></li><li class="listitem"><p>122 <code class="function">errdetail_log(const char *msg, ...)</code> is the same as123 <code class="function">errdetail</code> except that this string goes only to the server124 log, never to the client. If both <code class="function">errdetail</code> (or one of125 its equivalents above) and126 <code class="function">errdetail_log</code> are used then one string goes to the client127 and the other to the log. This is useful for error details that are128 too security-sensitive or too bulky to include in the report129 sent to the client.130 </p></li><li class="listitem"><p>131 <code class="function">errdetail_log_plural(const char *fmt_singular, const char132 *fmt_plural, unsigned long n, ...)</code> is like133 <code class="function">errdetail_log</code>, but with support for various plural forms of134 the message.135 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>.136 </p></li><li class="listitem"><p>137 <code class="function">errhint(const char *msg, ...)</code> supplies an optional138 <span class="quote">“<span class="quote">hint</span>”</span> message; this is to be used when offering suggestions139 about how to fix the problem, as opposed to factual details about140 what went wrong.141 The message string is processed in just the same way as for142 <code class="function">errmsg</code>.143 </p></li><li class="listitem"><p>144 <code class="function">errhint_plural(const char *fmt_singular, const char *fmt_plural,145 unsigned long n, ...)</code> is like <code class="function">errhint</code>, but with146 support for various plural forms of the message.147 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>.148 </p></li><li class="listitem"><p>149 <code class="function">errcontext(const char *msg, ...)</code> is not normally called150 directly from an <code class="function">ereport</code> message site; rather it is used151 in <code class="literal">error_context_stack</code> callback functions to provide152 information about the context in which an error occurred, such as the153 current location in a PL function.154 The message string is processed in just the same way as for155 <code class="function">errmsg</code>. Unlike the other auxiliary functions, this can156 be called more than once per <code class="function">ereport</code> call; the successive157 strings thus supplied are concatenated with separating newlines.158 </p></li><li class="listitem"><p>159 <code class="function">errposition(int cursorpos)</code> specifies the textual location160 of an error within a query string. Currently it is only useful for161 errors detected in the lexical and syntactic analysis phases of162 query processing.163 </p></li><li class="listitem"><p>164 <code class="function">errtable(Relation rel)</code> specifies a relation whose165 name and schema name should be included as auxiliary fields in the error166 report.167 </p></li><li class="listitem"><p>168 <code class="function">errtablecol(Relation rel, int attnum)</code> specifies169 a column whose name, table name, and schema name should be included as170 auxiliary fields in the error report.171 </p></li><li class="listitem"><p>172 <code class="function">errtableconstraint(Relation rel, const char *conname)</code>173 specifies a table constraint whose name, table name, and schema name174 should be included as auxiliary fields in the error report. Indexes175 should be considered to be constraints for this purpose, whether or176 not they have an associated <code class="structname">pg_constraint</code> entry. Be177 careful to pass the underlying heap relation, not the index itself, as178 <code class="literal">rel</code>.179 </p></li><li class="listitem"><p>180 <code class="function">errdatatype(Oid datatypeOid)</code> specifies a data181 type whose name and schema name should be included as auxiliary fields182 in the error report.183 </p></li><li class="listitem"><p>184 <code class="function">errdomainconstraint(Oid datatypeOid, const char *conname)</code>185 specifies a domain constraint whose name, domain name, and schema name186 should be included as auxiliary fields in the error report.187 </p></li><li class="listitem"><p>188 <code class="function">errcode_for_file_access()</code> is a convenience function that189 selects an appropriate SQLSTATE error identifier for a failure in a190 file-access-related system call. It uses the saved191 <code class="literal">errno</code> to determine which error code to generate.192 Usually this should be used in combination with <code class="literal">%m</code> in the193 primary error message text.194 </p></li><li class="listitem"><p>195 <code class="function">errcode_for_socket_access()</code> is a convenience function that196 selects an appropriate SQLSTATE error identifier for a failure in a197 socket-related system call.198 </p></li><li class="listitem"><p>199 <code class="function">errhidestmt(bool hide_stmt)</code> can be called to specify200 suppression of the <code class="literal">STATEMENT:</code> portion of a message in the201 postmaster log. Generally this is appropriate if the message text202 includes the current statement already.203 </p></li><li class="listitem"><p>204 <code class="function">errhidecontext(bool hide_ctx)</code> can be called to205 specify suppression of the <code class="literal">CONTEXT:</code> portion of a message in206 the postmaster log. This should only be used for verbose debugging207 messages where the repeated inclusion of context would bloat the log208 too much.209 </p></li></ul></div><p>210 </p><div class="note"><h3 class="title">Note</h3><p>211 At most one of the functions <code class="function">errtable</code>,212 <code class="function">errtablecol</code>, <code class="function">errtableconstraint</code>,213 <code class="function">errdatatype</code>, or <code class="function">errdomainconstraint</code> should214 be used in an <code class="function">ereport</code> call. These functions exist to215 allow applications to extract the name of a database object associated216 with the error condition without having to examine the217 potentially-localized error message text.218 These functions should be used in error reports for which it's likely219 that applications would wish to have automatic error handling. As of220 <span class="productname">PostgreSQL</span> 9.3, complete coverage exists only for221 errors in SQLSTATE class 23 (integrity constraint violation), but this222 is likely to be expanded in future.223 </p></div><p>224 There is an older function <code class="function">elog</code> that is still heavily used.225 An <code class="function">elog</code> call:226</p><pre class="programlisting">227elog(level, "format string", ...);228</pre><p>229 is exactly equivalent to:230</p><pre class="programlisting">231ereport(level, errmsg_internal("format string", ...));232</pre><p>233 Notice that the SQLSTATE error code is always defaulted, and the message234 string is not subject to translation.235 Therefore, <code class="function">elog</code> should be used only for internal errors and236 low-level debug logging. Any message that is likely to be of interest to237 ordinary users should go through <code class="function">ereport</code>. Nonetheless,238 there are enough internal <span class="quote">“<span class="quote">cannot happen</span>”</span> error checks in the239 system that <code class="function">elog</code> is still widely used; it is preferred for240 those messages for its notational simplicity.241 </p><p>242 Advice about writing good error messages can be found in243 <a class="xref" href="error-style-guide.html" title="56.3. Error Message Style Guide">Section 56.3</a>.244 </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>245 That is, the value that was current when the <code class="function">ereport</code> call246 was reached; changes of <code class="literal">errno</code> within the auxiliary reporting247 routines will not affect it. That would not be true if you were to248 write <code class="literal">strerror(errno)</code> explicitly in <code class="function">errmsg</code>'s249 parameter list; accordingly, do not do so.250 </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 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 56.3. Error Message Style Guide</td></tr></table></div></body></html>