PostgreSQL 8.4.22 Documentation | ||||
---|---|---|---|---|
Prev | Fast Backward | Chapter 46. PostgreSQL Coding Conventions | Fast Forward | Next |
Error, warning, and log messages generated within the server
code should be created using ereport
, or its older cousin elog
. The use of this function is complex
enough to require some explanation.
There are two required elements for every message: a severity
level (ranging from DEBUG to PANIC) 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.
ereport
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 ereport
is the severity level. The primary
message text and any optional message elements are generated by
calling auxiliary functions, such as errmsg
, within the ereport
call.
A typical call to ereport
might
look like this:
ereport(ERROR, (errcode(ERRCODE_DIVISION_BY_ZERO), errmsg("division by zero")));
This specifies error severity level ERROR (a run-of-the-mill error). The errcode
call specifies the SQLSTATE error code
using a macro defined in src/include/utils/errcodes.h. The errmsg
call provides the primary message text.
Notice the extra set of parentheses surrounding the auxiliary
function calls — these are annoying but syntactically
necessary.
Here is a more complex example:
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 might need to add explicit typecasts.")));
This illustrates the use of format codes to embed run-time values into a message text. Also, an optional "hint" message is provided.
The available auxiliary routines for ereport
are:
errcode(sqlerrcode)
specifies the SQLSTATE error identifier code for the
condition. If this routine is not called, the error
identifier defaults to ERRCODE_INTERNAL_ERROR when the error severity
level is ERROR or higher, ERRCODE_WARNING when the error level is
WARNING, otherwise (for NOTICE and below) ERRCODE_SUCCESSFUL_COMPLETION. While these
defaults are often convenient, always think whether they are
appropriate before omitting the errcode()
call.
errmsg(const char *msg, ...)
specifies the primary error message text, and possibly
run-time values to insert into it. Insertions are specified
by sprintf
-style format codes.
In addition to the standard format codes accepted by
sprintf
, the format code
%m can be used to insert the error
message returned by strerror
for the current value of errno.
[1] %m does not require any corresponding entry in
the parameter list for errmsg
.
Note that the message string will be run through gettext
for possible localization before
format codes are processed.
errmsg_internal(const char *msg,
...)
is the same as errmsg
, except that the message string will
not be translated nor included in the internationalization
message dictionary. This should be used for "cannot happen" cases that are probably not
worth expending translation effort on.
errmsg_plural(const char
*fmt_singular, const char *fmt_plural, unsigned long n,
...)
is like errmsg
, but
with support for various plural forms of the message.
fmt_singular is the English
singular format, fmt_plural
is the English plural format, n 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 Section 47.2.2.
errdetail(const char *msg,
...)
supplies an optional "detail" 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 errmsg
.
errdetail_log(const char *msg,
...)
is the same as errdetail
except that this string goes only
to the server log, never to the client. If both errdetail
and errdetail_log
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.
errdetail_plural(const char
*fmt_singular, const char *fmt_plural, unsigned long n,
...)
is like errdetail
,
but with support for various plural forms of the message. For
more information see Section 47.2.2.
errhint(const char *msg,
...)
supplies an optional "hint" 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 errmsg
.
errcontext(const char *msg,
...)
is not normally called directly from an
ereport
message site; rather it
is used in error_context_stack
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 errmsg
. Unlike the
other auxiliary functions, this can be called more than once
per ereport
call; the
successive strings thus supplied are concatenated with
separating newlines.
errposition(int cursorpos)
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.
errcode_for_file_access()
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 errno
to determine which error code to generate. Usually this
should be used in combination with %m in the primary error message text.
errcode_for_socket_access()
is a convenience function that selects an appropriate
SQLSTATE error identifier for a failure in a socket-related
system call.
errhidestmt(bool hide_stmt)
can be called to specify suppression of the STATEMENT: portion of a message in the
postmaster log. Generally this is appropriate if the message
text includes the current statement already.
There is an older function elog
that is still heavily used. An elog
call:
elog(level, "format string", ...);
is exactly equivalent to:
ereport(level, (errmsg_internal("format string", ...)));
Notice that the SQLSTATE error code is always defaulted, and
the message string is not subject to translation. Therefore,
elog
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
ereport
. Nonetheless, there are
enough internal "cannot happen" error
checks in the system that elog
is
still widely used; it is preferred for those messages for its
notational simplicity.
Advice about writing good error messages can be found in Section 46.3.
[1] |
That is, the value that was current when the |