| PostgreSQL 8.0.1 Documentation | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Chapter 43. PostgreSQL Coding Conventions | Fast Forward | Next |
43.2. Reporting Errors Within the Server
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:
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:
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 theerrcode()call.errmsg(const char *msg, ...)specifies the primary error message text, and possibly run-time values to insert into it. Insertions are specified bysprintf-style format codes. In addition to the standard format codes accepted bysprintf, the format code %m can be used to insert the error message returned bystrerrorfor the current value of errno. [1] %m does not require any corresponding entry in the parameter list forerrmsg. Note that the message string will be run throughgettextfor possible localization before format codes are processed.errmsg_internal(const char *msg, ...)is the same aserrmsg, except that the message string will not be included in the internationalization message dictionary. This should be used for "can't happen" cases that are probably not worth expending translation effort on.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 forerrmsg.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 forerrmsg.errcontext(const char *msg, ...)is not normally called directly from anereportmessage 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 forerrmsg. Unlike the other auxiliary functions, this can be called more than once perereportcall; 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.
There is an older function elog that is still heavily used. An elog call
is exactly equivalent to
Notice that the SQLSTATE errcode is always defaulted, and the message string is not included in the internationalization message dictionary. 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 "can't 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 43.3.
Notes
| [1] | That is, the value that was current when the |
