File: error-message-reporting.html

package info (click to toggle)
postgresql-9.1 9.1.15-0%2Bdeb8u1
links: PTS, VCS
area: main
in suites: jessie-kfreebsd
size: 109,092 kB
sloc: ansic: 575,877; sql: 43,887; yacc: 26,399; perl: 6,352; lex: 6,171; sh: 5,282; makefile: 3,772; asm: 65; sed: 15; python: 12
file content (675 lines) | stat: -rw-r--r-- 14,124 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Reporting Errors Within the Server</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.1.15 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="PostgreSQL Coding Conventions"
HREF="source.html"><LINK
REL="PREVIOUS"
TITLE="Formatting"
HREF="source-format.html"><LINK
REL="NEXT"
TITLE="Error Message Style Guide"
HREF="error-style-guide.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2015-02-02T21:03:01"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.1.15 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Formatting"
HREF="source-format.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="source.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 47. PostgreSQL Coding Conventions</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Error Message Style Guide"
HREF="error-style-guide.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="ERROR-MESSAGE-REPORTING"
>47.2. Reporting Errors Within the Server</A
></H1
><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 <TT
CLASS="LITERAL"
>DEBUG</TT
> to <TT
CLASS="LITERAL"
>PANIC</TT
>) 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 <TT
CLASS="LITERAL"
>ERROR</TT
> (a run-of-the-mill
    error).  The <CODE
CLASS="FUNCTION"
>errcode</CODE
> call specifies the SQLSTATE error code
    using a macro defined in <TT
CLASS="FILENAME"
>src/include/utils/errcodes.h</TT
>.  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,
                                      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"
>"hint"</SPAN
> message is provided.
   </P
><P
>    The available auxiliary routines for <CODE
CLASS="FUNCTION"
>ereport</CODE
> are:
  <P
></P
></P><UL
><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
     <TT
CLASS="LITERAL"
>ERRCODE_INTERNAL_ERROR</TT
> when the error severity level is
     <TT
CLASS="LITERAL"
>ERROR</TT
> or higher, <TT
CLASS="LITERAL"
>ERRCODE_WARNING</TT
> when the
     error level is <TT
CLASS="LITERAL"
>WARNING</TT
>, otherwise (for <TT
CLASS="LITERAL"
>NOTICE</TT
>
     and below) <TT
CLASS="LITERAL"
>ERRCODE_SUCCESSFUL_COMPLETION</TT
>.
     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 <TT
CLASS="LITERAL"
>%m</TT
> can be used to insert the error message returned
     by <CODE
CLASS="FUNCTION"
>strerror</CODE
> for the current value of <TT
CLASS="LITERAL"
>errno</TT
>.
     <A
NAME="AEN93437"
HREF="#FTN.AEN93437"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
>
     <TT
CLASS="LITERAL"
>%m</TT
> 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
     translated nor included in the internationalization message dictionary.
     This should be used for <SPAN
CLASS="QUOTE"
>"cannot happen"</SPAN
> cases that are probably
     not worth expending translation effort on.
    </P
></LI
><LI
><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.
     <TT
CLASS="REPLACEABLE"
><I
>fmt_singular</I
></TT
> is the English singular format,
     <TT
CLASS="REPLACEABLE"
><I
>fmt_plural</I
></TT
> is the English plural format,
     <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
> 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
HREF="nls-programmer.html#NLS-GUIDELINES"
>Section 48.2.2</A
>.
    </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"
>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
><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
HREF="nls-programmer.html#NLS-GUIDELINES"
>Section 48.2.2</A
>.
    </P
></LI
><LI
><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
><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 <TT
CLASS="LITERAL"
>error_context_stack</TT
> 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
     <TT
CLASS="LITERAL"
>errno</TT
> to determine which error code to generate.
     Usually this should be used in combination with <TT
CLASS="LITERAL"
>%m</TT
> 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
><LI
><P
>     <CODE
CLASS="FUNCTION"
>errhidestmt(bool hide_stmt)</CODE
> can be called to specify
     suppression of the <TT
CLASS="LITERAL"
>STATEMENT:</TT
> portion of a message in the
     postmaster log.  Generally this is appropriate if the message text
     includes the current statement already.
    </P
></LI
></UL
><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 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"
>"cannot 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"
>Section 47.3</A
>.
   </P
></DIV
><H3
CLASS="FOOTNOTES"
>Notes</H3
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN93437"
HREF="error-message-reporting.html#AEN93437"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>       That is, the value that was current when the <CODE
CLASS="FUNCTION"
>ereport</CODE
> call
       was reached; changes of <TT
CLASS="LITERAL"
>errno</TT
> within the auxiliary reporting
       routines will not affect it.  That would not be true if you were to
       write <TT
CLASS="LITERAL"
>strerror(errno)</TT
> explicitly in <CODE
CLASS="FUNCTION"
>errmsg</CODE
>'s
       parameter list; accordingly, do not do so.
      </P
></TD
></TR
></TABLE
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="source-format.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="error-style-guide.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Formatting</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="source.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Error Message Style Guide</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>