sources.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

<!--
$PostgreSQL: pgsql/doc/src/sgml/sources.sgml,v 2.16 2004/12/13 18:05:09 petere Exp $
-->

 <chapter id="source">
  <title>PostgreSQL Coding Conventions</title>

  <sect1 id="source-format">
   <title>Formatting</title>

   <para>
    Source code formatting uses 4 column tab spacing, with 
    tabs preserved (i.e. tabs are not expanded to spaces).
    Each logical indentation level is one additional tab stop.
    Layout rules (brace positioning, etc) follow BSD conventions.
   </para>

   <para>
    While submitted patches do not absolutely have to follow these formatting
    rules, it's a good idea to do so.  Your code will get run through
    <application>pgindent</>, so there's no point in making it look nice
    under some other set of formatting conventions.
   </para>

   <para>
    For <productname>Emacs</productname>, add the following (or
    something similar) to your <filename>~/.emacs</filename> 
    initialization file:

<programlisting>
;; check for files with a path containing "postgres" or "pgsql"
(setq auto-mode-alist
  (cons '("\\(postgres\\|pgsql\\).*\\.[ch]\\'" . pgsql-c-mode)
        auto-mode-alist))
(setq auto-mode-alist
  (cons '("\\(postgres\\|pgsql\\).*\\.cc\\'" . pgsql-c-mode)
        auto-mode-alist))

(defun pgsql-c-mode ()
  ;; sets up formatting for PostgreSQL C code
  (interactive)
  (c-mode)
  (setq-default tab-width 4)
  (c-set-style "bsd")             ; set c-basic-offset to 4, plus other stuff
  (c-set-offset 'case-label '+)   ; tweak case indent to match PG custom
  (setq indent-tabs-mode t))      ; make sure we keep tabs when indenting
</programlisting>
   </para>

   <para>
    For <application>vi</application>, your
    <filename>~/.vimrc</filename> or equivalent file should contain
    the following:

<programlisting>
set tabstop=4
</programlisting>

    or equivalently from within <application>vi</application>, try

<programlisting>
:set ts=4
</programlisting>
   </para>

   <para>
    The text browsing tools <application>more</application> and
    <application>less</application> can be invoked as
