1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>44.2.Reporting Errors Within the Server</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="source.html" title="Chapter44.PostgreSQL Coding Conventions">
<link rel="prev" href="source.html" title="Chapter44.PostgreSQL Coding Conventions">
<link rel="next" href="error-style-guide.html" title="44.3.Error Message Style Guide">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="error-message-reporting"></a>44.2.Reporting Errors Within the Server</h2></div></div></div>
<a name="id839041"></a><a name="id839047"></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 function, that exists
mainly for the syntactic convenience of making message generation
look like a 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. Notice the
extra set of parentheses surrounding the auxiliary function calls [mdash ]
these are annoying but syntactically necessary.
</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,
actual_arg_types)),
errhint("Unable to choose a best candidate function. "
"You may 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">hint</span>” message is provided.
</p>
<p> The available auxiliary routines for <code class="function">ereport</code> are:
</p>
<div class="itemizedlist"><ul type="disc">
<li><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><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>.
<sup>[<a name="id839319" href="#ftn.id839319">9</a>]</sup>
<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><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
included in the internationalization message dictionary.
This should be used for “<span class="quote">can't happen</span>” cases that are probably
not worth expending translation effort on.
</p></li>
<li><p> <code class="function">errdetail(const char *msg, ...)</code> supplies an optional
“<span class="quote">detail</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><p> <code class="function">errhint(const char *msg, ...)</code> supplies an optional
“<span class="quote">hint</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><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><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><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><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>
</ul></div>
<p>
</p>
<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 errcode is always defaulted, and the message
string is not included in the internationalization message dictionary.
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">can't happen</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 href="error-style-guide.html" title="44.3.Error Message Style Guide">Section44.3, “Error Message Style Guide”</a>.
</p>
<div class="footnotes">
<br><hr width="100" align="left">
<div class="footnote"><p><sup>[<a name="ftn.id839319" href="#id839319">9</a>] </sup> 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></body>
</html>
|
