2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/sources.sgml -->
|
2000-03-31 05:27:42 +02:00
|
|
|
|
2000-09-29 22:21:34 +02:00
|
|
|
<chapter id="source">
|
2003-06-22 18:17:01 +02:00
|
|
|
<title>PostgreSQL Coding Conventions</title>
|
2000-02-02 17:25:04 +01:00
|
|
|
|
2000-09-29 22:21:34 +02:00
|
|
|
<sect1 id="source-format">
|
2000-02-02 17:25:04 +01:00
|
|
|
<title>Formatting</title>
|
|
|
|
|
|
|
|
<para>
|
2008-09-07 04:01:04 +02:00
|
|
|
Source code formatting uses 4 column tab spacing, with
|
|
|
|
tabs preserved (i.e., tabs are not expanded to spaces).
|
2003-05-19 23:38:24 +02:00
|
|
|
Each logical indentation level is one additional tab stop.
|
2008-09-07 04:01:04 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Layout rules (brace positioning, etc) follow BSD conventions. In
|
2017-10-09 03:44:17 +02:00
|
|
|
particular, curly braces for the controlled blocks of <literal>if</literal>,
|
|
|
|
<literal>while</literal>, <literal>switch</literal>, etc go on their own lines.
|
2008-09-07 04:01:04 +02:00
|
|
|
</para>
|
|
|
|
|
2010-07-10 20:37:00 +02:00
|
|
|
<para>
|
|
|
|
Limit line lengths so that the code is readable in an 80-column window.
|
|
|
|
(This doesn't mean that you must never go past 80 columns. For instance,
|
|
|
|
breaking a long error message string in arbitrary places just to keep the
|
|
|
|
code within 80 columns is probably not a net gain in readability.)
|
|
|
|
</para>
|
|
|
|
|
2008-09-07 04:01:04 +02:00
|
|
|
<para>
|
2019-09-26 10:51:39 +02:00
|
|
|
To maintain a consistent coding style, do not use C++ style comments
|
|
|
|
(<literal>//</literal> comments). <application>pgindent</application>
|
|
|
|
will replace them with <literal>/* ... */</literal>.
|
2008-09-07 04:01:04 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The preferred style for multi-line comment blocks is
|
|
|
|
<programlisting>
|
|
|
|
/*
|
|
|
|
* comment text begins here
|
|
|
|
* and continues here
|
|
|
|
*/
|
|
|
|
</programlisting>
|
|
|
|
Note that comment blocks that begin in column 1 will be preserved as-is
|
2017-10-09 03:44:17 +02:00
|
|
|
by <application>pgindent</application>, but it will re-flow indented comment blocks
|
2008-09-07 04:01:04 +02:00
|
|
|
as though they were plain text. If you want to preserve the line breaks
|
|
|
|
in an indented block, add dashes like this:
|
|
|
|
<programlisting>
|
|
|
|
/*----------
|
|
|
|
* comment text begins here
|
|
|
|
* and continues here
|
|
|
|
*----------
|
|
|
|
*/
|
|
|
|
</programlisting>
|
2003-05-19 23:38:24 +02:00
|
|
|
</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
|
2017-10-09 03:44:17 +02:00
|
|
|
<application>pgindent</application> before the next release, so there's no point in
|
2008-09-07 04:01:04 +02:00
|
|
|
making it look nice under some other set of formatting conventions.
|
2010-07-10 20:37:00 +02:00
|
|
|
A good rule of thumb for patches is <quote>make the new code look like
|
2017-10-09 03:44:17 +02:00
|
|
|
the existing code around it</quote>.
|
2000-02-02 17:25:04 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2021-09-20 16:48:02 +02:00
|
|
|
The <filename>src/tools/editors</filename> directory contains sample settings
|
2022-04-13 07:42:13 +02:00
|
|
|
files that can be used with the <productname>Emacs</productname>,
|
2008-09-07 04:01:04 +02:00
|
|
|
<productname>xemacs</productname> or <productname>vim</productname>
|
|
|
|
editors to help ensure that they format code according to these
|
2007-02-01 23:06:14 +01:00
|
|
|
conventions.
|
2000-02-02 17:25:04 +01:00
|
|
|
</para>
|
2021-09-20 16:48:02 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
If you'd like to run <application>pgindent</application> locally
|
|
|
|
to help make your code match project style, see
|
|
|
|
the <filename>src/tools/pgindent</filename> directory.
|
|
|
|
</para>
|
2000-02-02 17:25:04 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
The text browsing tools <application>more</application> and
|
2007-02-01 01:28:19 +01:00
|
|
|
<application>less</application> can be invoked as:
|
2001-10-09 20:46:00 +02:00
|
|
|
<programlisting>
|
2000-02-02 17:25:04 +01:00
|
|
|
more -x4
|
|
|
|
less -x4
|
2001-10-09 20:46:00 +02:00
|
|
|
</programlisting>
|
2003-05-19 23:38:24 +02:00
|
|
|
to make them show tabs appropriately.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="error-message-reporting">
|
|
|
|
<title>Reporting Errors Within the Server</title>
|
|
|
|
|
2003-06-22 18:17:01 +02:00
|
|
|
<indexterm>
|
|
|
|
<primary>ereport</primary>
|
|
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
|
|
<primary>elog</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2003-05-19 23:38:24 +02:00
|
|
|
<para>
|
|
|
|
Error, warning, and log messages generated within the server code
|
2017-10-09 03:44:17 +02:00
|
|
|
should be created using <function>ereport</function>, or its older cousin
|
|
|
|
<function>elog</function>. The use of this function is complex enough to
|
2003-05-19 23:38:24 +02:00
|
|
|
require some explanation.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There are two required elements for every message: a severity level
|
2017-10-09 03:44:17 +02:00
|
|
|
(ranging from <literal>DEBUG</literal> to <literal>PANIC</literal>) and a primary
|
2003-05-19 23:38:24 +02:00
|
|
|
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.
|
2020-12-24 09:05:49 +01:00
|
|
|
<function>ereport</function> itself is just a shell macro that exists
|
2003-05-19 23:38:24 +02:00
|
|
|
mainly for the syntactic convenience of making message generation
|
Re-implement the ereport() macro using __VA_ARGS__.
Now that we require C99, we can depend on __VA_ARGS__ to work, and
revising ereport() to use it has several significant benefits:
* The extra parentheses around the auxiliary function calls are now
optional. Aside from being a bit less ugly, this removes a common
gotcha for new contributors, because in some cases the compiler errors
you got from forgetting them were unintelligible.
* The auxiliary function calls are now evaluated as a comma expression
list rather than as extra arguments to errfinish(). This means that
compilers can be expected to warn about no-op expressions in the list,
allowing detection of several other common mistakes such as forgetting
to add errmsg(...) when converting an elog() call to ereport().
* Unlike the situation with extra function arguments, comma expressions
are guaranteed to be evaluated left-to-right, so this removes platform
dependency in the order of the auxiliary function calls. While that
dependency hasn't caused us big problems in the past, this change does
allow dropping some rather shaky assumptions around errcontext() domain
handling.
There's no intention to make wholesale changes of existing ereport
calls, but as proof-of-concept this patch removes the extra parens
from a couple of calls in postgres.c.
While new code can be written either way, code intended to be
back-patched will need to use extra parens for awhile yet. It seems
worth back-patching this change into v12, so as to reduce the window
where we have to be careful about that by one year. Hence, this patch
is careful to preserve ABI compatibility; a followup HEAD-only patch
will make some additional simplifications.
Andres Freund and Tom Lane
Discussion: https://postgr.es/m/CA+fd4k6N8EjNvZpM8nme+y+05mz-SM8Z_BgkixzkA34R+ej0Kw@mail.gmail.com
2020-03-24 16:48:33 +01:00
|
|
|
look like a single function call in the C source code. The only parameter
|
2017-10-09 03:44:17 +02:00
|
|
|
accepted directly by <function>ereport</function> is the severity level.
|
2003-05-19 23:38:24 +02:00
|
|
|
The primary message text and any optional message elements are
|
2017-10-09 03:44:17 +02:00
|
|
|
generated by calling auxiliary functions, such as <function>errmsg</function>,
|
|
|
|
within the <function>ereport</function> call.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
A typical call to <function>ereport</function> might look like this:
|
2003-05-19 23:38:24 +02:00
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
ereport(ERROR,
|
Re-implement the ereport() macro using __VA_ARGS__.
Now that we require C99, we can depend on __VA_ARGS__ to work, and
revising ereport() to use it has several significant benefits:
* The extra parentheses around the auxiliary function calls are now
optional. Aside from being a bit less ugly, this removes a common
gotcha for new contributors, because in some cases the compiler errors
you got from forgetting them were unintelligible.
* The auxiliary function calls are now evaluated as a comma expression
list rather than as extra arguments to errfinish(). This means that
compilers can be expected to warn about no-op expressions in the list,
allowing detection of several other common mistakes such as forgetting
to add errmsg(...) when converting an elog() call to ereport().
* Unlike the situation with extra function arguments, comma expressions
are guaranteed to be evaluated left-to-right, so this removes platform
dependency in the order of the auxiliary function calls. While that
dependency hasn't caused us big problems in the past, this change does
allow dropping some rather shaky assumptions around errcontext() domain
handling.
There's no intention to make wholesale changes of existing ereport
calls, but as proof-of-concept this patch removes the extra parens
from a couple of calls in postgres.c.
While new code can be written either way, code intended to be
back-patched will need to use extra parens for awhile yet. It seems
worth back-patching this change into v12, so as to reduce the window
where we have to be careful about that by one year. Hence, this patch
is careful to preserve ABI compatibility; a followup HEAD-only patch
will make some additional simplifications.
Andres Freund and Tom Lane
Discussion: https://postgr.es/m/CA+fd4k6N8EjNvZpM8nme+y+05mz-SM8Z_BgkixzkA34R+ej0Kw@mail.gmail.com
2020-03-24 16:48:33 +01:00
|
|
|
errcode(ERRCODE_DIVISION_BY_ZERO),
|
|
|
|
errmsg("division by zero"));
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
2017-10-09 03:44:17 +02:00
|
|
|
This specifies error severity level <literal>ERROR</literal> (a run-of-the-mill
|
|
|
|
error). The <function>errcode</function> call specifies the SQLSTATE error code
|
|
|
|
using a macro defined in <filename>src/include/utils/errcodes.h</filename>. The
|
Re-implement the ereport() macro using __VA_ARGS__.
Now that we require C99, we can depend on __VA_ARGS__ to work, and
revising ereport() to use it has several significant benefits:
* The extra parentheses around the auxiliary function calls are now
optional. Aside from being a bit less ugly, this removes a common
gotcha for new contributors, because in some cases the compiler errors
you got from forgetting them were unintelligible.
* The auxiliary function calls are now evaluated as a comma expression
list rather than as extra arguments to errfinish(). This means that
compilers can be expected to warn about no-op expressions in the list,
allowing detection of several other common mistakes such as forgetting
to add errmsg(...) when converting an elog() call to ereport().
* Unlike the situation with extra function arguments, comma expressions
are guaranteed to be evaluated left-to-right, so this removes platform
dependency in the order of the auxiliary function calls. While that
dependency hasn't caused us big problems in the past, this change does
allow dropping some rather shaky assumptions around errcontext() domain
handling.
There's no intention to make wholesale changes of existing ereport
calls, but as proof-of-concept this patch removes the extra parens
from a couple of calls in postgres.c.
While new code can be written either way, code intended to be
back-patched will need to use extra parens for awhile yet. It seems
worth back-patching this change into v12, so as to reduce the window
where we have to be careful about that by one year. Hence, this patch
is careful to preserve ABI compatibility; a followup HEAD-only patch
will make some additional simplifications.
Andres Freund and Tom Lane
Discussion: https://postgr.es/m/CA+fd4k6N8EjNvZpM8nme+y+05mz-SM8Z_BgkixzkA34R+ej0Kw@mail.gmail.com
2020-03-24 16:48:33 +01:00
|
|
|
<function>errmsg</function> call provides the primary message text.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
You will also frequently see this older style, with an extra set of
|
|
|
|
parentheses surrounding the auxiliary function calls:
|
|
|
|
<programlisting>
|
|
|
|
ereport(ERROR,
|
|
|
|
(errcode(ERRCODE_DIVISION_BY_ZERO),
|
|
|
|
errmsg("division by zero")));
|
|
|
|
</programlisting>
|
|
|
|
The extra parentheses were required
|
|
|
|
before <productname>PostgreSQL</productname> version 12, but are now
|
|
|
|
optional.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here is a more complex example:
|
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
ereport(ERROR,
|
Re-implement the ereport() macro using __VA_ARGS__.
Now that we require C99, we can depend on __VA_ARGS__ to work, and
revising ereport() to use it has several significant benefits:
* The extra parentheses around the auxiliary function calls are now
optional. Aside from being a bit less ugly, this removes a common
gotcha for new contributors, because in some cases the compiler errors
you got from forgetting them were unintelligible.
* The auxiliary function calls are now evaluated as a comma expression
list rather than as extra arguments to errfinish(). This means that
compilers can be expected to warn about no-op expressions in the list,
allowing detection of several other common mistakes such as forgetting
to add errmsg(...) when converting an elog() call to ereport().
* Unlike the situation with extra function arguments, comma expressions
are guaranteed to be evaluated left-to-right, so this removes platform
dependency in the order of the auxiliary function calls. While that
dependency hasn't caused us big problems in the past, this change does
allow dropping some rather shaky assumptions around errcontext() domain
handling.
There's no intention to make wholesale changes of existing ereport
calls, but as proof-of-concept this patch removes the extra parens
from a couple of calls in postgres.c.
While new code can be written either way, code intended to be
back-patched will need to use extra parens for awhile yet. It seems
worth back-patching this change into v12, so as to reduce the window
where we have to be careful about that by one year. Hence, this patch
is careful to preserve ABI compatibility; a followup HEAD-only patch
will make some additional simplifications.
Andres Freund and Tom Lane
Discussion: https://postgr.es/m/CA+fd4k6N8EjNvZpM8nme+y+05mz-SM8Z_BgkixzkA34R+ej0Kw@mail.gmail.com
2020-03-24 16:48:33 +01:00
|
|
|
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."));
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
|
|
|
This illustrates the use of format codes to embed run-time values into
|
2017-10-09 03:44:17 +02:00
|
|
|
a message text. Also, an optional <quote>hint</quote> message is provided.
|
Re-implement the ereport() macro using __VA_ARGS__.
Now that we require C99, we can depend on __VA_ARGS__ to work, and
revising ereport() to use it has several significant benefits:
* The extra parentheses around the auxiliary function calls are now
optional. Aside from being a bit less ugly, this removes a common
gotcha for new contributors, because in some cases the compiler errors
you got from forgetting them were unintelligible.
* The auxiliary function calls are now evaluated as a comma expression
list rather than as extra arguments to errfinish(). This means that
compilers can be expected to warn about no-op expressions in the list,
allowing detection of several other common mistakes such as forgetting
to add errmsg(...) when converting an elog() call to ereport().
* Unlike the situation with extra function arguments, comma expressions
are guaranteed to be evaluated left-to-right, so this removes platform
dependency in the order of the auxiliary function calls. While that
dependency hasn't caused us big problems in the past, this change does
allow dropping some rather shaky assumptions around errcontext() domain
handling.
There's no intention to make wholesale changes of existing ereport
calls, but as proof-of-concept this patch removes the extra parens
from a couple of calls in postgres.c.
While new code can be written either way, code intended to be
back-patched will need to use extra parens for awhile yet. It seems
worth back-patching this change into v12, so as to reduce the window
where we have to be careful about that by one year. Hence, this patch
is careful to preserve ABI compatibility; a followup HEAD-only patch
will make some additional simplifications.
Andres Freund and Tom Lane
Discussion: https://postgr.es/m/CA+fd4k6N8EjNvZpM8nme+y+05mz-SM8Z_BgkixzkA34R+ej0Kw@mail.gmail.com
2020-03-24 16:48:33 +01:00
|
|
|
The auxiliary function calls can be written in any order, but
|
|
|
|
conventionally <function>errcode</function>
|
|
|
|
and <function>errmsg</function> appear first.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
2013-08-26 20:27:43 +02:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
If the severity level is <literal>ERROR</literal> or higher,
|
Re-implement the ereport() macro using __VA_ARGS__.
Now that we require C99, we can depend on __VA_ARGS__ to work, and
revising ereport() to use it has several significant benefits:
* The extra parentheses around the auxiliary function calls are now
optional. Aside from being a bit less ugly, this removes a common
gotcha for new contributors, because in some cases the compiler errors
you got from forgetting them were unintelligible.
* The auxiliary function calls are now evaluated as a comma expression
list rather than as extra arguments to errfinish(). This means that
compilers can be expected to warn about no-op expressions in the list,
allowing detection of several other common mistakes such as forgetting
to add errmsg(...) when converting an elog() call to ereport().
* Unlike the situation with extra function arguments, comma expressions
are guaranteed to be evaluated left-to-right, so this removes platform
dependency in the order of the auxiliary function calls. While that
dependency hasn't caused us big problems in the past, this change does
allow dropping some rather shaky assumptions around errcontext() domain
handling.
There's no intention to make wholesale changes of existing ereport
calls, but as proof-of-concept this patch removes the extra parens
from a couple of calls in postgres.c.
While new code can be written either way, code intended to be
back-patched will need to use extra parens for awhile yet. It seems
worth back-patching this change into v12, so as to reduce the window
where we have to be careful about that by one year. Hence, this patch
is careful to preserve ABI compatibility; a followup HEAD-only patch
will make some additional simplifications.
Andres Freund and Tom Lane
Discussion: https://postgr.es/m/CA+fd4k6N8EjNvZpM8nme+y+05mz-SM8Z_BgkixzkA34R+ej0Kw@mail.gmail.com
2020-03-24 16:48:33 +01:00
|
|
|
<function>ereport</function> aborts execution of the current query
|
|
|
|
and does not return to the caller. If the severity level is
|
2017-10-09 03:44:17 +02:00
|
|
|
lower than <literal>ERROR</literal>, <function>ereport</function> returns normally.
|
2013-08-26 20:27:43 +02:00
|
|
|
</para>
|
2013-11-10 15:20:52 +01:00
|
|
|
|
2003-05-19 23:38:24 +02:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The available auxiliary routines for <function>ereport</function> are:
|
2003-05-19 23:38:24 +02:00
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-12-13 19:05:10 +01:00
|
|
|
<function>errcode(sqlerrcode)</function> specifies the SQLSTATE error identifier
|
2003-07-19 01:20:33 +02:00
|
|
|
code for the condition. If this routine is not called, the error
|
|
|
|
identifier defaults to
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>ERRCODE_INTERNAL_ERROR</literal> when the error severity level is
|
|
|
|
<literal>ERROR</literal> or higher, <literal>ERRCODE_WARNING</literal> when the
|
|
|
|
error level is <literal>WARNING</literal>, otherwise (for <literal>NOTICE</literal>
|
|
|
|
and below) <literal>ERRCODE_SUCCESSFUL_COMPLETION</literal>.
|
2003-07-19 01:20:33 +02:00
|
|
|
While these defaults are often convenient, always think whether they
|
2017-10-09 03:44:17 +02:00
|
|
|
are appropriate before omitting the <function>errcode()</function> call.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-12-13 19:05:10 +01:00
|
|
|
<function>errmsg(const char *msg, ...)</function> specifies the primary error
|
2003-05-19 23:38:24 +02:00
|
|
|
message text, and possibly run-time values to insert into it. Insertions
|
2017-10-09 03:44:17 +02:00
|
|
|
are specified by <function>sprintf</function>-style format codes. In addition to
|
|
|
|
the standard format codes accepted by <function>sprintf</function>, the format
|
|
|
|
code <literal>%m</literal> can be used to insert the error message returned
|
|
|
|
by <function>strerror</function> for the current value of <literal>errno</literal>.
|
2003-05-19 23:38:24 +02:00
|
|
|
<footnote>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
That is, the value that was current when the <function>ereport</function> call
|
|
|
|
was reached; changes of <literal>errno</literal> within the auxiliary reporting
|
2003-05-19 23:38:24 +02:00
|
|
|
routines will not affect it. That would not be true if you were to
|
2017-10-09 03:44:17 +02:00
|
|
|
write <literal>strerror(errno)</literal> explicitly in <function>errmsg</function>'s
|
2003-05-19 23:38:24 +02:00
|
|
|
parameter list; accordingly, do not do so.
|
|
|
|
</para>
|
|
|
|
</footnote>
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>%m</literal> does not require any
|
|
|
|
corresponding entry in the parameter list for <function>errmsg</function>.
|
|
|
|
Note that the message string will be run through <function>gettext</function>
|
2003-05-19 23:38:24 +02:00
|
|
|
for possible localization before format codes are processed.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-12-13 19:05:10 +01:00
|
|
|
<function>errmsg_internal(const char *msg, ...)</function> is the same as
|
2017-10-09 03:44:17 +02:00
|
|
|
<function>errmsg</function>, except that the message string will not be
|
2008-10-27 20:37:22 +01:00
|
|
|
translated nor included in the internationalization message dictionary.
|
2017-10-09 03:44:17 +02:00
|
|
|
This should be used for <quote>cannot happen</quote> cases that are probably
|
2003-05-19 23:38:24 +02:00
|
|
|
not worth expending translation effort on.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2009-06-04 20:33:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errmsg_plural(const char *fmt_singular, const char *fmt_plural,
|
2017-10-09 03:44:17 +02:00
|
|
|
unsigned long n, ...)</function> is like <function>errmsg</function>, but with
|
2009-06-04 20:33:08 +02:00
|
|
|
support for various plural forms of the message.
|
2017-10-09 03:44:17 +02:00
|
|
|
<replaceable>fmt_singular</replaceable> is the English singular format,
|
|
|
|
<replaceable>fmt_plural</replaceable> is the English plural format,
|
|
|
|
<replaceable>n</replaceable> is the integer value that determines which plural
|
2009-06-04 20:33:08 +02:00
|
|
|
form is needed, and the remaining arguments are formatted according
|
|
|
|
to the selected format string. For more information see
|
2017-11-23 15:39:47 +01:00
|
|
|
<xref linkend="nls-guidelines"/>.
|
2009-06-04 20:33:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2003-05-19 23:38:24 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-12-13 19:05:10 +01:00
|
|
|
<function>errdetail(const char *msg, ...)</function> supplies an optional
|
2017-10-09 03:44:17 +02:00
|
|
|
<quote>detail</quote> message; this is to be used when there is additional
|
2003-05-19 23:38:24 +02:00
|
|
|
information that seems inappropriate to put in the primary message.
|
|
|
|
The message string is processed in just the same way as for
|
2017-10-09 03:44:17 +02:00
|
|
|
<function>errmsg</function>.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2008-03-24 19:08:47 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2011-07-16 19:41:48 +02:00
|
|
|
<function>errdetail_internal(const char *msg, ...)</function> is the same
|
2017-10-09 03:44:17 +02:00
|
|
|
as <function>errdetail</function>, except that the message string will not be
|
2011-07-16 19:41:48 +02:00
|
|
|
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.
|
2008-03-24 19:08:47 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2009-06-04 20:33:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errdetail_plural(const char *fmt_singular, const char *fmt_plural,
|
2017-10-09 03:44:17 +02:00
|
|
|
unsigned long n, ...)</function> is like <function>errdetail</function>, but with
|
2009-06-04 20:33:08 +02:00
|
|
|
support for various plural forms of the message.
|
2017-11-23 15:39:47 +01:00
|
|
|
For more information see <xref linkend="nls-guidelines"/>.
|
2009-06-04 20:33:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2011-07-16 19:41:48 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errdetail_log(const char *msg, ...)</function> is the same as
|
2017-10-09 03:44:17 +02:00
|
|
|
<function>errdetail</function> except that this string goes only to the server
|
|
|
|
log, never to the client. If both <function>errdetail</function> (or one of
|
2011-07-16 19:41:48 +02:00
|
|
|
its equivalents above) and
|
2017-10-09 03:44:17 +02:00
|
|
|
<function>errdetail_log</function> are used then one string goes to the client
|
2011-07-16 19:41:48 +02:00
|
|
|
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.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2014-03-12 19:26:47 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2015-09-05 10:35:49 +02:00
|
|
|
<function>errdetail_log_plural(const char *fmt_singular, const char
|
2014-03-12 19:26:47 +01:00
|
|
|
*fmt_plural, unsigned long n, ...)</function> is like
|
2017-10-09 03:44:17 +02:00
|
|
|
<function>errdetail_log</function>, but with support for various plural forms of
|
2014-03-12 19:26:47 +01:00
|
|
|
the message.
|
2017-11-23 15:39:47 +01:00
|
|
|
For more information see <xref linkend="nls-guidelines"/>.
|
2014-03-12 19:26:47 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2003-05-19 23:38:24 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-12-13 19:05:10 +01:00
|
|
|
<function>errhint(const char *msg, ...)</function> supplies an optional
|
2017-10-09 03:44:17 +02:00
|
|
|
<quote>hint</quote> message; this is to be used when offering suggestions
|
2003-05-19 23:38:24 +02:00
|
|
|
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
|
2017-10-09 03:44:17 +02:00
|
|
|
<function>errmsg</function>.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2021-03-31 09:15:51 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errhint_plural(const char *fmt_singular, const char *fmt_plural,
|
|
|
|
unsigned long n, ...)</function> is like <function>errhint</function>, but with
|
|
|
|
support for various plural forms of the message.
|
|
|
|
For more information see <xref linkend="nls-guidelines"/>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2003-05-19 23:38:24 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-12-13 19:05:10 +01:00
|
|
|
<function>errcontext(const char *msg, ...)</function> is not normally called
|
2017-10-09 03:44:17 +02:00
|
|
|
directly from an <function>ereport</function> message site; rather it is used
|
|
|
|
in <literal>error_context_stack</literal> callback functions to provide
|
2003-05-19 23:38:24 +02:00
|
|
|
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
|
2017-10-09 03:44:17 +02:00
|
|
|
<function>errmsg</function>. Unlike the other auxiliary functions, this can
|
|
|
|
be called more than once per <function>ereport</function> call; the successive
|
2003-05-19 23:38:24 +02:00
|
|
|
strings thus supplied are concatenated with separating newlines.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-12-13 19:05:10 +01:00
|
|
|
<function>errposition(int cursorpos)</function> specifies the textual location
|
2003-05-19 23:38:24 +02:00
|
|
|
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>
|
Provide database object names as separate fields in error messages.
This patch addresses the problem that applications currently have to
extract object names from possibly-localized textual error messages,
if they want to know for example which index caused a UNIQUE_VIOLATION
failure. It adds new error message fields to the wire protocol, which
can carry the name of a table, table column, data type, or constraint
associated with the error. (Since the protocol spec has always instructed
clients to ignore unrecognized field types, this should not create any
compatibility problem.)
Support for providing these new fields has been added to just a limited set
of error reports (mainly, those in the "integrity constraint violation"
SQLSTATE class), but we will doubtless add them to more calls in future.
Pavel Stehule, reviewed and extensively revised by Peter Geoghegan, with
additional hacking by Tom Lane.
2013-01-29 23:06:26 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errtable(Relation rel)</function> specifies a relation whose
|
|
|
|
name and schema name should be included as auxiliary fields in the error
|
|
|
|
report.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errtablecol(Relation rel, int attnum)</function> specifies
|
|
|
|
a column whose name, table name, and schema name should be included as
|
|
|
|
auxiliary fields in the error report.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errtableconstraint(Relation rel, const char *conname)</function>
|
|
|
|
specifies a table constraint whose name, table name, and schema name
|
|
|
|
should be included as auxiliary fields in the error report. Indexes
|
|
|
|
should be considered to be constraints for this purpose, whether or
|
2017-10-09 03:44:17 +02:00
|
|
|
not they have an associated <structname>pg_constraint</structname> entry. Be
|
Provide database object names as separate fields in error messages.
This patch addresses the problem that applications currently have to
extract object names from possibly-localized textual error messages,
if they want to know for example which index caused a UNIQUE_VIOLATION
failure. It adds new error message fields to the wire protocol, which
can carry the name of a table, table column, data type, or constraint
associated with the error. (Since the protocol spec has always instructed
clients to ignore unrecognized field types, this should not create any
compatibility problem.)
Support for providing these new fields has been added to just a limited set
of error reports (mainly, those in the "integrity constraint violation"
SQLSTATE class), but we will doubtless add them to more calls in future.
Pavel Stehule, reviewed and extensively revised by Peter Geoghegan, with
additional hacking by Tom Lane.
2013-01-29 23:06:26 +01:00
|
|
|
careful to pass the underlying heap relation, not the index itself, as
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>rel</literal>.
|
Provide database object names as separate fields in error messages.
This patch addresses the problem that applications currently have to
extract object names from possibly-localized textual error messages,
if they want to know for example which index caused a UNIQUE_VIOLATION
failure. It adds new error message fields to the wire protocol, which
can carry the name of a table, table column, data type, or constraint
associated with the error. (Since the protocol spec has always instructed
clients to ignore unrecognized field types, this should not create any
compatibility problem.)
Support for providing these new fields has been added to just a limited set
of error reports (mainly, those in the "integrity constraint violation"
SQLSTATE class), but we will doubtless add them to more calls in future.
Pavel Stehule, reviewed and extensively revised by Peter Geoghegan, with
additional hacking by Tom Lane.
2013-01-29 23:06:26 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errdatatype(Oid datatypeOid)</function> specifies a data
|
|
|
|
type whose name and schema name should be included as auxiliary fields
|
|
|
|
in the error report.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errdomainconstraint(Oid datatypeOid, const char *conname)</function>
|
|
|
|
specifies a domain constraint whose name, domain name, and schema name
|
|
|
|
should be included as auxiliary fields in the error report.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2003-07-19 01:20:33 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<function>errcode_for_file_access()</function> is a convenience function that
|
2003-07-19 01:20:33 +02:00
|
|
|
selects an appropriate SQLSTATE error identifier for a failure in a
|
|
|
|
file-access-related system call. It uses the saved
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>errno</literal> to determine which error code to generate.
|
|
|
|
Usually this should be used in combination with <literal>%m</literal> in the
|
2003-07-19 01:20:33 +02:00
|
|
|
primary error message text.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2003-07-22 21:00:12 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<function>errcode_for_socket_access()</function> is a convenience function that
|
2003-07-22 21:00:12 +02:00
|
|
|
selects an appropriate SQLSTATE error identifier for a failure in a
|
|
|
|
socket-related system call.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2007-03-03 00:37:23 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errhidestmt(bool hide_stmt)</function> can be called to specify
|
2017-10-09 03:44:17 +02:00
|
|
|
suppression of the <literal>STATEMENT:</literal> portion of a message in the
|
2007-03-03 00:37:23 +01:00
|
|
|
postmaster log. Generally this is appropriate if the message text
|
|
|
|
includes the current statement already.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2016-03-28 20:18:00 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<function>errhidecontext(bool hide_ctx)</function> can be called to
|
2017-10-09 03:44:17 +02:00
|
|
|
specify suppression of the <literal>CONTEXT:</literal> portion of a message in
|
2016-03-28 20:18:00 +02:00
|
|
|
the postmaster log. This should only be used for verbose debugging
|
|
|
|
messages where the repeated inclusion of context would bloat the log
|
2020-09-10 08:50:19 +02:00
|
|
|
too much.
|
2016-03-28 20:18:00 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2003-05-19 23:38:24 +02:00
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
Provide database object names as separate fields in error messages.
This patch addresses the problem that applications currently have to
extract object names from possibly-localized textual error messages,
if they want to know for example which index caused a UNIQUE_VIOLATION
failure. It adds new error message fields to the wire protocol, which
can carry the name of a table, table column, data type, or constraint
associated with the error. (Since the protocol spec has always instructed
clients to ignore unrecognized field types, this should not create any
compatibility problem.)
Support for providing these new fields has been added to just a limited set
of error reports (mainly, those in the "integrity constraint violation"
SQLSTATE class), but we will doubtless add them to more calls in future.
Pavel Stehule, reviewed and extensively revised by Peter Geoghegan, with
additional hacking by Tom Lane.
2013-01-29 23:06:26 +01:00
|
|
|
<note>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
At most one of the functions <function>errtable</function>,
|
|
|
|
<function>errtablecol</function>, <function>errtableconstraint</function>,
|
|
|
|
<function>errdatatype</function>, or <function>errdomainconstraint</function> should
|
|
|
|
be used in an <function>ereport</function> call. These functions exist to
|
Provide database object names as separate fields in error messages.
This patch addresses the problem that applications currently have to
extract object names from possibly-localized textual error messages,
if they want to know for example which index caused a UNIQUE_VIOLATION
failure. It adds new error message fields to the wire protocol, which
can carry the name of a table, table column, data type, or constraint
associated with the error. (Since the protocol spec has always instructed
clients to ignore unrecognized field types, this should not create any
compatibility problem.)
Support for providing these new fields has been added to just a limited set
of error reports (mainly, those in the "integrity constraint violation"
SQLSTATE class), but we will doubtless add them to more calls in future.
Pavel Stehule, reviewed and extensively revised by Peter Geoghegan, with
additional hacking by Tom Lane.
2013-01-29 23:06:26 +01:00
|
|
|
allow applications to extract the name of a database object associated
|
|
|
|
with the error condition without having to examine the
|
|
|
|
potentially-localized error message text.
|
|
|
|
These functions should be used in error reports for which it's likely
|
|
|
|
that applications would wish to have automatic error handling. As of
|
2017-10-09 03:44:17 +02:00
|
|
|
<productname>PostgreSQL</productname> 9.3, complete coverage exists only for
|
Provide database object names as separate fields in error messages.
This patch addresses the problem that applications currently have to
extract object names from possibly-localized textual error messages,
if they want to know for example which index caused a UNIQUE_VIOLATION
failure. It adds new error message fields to the wire protocol, which
can carry the name of a table, table column, data type, or constraint
associated with the error. (Since the protocol spec has always instructed
clients to ignore unrecognized field types, this should not create any
compatibility problem.)
Support for providing these new fields has been added to just a limited set
of error reports (mainly, those in the "integrity constraint violation"
SQLSTATE class), but we will doubtless add them to more calls in future.
Pavel Stehule, reviewed and extensively revised by Peter Geoghegan, with
additional hacking by Tom Lane.
2013-01-29 23:06:26 +01:00
|
|
|
errors in SQLSTATE class 23 (integrity constraint violation), but this
|
|
|
|
is likely to be expanded in future.
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
2003-05-19 23:38:24 +02:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
There is an older function <function>elog</function> that is still heavily used.
|
|
|
|
An <function>elog</function> call:
|
2003-07-27 20:37:52 +02:00
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
elog(level, "format string", ...);
|
2003-07-27 20:37:52 +02:00
|
|
|
</programlisting>
|
2007-02-01 01:28:19 +01:00
|
|
|
is exactly equivalent to:
|
2003-07-27 20:37:52 +02:00
|
|
|
<programlisting>
|
Re-implement the ereport() macro using __VA_ARGS__.
Now that we require C99, we can depend on __VA_ARGS__ to work, and
revising ereport() to use it has several significant benefits:
* The extra parentheses around the auxiliary function calls are now
optional. Aside from being a bit less ugly, this removes a common
gotcha for new contributors, because in some cases the compiler errors
you got from forgetting them were unintelligible.
* The auxiliary function calls are now evaluated as a comma expression
list rather than as extra arguments to errfinish(). This means that
compilers can be expected to warn about no-op expressions in the list,
allowing detection of several other common mistakes such as forgetting
to add errmsg(...) when converting an elog() call to ereport().
* Unlike the situation with extra function arguments, comma expressions
are guaranteed to be evaluated left-to-right, so this removes platform
dependency in the order of the auxiliary function calls. While that
dependency hasn't caused us big problems in the past, this change does
allow dropping some rather shaky assumptions around errcontext() domain
handling.
There's no intention to make wholesale changes of existing ereport
calls, but as proof-of-concept this patch removes the extra parens
from a couple of calls in postgres.c.
While new code can be written either way, code intended to be
back-patched will need to use extra parens for awhile yet. It seems
worth back-patching this change into v12, so as to reduce the window
where we have to be careful about that by one year. Hence, this patch
is careful to preserve ABI compatibility; a followup HEAD-only patch
will make some additional simplifications.
Andres Freund and Tom Lane
Discussion: https://postgr.es/m/CA+fd4k6N8EjNvZpM8nme+y+05mz-SM8Z_BgkixzkA34R+ej0Kw@mail.gmail.com
2020-03-24 16:48:33 +01:00
|
|
|
ereport(level, errmsg_internal("format string", ...));
|
2003-07-27 20:37:52 +02:00
|
|
|
</programlisting>
|
2006-10-23 20:10:32 +02:00
|
|
|
Notice that the SQLSTATE error code is always defaulted, and the message
|
2008-10-27 20:37:22 +01:00
|
|
|
string is not subject to translation.
|
2017-10-09 03:44:17 +02:00
|
|
|
Therefore, <function>elog</function> should be used only for internal errors and
|
2003-07-27 20:37:52 +02:00
|
|
|
low-level debug logging. Any message that is likely to be of interest to
|
2017-10-09 03:44:17 +02:00
|
|
|
ordinary users should go through <function>ereport</function>. Nonetheless,
|
|
|
|
there are enough internal <quote>cannot happen</quote> error checks in the
|
|
|
|
system that <function>elog</function> is still widely used; it is preferred for
|
2003-07-27 20:37:52 +02:00
|
|
|
those messages for its notational simplicity.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Advice about writing good error messages can be found in
|
2017-11-23 15:39:47 +01:00
|
|
|
<xref linkend="error-style-guide"/>.
|
2003-05-19 23:38:24 +02:00
|
|
|
</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
|
2017-10-09 03:44:17 +02:00
|
|
|
<productname>PostgreSQL</productname>.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>What Goes Where</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<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>
|
2007-02-01 01:28:19 +01:00
|
|
|
For example, instead of:
|
2003-05-19 23:38:24 +02:00
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
|
|
|
|
(plus a long addendum that is basically a hint)
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
2007-02-01 01:28:19 +01:00
|
|
|
write:
|
2003-05-19 23:38:24 +02:00
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
Primary: could not create shared memory segment: %m
|
|
|
|
Detail: Failed syscall was shmget(key=%d, size=%u, 0%o).
|
|
|
|
Hint: the addendum
|
2003-05-19 23:38:24 +02:00
|
|
|
</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
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
enough for error messages. Detail and hint messages can be relegated to a
|
2003-05-19 23:38:24 +02:00
|
|
|
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
|
2016-07-31 03:34:28 +02:00
|
|
|
aren't expected to know the details.
|
2003-05-19 23:38:24 +02:00
|
|
|
</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
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
needs. In long messages, newline characters (\n) can be used to indicate
|
2003-05-19 23:38:24 +02:00
|
|
|
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>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Quotation Marks</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<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
|
|
|
|
aren't even familiar with, it won't scale to other kinds of quoted terms,
|
|
|
|
it doesn't translate to other languages, and it's pretty pointless, too.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Use of Quotes</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
2020-09-21 18:43:42 +02:00
|
|
|
Always use quotes to delimit file names, user-supplied identifiers, and
|
2003-05-19 23:38:24 +02:00
|
|
|
other variables that might contain words. Do not use them to mark up
|
|
|
|
variables that will not contain words (for example, operator names).
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There are functions in the backend that will double-quote their own output
|
2020-02-10 05:01:18 +01:00
|
|
|
as needed (for example, <function>format_type_be()</function>). Do not put
|
2009-06-04 20:33:08 +02:00
|
|
|
additional quotes around the output of such functions.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Rationale: Objects can have names that create ambiguity when embedded in a
|
|
|
|
message. Be consistent about denoting where a plugged-in name starts and
|
|
|
|
ends. But don't clutter messages with unnecessary or duplicate quote
|
2009-06-04 20:33:08 +02:00
|
|
|
marks.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Grammar and Punctuation</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
The rules are different for primary error messages and for detail/hint
|
|
|
|
messages:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Primary error messages: Do not capitalize the first letter. Do not end a
|
|
|
|
message with a period. Do not even think about ending a message with an
|
2009-06-04 20:33:08 +02:00
|
|
|
exclamation point.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Detail and hint messages: Use complete sentences, and end each with
|
2007-11-07 14:12:21 +01:00
|
|
|
a period. Capitalize the first word of sentences. Put two spaces after
|
|
|
|
the period if another sentence follows (for English text; might be
|
|
|
|
inappropriate in other languages).
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
2010-06-28 19:48:26 +02:00
|
|
|
<para>
|
|
|
|
Error context strings: Do not capitalize the first letter and do
|
|
|
|
not end the string with a period. Context strings should normally
|
|
|
|
not be complete sentences.
|
|
|
|
</para>
|
|
|
|
|
2003-05-19 23:38:24 +02:00
|
|
|
<para>
|
|
|
|
Rationale: Avoiding punctuation makes it easier for client applications to
|
|
|
|
embed the message into a variety of grammatical contexts. Often, primary
|
|
|
|
messages are not grammatically complete sentences anyway. (And if they're
|
|
|
|
long enough to be more than one sentence, they should be split into
|
|
|
|
primary and detail parts.) However, detail and hint messages are longer
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
and might need to include multiple sentences. For consistency, they should
|
2009-06-04 20:33:08 +02:00
|
|
|
follow complete-sentence style even when there's only one sentence.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Upper Case vs. Lower Case</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Use lower case for message wording, including the first letter of a
|
|
|
|
primary error message. Use upper case for SQL commands and key words if
|
2004-02-17 03:53:03 +01:00
|
|
|
they appear in the message.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Rationale: It's easier to make everything look more consistent this
|
|
|
|
way, since some messages are complete sentences and some not.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Avoid Passive Voice</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Use the active voice. Use complete sentences when there is an acting
|
|
|
|
subject (<quote>A could not do B</quote>). Use telegram style without
|
|
|
|
subject if the subject would be the program itself; do not use
|
|
|
|
<quote>I</quote> for the program.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Rationale: The program is not human. Don't pretend otherwise.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Present vs. Past Tense</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Use past tense if an attempt to do something failed, but could perhaps
|
|
|
|
succeed next time (perhaps after fixing some problem). Use present tense
|
2009-06-04 20:33:08 +02:00
|
|
|
if the failure is certainly permanent.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2007-02-01 01:28:19 +01:00
|
|
|
There is a nontrivial semantic difference between sentences of the form:
|
2003-05-19 23:38:24 +02:00
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
could not open file "%s": %m
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
2007-02-01 01:28:19 +01:00
|
|
|
and:
|
2003-05-19 23:38:24 +02:00
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
cannot open file "%s"
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
|
|
|
The first one means that the attempt to open the file failed. The
|
|
|
|
message should give a reason, such as <quote>disk full</quote> or
|
|
|
|
<quote>file doesn't exist</quote>. The past tense is appropriate because
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
next time the disk might not be full anymore or the file in question might
|
2009-06-04 20:33:08 +02:00
|
|
|
exist.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2007-02-01 21:28:08 +01:00
|
|
|
The second form indicates that the functionality of opening the named file
|
2003-05-19 23:38:24 +02:00
|
|
|
does not exist at all in the program, or that it's conceptually
|
|
|
|
impossible. The present tense is appropriate because the condition will
|
2009-06-04 20:33:08 +02:00
|
|
|
persist indefinitely.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Rationale: Granted, the average user will not be able to draw great
|
|
|
|
conclusions merely from the tense of the message, but since the language
|
2009-06-04 20:33:08 +02:00
|
|
|
provides us with a grammar we should use it correctly.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Type of the Object</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
When citing the name of an object, state what kind of object it is.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
Rationale: Otherwise no one will know what <quote>foo.bar.baz</quote>
|
2004-02-17 03:53:03 +01:00
|
|
|
refers to.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
|
|
|
<title>Brackets</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Square brackets are only to be used (1) in command synopses to denote
|
|
|
|
optional arguments, or (2) to denote an array subscript.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Rationale: Anything else does not correspond to widely-known customary
|
|
|
|
usage and will confuse people.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Assembling Error Messages</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
When a message includes text that is generated elsewhere, embed it in
|
|
|
|
this style:
|
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
could not open file %s: %m
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Rationale: It would be difficult to account for all possible error codes
|
|
|
|
to paste this into a single smooth sentence, so some sort of punctuation
|
|
|
|
is needed. Putting the embedded text in parentheses has also been
|
|
|
|
suggested, but it's unnatural if the embedded text is likely to be the
|
2009-06-04 20:33:08 +02:00
|
|
|
most important part of the message, as is often the case.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Reasons for Errors</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Messages should always state the reason why an error occurred.
|
|
|
|
For example:
|
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
BAD: could not open file %s
|
|
|
|
BETTER: could not open file %s (I/O failure)
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
|
|
|
If no reason is known you better fix the code.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Function Names</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Don't include the name of the reporting routine in the error text. We have
|
|
|
|
other mechanisms for finding that out when needed, and for most users it's
|
|
|
|
not helpful information. If the error text doesn't make as much sense
|
2009-06-04 20:33:08 +02:00
|
|
|
without the function name, reword it.
|
2003-05-19 23:38:24 +02:00
|
|
|
<programlisting>
|
2018-07-22 23:58:01 +02:00
|
|
|
BAD: pg_strtoint32: error in "z": cannot parse "z"
|
2018-07-23 02:27:05 +02:00
|
|
|
BETTER: invalid input syntax for type integer: "z"
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Avoid mentioning called function names, either; instead say what the code
|
|
|
|
was trying to do:
|
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
BAD: open() failed: %m
|
|
|
|
BETTER: could not open file %s: %m
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
|
|
|
If it really seems necessary, mention the system call in the detail
|
|
|
|
message. (In some cases, providing the actual values passed to the
|
|
|
|
system call might be appropriate information for the detail message.)
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Rationale: Users don't know what all those functions do.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Tricky Words to Avoid</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Unable</title>
|
|
|
|
<para>
|
|
|
|
<quote>Unable</quote> is nearly the passive voice. Better use
|
|
|
|
<quote>cannot</quote> or <quote>could not</quote>, as appropriate.
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Bad</title>
|
|
|
|
<para>
|
|
|
|
Error messages like <quote>bad result</quote> are really hard to interpret
|
|
|
|
intelligently. It's better to write why the result is <quote>bad</quote>,
|
2009-06-04 20:33:08 +02:00
|
|
|
e.g., <quote>invalid format</quote>.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Illegal</title>
|
|
|
|
<para>
|
|
|
|
<quote>Illegal</quote> stands for a violation of the law, the rest is
|
|
|
|
<quote>invalid</quote>. Better yet, say why it's invalid.
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Unknown</title>
|
|
|
|
<para>
|
|
|
|
Try to avoid <quote>unknown</quote>. Consider <quote>error: unknown
|
|
|
|
response</quote>. If you don't know what the response is, how do you know
|
|
|
|
it's erroneous? <quote>Unrecognized</quote> is often a better choice.
|
2009-06-04 20:33:08 +02:00
|
|
|
Also, be sure to include the value being complained of.
|
2003-05-19 23:38:24 +02:00
|
|
|
<programlisting>
|
2004-12-13 19:05:10 +01:00
|
|
|
BAD: unknown node type
|
|
|
|
BETTER: unrecognized node type: 42
|
2003-05-19 23:38:24 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Find vs. Exists</title>
|
|
|
|
<para>
|
|
|
|
If the program uses a nontrivial algorithm to locate a resource (e.g., a
|
|
|
|
path search) and that algorithm fails, it is fair to say that the program
|
|
|
|
couldn't <quote>find</quote> the resource. If, on the other hand, the
|
|
|
|
expected location of the resource is known but the program cannot access
|
|
|
|
it there then say that the resource doesn't <quote>exist</quote>. Using
|
2009-06-04 20:33:08 +02:00
|
|
|
<quote>find</quote> in this case sounds weak and confuses the issue.
|
2003-05-19 23:38:24 +02:00
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
2007-02-01 22:28:34 +01:00
|
|
|
<formalpara>
|
2007-02-01 23:06:14 +01:00
|
|
|
<title>May vs. Can vs. Might</title>
|
2007-02-01 22:28:34 +01:00
|
|
|
<para>
|
2009-04-27 18:27:36 +02:00
|
|
|
<quote>May</quote> suggests permission (e.g., "You may borrow my rake."),
|
2007-02-01 22:28:34 +01:00
|
|
|
and has little use in documentation or error messages.
|
2009-04-27 18:27:36 +02:00
|
|
|
<quote>Can</quote> suggests ability (e.g., "I can lift that log."),
|
|
|
|
and <quote>might</quote> suggests possibility (e.g., "It might rain
|
2007-02-01 23:06:14 +01:00
|
|
|
today."). Using the proper word clarifies meaning and assists
|
2007-02-01 22:28:34 +01:00
|
|
|
translation.
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Contractions</title>
|
|
|
|
<para>
|
|
|
|
Avoid contractions, like <quote>can't</quote>; use
|
|
|
|
<quote>cannot</quote> instead.
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
2021-07-27 18:20:16 +02:00
|
|
|
<formalpara>
|
|
|
|
<title>Non-negative</title>
|
|
|
|
<para>
|
|
|
|
Avoid <quote>non-negative</quote> as it is ambiguous
|
|
|
|
about whether it accepts zero. It's better to use
|
|
|
|
<quote>greater than zero</quote> or
|
|
|
|
<quote>greater than or equal to zero</quote>.
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
2003-05-19 23:38:24 +02:00
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Proper Spelling</title>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Spell out words in full. For instance, avoid:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
spec
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
stats
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
parens
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
auth
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
xact
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
2000-02-02 17:25:04 +01:00
|
|
|
</para>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Rationale: This will improve consistency.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
|
|
|
<title>Localization</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Keep in mind that error message texts need to be translated into other
|
2017-11-23 15:39:47 +01:00
|
|
|
languages. Follow the guidelines in <xref linkend="nls-guidelines"/>
|
2003-05-19 23:38:24 +02:00
|
|
|
to avoid making life difficult for translators.
|
|
|
|
</para>
|
|
|
|
</simplesect>
|
|
|
|
|
2000-02-02 17:25:04 +01:00
|
|
|
</sect1>
|
2003-05-19 23:38:24 +02:00
|
|
|
|
2015-09-11 21:33:17 +02:00
|
|
|
<sect1 id="source-conventions">
|
|
|
|
<title>Miscellaneous Coding Conventions</title>
|
|
|
|
|
|
|
|
<simplesect>
|
|
|
|
<title>C Standard</title>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
Code in <productname>PostgreSQL</productname> should only rely on language
|
2018-08-24 03:33:40 +02:00
|
|
|
features available in the C99 standard. That means a conforming
|
|
|
|
C99 compiler has to be able to compile postgres, at least aside
|
|
|
|
from a few platform dependent pieces.
|
|
|
|
</para>
|
|
|
|
<para>
|
2019-04-28 15:53:33 +02:00
|
|
|
A few features included in the C99 standard are, at this time, not
|
2018-08-24 03:33:40 +02:00
|
|
|
permitted to be used in core <productname>PostgreSQL</productname>
|
|
|
|
code. This currently includes variable length arrays, intermingled
|
|
|
|
declarations and code, <literal>//</literal> comments, universal
|
|
|
|
character names. Reasons for that include portability and historical
|
|
|
|
practices.
|
|
|
|
</para>
|
|
|
|
<para>
|
2020-02-10 05:01:18 +01:00
|
|
|
Features from later revisions of the C standard or compiler specific
|
2018-08-24 03:33:40 +02:00
|
|
|
features can be used, if a fallback is provided.
|
|
|
|
</para>
|
|
|
|
<para>
|
2019-08-13 06:53:41 +02:00
|
|
|
For example <literal>_Static_assert()</literal> and
|
2018-08-24 03:33:40 +02:00
|
|
|
<literal>__builtin_constant_p</literal> are currently used, even though
|
|
|
|
they are from newer revisions of the C standard and a
|
|
|
|
<productname>GCC</productname> extension respectively. If not available
|
|
|
|
we respectively fall back to using a C99 compatible replacement that
|
|
|
|
performs the same checks, but emits rather cryptic messages and do not
|
|
|
|
use <literal>__builtin_constant_p</literal>.
|
2015-09-11 21:33:17 +02:00
|
|
|
</para>
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
|
|
|
<title>Function-Like Macros and Inline Functions</title>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
Both, macros with arguments and <literal>static inline</literal>
|
2015-09-11 21:33:17 +02:00
|
|
|
functions, may be used. The latter are preferable if there are
|
2020-09-01 00:33:37 +02:00
|
|
|
multiple-evaluation hazards when written as a macro, as e.g., the
|
2015-09-11 21:33:17 +02:00
|
|
|
case with
|
|
|
|
<programlisting>
|
|
|
|
#define Max(x, y) ((x) > (y) ? (x) : (y))
|
|
|
|
</programlisting>
|
|
|
|
or when the macro would be very long. In other cases it's only
|
|
|
|
possible to use macros, or at least easier. For example because
|
|
|
|
expressions of various types need to be passed to the macro.
|
|
|
|
</para>
|
|
|
|
<para>
|
2016-10-30 23:30:46 +01:00
|
|
|
When the definition of an inline function references symbols
|
2020-09-01 00:33:37 +02:00
|
|
|
(i.e., variables, functions) that are only available as part of the
|
2015-09-11 21:33:17 +02:00
|
|
|
backend, the function may not be visible when included from frontend
|
|
|
|
code.
|
|
|
|
<programlisting>
|
|
|
|
#ifndef FRONTEND
|
|
|
|
static inline MemoryContext
|
|
|
|
MemoryContextSwitchTo(MemoryContext context)
|
|
|
|
{
|
|
|
|
MemoryContext old = CurrentMemoryContext;
|
|
|
|
|
|
|
|
CurrentMemoryContext = context;
|
|
|
|
return old;
|
|
|
|
}
|
|
|
|
#endif /* FRONTEND */
|
|
|
|
</programlisting>
|
2017-10-09 03:44:17 +02:00
|
|
|
In this example <literal>CurrentMemoryContext</literal>, which is only
|
2015-09-11 21:33:17 +02:00
|
|
|
available in the backend, is referenced and the function thus
|
|
|
|
hidden with a <literal>#ifndef FRONTEND</literal>. This rule
|
|
|
|
exists because some compilers emit references to symbols
|
|
|
|
contained in inline functions even if the function is not used.
|
|
|
|
</para>
|
|
|
|
</simplesect>
|
|
|
|
|
|
|
|
<simplesect>
|
|
|
|
<title>Writing Signal Handlers</title>
|
|
|
|
<para>
|
|
|
|
To be suitable to run inside a signal handler code has to be
|
|
|
|
written very carefully. The fundamental problem is that, unless
|
|
|
|
blocked, a signal handler can interrupt code at any time. If code
|
|
|
|
inside the signal handler uses the same state as code outside
|
|
|
|
chaos may ensue. As an example consider what happens if a signal
|
|
|
|
handler tries to acquire a lock that's already held in the
|
|
|
|
interrupted code.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Barring special arrangements code in signal handlers may only
|
2016-07-29 04:46:15 +02:00
|
|
|
call async-signal safe functions (as defined in POSIX) and access
|
2015-09-11 21:33:17 +02:00
|
|
|
variables of type <literal>volatile sig_atomic_t</literal>. A few
|
2016-07-29 04:46:15 +02:00
|
|
|
functions in <command>postgres</command> are also deemed signal safe, importantly
|
|
|
|
<function>SetLatch()</function>.
|
2015-09-11 21:33:17 +02:00
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
In most cases signal handlers should do nothing more than note
|
|
|
|
that a signal has arrived, and wake up code running outside of
|
|
|
|
the handler using a latch. An example of such a handler is the
|
|
|
|
following:
|
|
|
|
<programlisting>
|
|
|
|
static void
|
|
|
|
handle_sighup(SIGNAL_ARGS)
|
|
|
|
{
|
|
|
|
int save_errno = errno;
|
|
|
|
|
|
|
|
got_SIGHUP = true;
|
|
|
|
SetLatch(MyLatch);
|
|
|
|
|
|
|
|
errno = save_errno;
|
|
|
|
}
|
|
|
|
</programlisting>
|
2017-10-09 03:44:17 +02:00
|
|
|
<varname>errno</varname> is saved and restored because
|
|
|
|
<function>SetLatch()</function> might change it. If that were not done
|
2016-07-29 04:46:15 +02:00
|
|
|
interrupted code that's currently inspecting <varname>errno</varname> might see the wrong
|
2015-09-11 21:33:17 +02:00
|
|
|
value.
|
|
|
|
</para>
|
|
|
|
</simplesect>
|
|
|
|
|
2017-09-11 20:47:15 +02:00
|
|
|
<simplesect>
|
|
|
|
<title>Calling Function Pointers</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For clarity, it is preferred to explicitly dereference a function pointer
|
|
|
|
when calling the pointed-to function if the pointer is a simple variable,
|
|
|
|
for example:
|
|
|
|
<programlisting>
|
|
|
|
(*emit_log_hook) (edata);
|
|
|
|
</programlisting>
|
|
|
|
(even though <literal>emit_log_hook(edata)</literal> would also work).
|
|
|
|
When the function pointer is part of a structure, then the extra
|
|
|
|
punctuation can and usually should be omitted, for example:
|
|
|
|
<programlisting>
|
|
|
|
paramInfo->paramFetch(paramInfo, paramId);
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</simplesect>
|
2015-09-11 21:33:17 +02:00
|
|
|
</sect1>
|
2000-02-02 17:25:04 +01:00
|
|
|
</chapter>
|