<programlisting>
more -x4
less -x4
</programlisting>
    to make them show tabs appropriately.
   </para>
  </sect1>

  <sect1 id="error-message-reporting">
   <title>Reporting Errors Within the Server</title>

   <indexterm>
    <primary>ereport</primary>
   </indexterm>
   <indexterm>
    <primary>elog</primary>
   </indexterm>

   <para>
    Error, warning, and log messages generated within the server code
    should be created using <function>ereport</>, or its older cousin
    <function>elog</>.  The use of this function is complex enough to
    require some explanation.
   </para>

   <para>
    There are two required elements for every message: a severity level
    (ranging from <literal>DEBUG</> to <literal>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.
    <function>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 <function>ereport</> is the severity level.
    The primary message text and any optional message elements are
    generated by calling auxiliary functions, such as <function>errmsg</>,
    within the <function>ereport</> call.
   </para>

   <para>
    A typical call to <function>ereport</> might look like this:
<programlisting>
ereport(ERROR,
        (errcode(ERRCODE_DIVISION_BY_ZERO),
         errmsg("division by zero")));
</programlisting>
    This specifies error severity level <literal>ERROR</> (a run-of-the-mill
    error).  The <function>errcode</> call specifies the SQLSTATE error code
    using a macro defined in <filename>src/include/utils/errcodes.h</>.  The
    <function>errmsg</> call provides the primary message text.  Notice the
    extra set of parentheses surrounding the auxiliary function calls &mdash;
    these are annoying but syntactically necessary.
   </para>

   <para>
    Here is a more complex example:
<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.")));
</programlisting>
    This illustrates the use of format codes to embed run-time values into
    a message text.  Also, an optional <quote>hint</> message is provided.
   </para>

   <para>
    The available auxiliary routines for <function>ereport</> are:
  <itemizedlist>
   <listitem>
    <para>
     <function>errcode(sqlerrcode)</function> specifies the SQLSTATE error identifier
     code for the condition.  If this routine is not called, the error
     identifier defaults to
     <literal>ERRCODE_INTERNAL_ERROR</> when the error severity level is
     <literal>ERROR</> or higher, <literal>ERRCODE_WARNING</> when the
     error level is <literal>WARNING</>, otherwise (for <literal>NOTICE</>
     and below) <literal>ERRCODE_SUCCESSFUL_COMPLETION</>.
     While these defaults are often convenient, always think whether they
     are appropriate before omitting the <function>errcode()</> call.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>errmsg(const char *msg, ...)</function> specifies the primary error
     message text, and possibly run-time values to insert into it.  Insertions
     are specified by <function>sprintf</>-style format codes.  In addition to
     the standard format codes accepted by <function>sprintf</>, the format
     code <literal>%m</> can be used to insert the error message returned
     by <function>strerror</> for the current value of <literal>errno</>.
     <footnote>
      <para>
       That is, the value that was current when the <function>ereport</> call
       was reached; changes of <literal>errno</> within the auxiliary reporting
       routines will not affect it.  That would not be true if you were to
       write <literal>strerror(errno)</> explicitly in <function>errmsg</>'s
       parameter list; accordingly, do not do so.
      </para>
     </footnote>
     <literal>%m</> does not require any
     corresponding entry in the parameter list for <function>errmsg</>.
     Note that the message string will be run through <function>gettext</>
     for possible localization before format codes are processed.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>errmsg_internal(const char *msg, ...)</function> is the same as
     <function>errmsg</>, except that the message string will not be
     included in the internationalization message dictionary.
     This should be used for <quote>can't happen</> cases that are probably
     not worth expending translation effort on.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>errdetail(const char *msg, ...)</function> supplies an optional
     <quote>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
     <function>errmsg</>.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>errhint(const char *msg, ...)</function> supplies an optional
     <quote>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
     <function>errmsg</>.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>errcontext(const char *msg, ...)</function> is not normally called
     directly from an <function>ereport</> message site; rather it is used
     in <literal>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
     <function>errmsg</>.  Unlike the other auxiliary functions, this can
     be called more than once per <function>ereport</> call; the successive
     strings thus supplied are concatenated with separating newlines.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>errposition(int cursorpos)</function> 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.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>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
     <literal>errno</> to determine which error code to generate.
     Usually this should be used in combination with <literal>%m</> in the
     primary error message text.
    </para>
   </listitem>
   <listitem>
    <para>
     <function>errcode_for_socket_access()</> is a convenience function that
     selects an appropriate SQLSTATE error identifier for a failure in a
     socket-related system call.
    </para>
   </listitem>
  </itemizedlist>
   </para>

   <para>
    There is an older function <function>elog</> that is still heavily used.
    An <function>elog</> call
<programlisting>
elog(level, "format string", ...);
</programlisting>
    is exactly equivalent to
<programlisting>
ereport(level, (errmsg_internal("format string", ...)));
</programlisting>
    Notice that the SQLSTATE errcode is always defaulted, and the message
    string is not included in the internationalization message dictionary.
    Therefore, <function>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 <function>ereport</>.  Nonetheless,
    there are enough internal <quote>can't happen</> error checks in the
    system that <function>elog</> is still widely used; it is preferred for
    those messages for its notational simplicity.
   </para>

   <para>
    Advice about writing good error messages can be found in
    <xref linkend="error-style-guide">.
   </para>
  </sect1>

  <sect1 id="error-style-guide">
   <title>Error Message Style Guide</title>

   <para>
    This style guide is offered in the hope of maintaining a consistent,
    user-friendly style throughout all the messages generated by
    <productname>PostgreSQL</>.
   </para>

  <simplesect>
   <title>What goes where</title>

   <para>
    The primary message should be short, factual, and avoid reference to
    implementation details such as specific function names.
    <quote>Short</quote> means <quote>should fit on one line under normal
    conditions</quote>.  Use a detail message if needed to keep the primary
    message short, or if you feel a need to mention implementation details
    such as the particular system call that failed. Both primary and detail
    messages should be factual.  Use a hint message for suggestions about what
    to do to fix the problem, especially if the suggestion might not always be
    applicable.
   </para>

   <para>
    For example, instead of
<programlisting>
IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
(plus a long addendum that is basically a hint)
</programlisting>
    write
<programlisting>
Primary:    could not create shared memory segment: %m
Detail:     Failed syscall was shmget(key=%d, size=%u, 0%o).
Hint:       the addendum
</programlisting>
   </para>

   <para>
    Rationale: keeping the primary message short helps keep it to the point,
    and lets clients lay out screen space on the assumption that one line is
    enough for error messages.  Detail and hint messages may be relegated to a
    verbose mode, or perhaps a pop-up error-details window.  Also, details and
    hints would normally be suppressed from the server log to save
    space. Reference to implementation details is best avoided since users
    don't know the details anyway.
   </para>

  </simplesect>

  <simplesect>
   <title>Formatting</title>

   <para>
    Don't put any specific assumptions about formatting into the message
    texts.  Expect clients and the server log to wrap lines to fit their own
    needs.  In long messages, newline characters (\n) may be used to indicate
    suggested paragraph breaks.  Don't end a message with a newline.  Don't
    use tabs or other formatting characters.  (In error context displays,
    newlines are automatically added to separate levels of context such as
    function calls.)
   </para>

   <para>
    Rationale: Messages are not necessarily displayed on terminal-type
    displays.  In GUI displays or browsers these formatting instructions are
    at best ignored.
   </para>

  </simplesect>

  <simplesect>
   <title>Quotation marks</title>

   <para>
    English text should use double quotes when quoting is appropriate.
    Text in other languages should consistently use one kind of quotes that is
    consistent with publishing customs and computer output of other programs.
   </para>

   <para>
    Rationale: The choice of double quotes over single quotes is somewhat
    arbitrary, but tends to be the preferred use.  Some have suggested
    choosing the kind of quotes depending on the type of object according to
    SQL conventions (namely, strings single quoted, identifiers double
    quoted).  But this is a language-internal technical issue that many users