New programmer's information from Massimo Dal Zotto.

diff --git a/doc/src/sgml/pg_options.sgml b/doc/src/sgml/pg_options.sgml
new file mode 100644 (file)
index 0000000..b8205f7
--- /dev/null
+++ b/doc/src/sgml/pg_options.sgml
@@ -0,0 +1,543 @@
+<Chapter Id="pg-options">
+<DocInfo>
+<AuthorGroup>
+<Author>
+<FirstName>Massimo</FirstName>
+<Surname>Dal Zotto</Surname>
+</Author>
+</AuthorGroup>
+<Date>Transcribed 1998-10-16</Date>
+</DocInfo>
+
+<Title>Using pg_options</Title>
+
+<Para>
+<Note>
+<Para>
+Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
+</Para>
+</Note>
+
+<Para>
+The optional file <filename>data/pg_options</filename> contains runtime
+options used by the backend to control trace messages and other backend
+tunable parameters.
+What makes this file interesting is the fact that it is re-read by a backend
+when it receives a SIGHUP signal, making thus possible to change run-time
+options on the fly without needing to restart 
+<productname>Postgres</productname>.
+The options specified in this file may be debugging flags used by the trace
+package (<filename>backend/utils/misc/trace.c</filename>) or numeric
+parameters which can be used by the backend to control its behaviour.
+New options and parameters must be defined in
+<filename>backend/utils/misc/trace.c</filename> and
+<filename>backend/include/utils/trace.h</filename>.
+
+<Para>
+For example suppose we want to add conditional trace messages and a tunable
+numeric parameter to the code in file <filename>foo.c</filename>.
+All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into
+<filename>backend/include/utils/trace.h</filename>:
+
+<programlisting>
+/* file trace.h */
+enum pg_option_enum {
+    ...
+    TRACE_FOO,                 /* trace foo functions */
+    OPT_FOO_PARAM,             /* foo tunable parameter */
+
+    NUM_PG_OPTIONS              /* must be the last item of enum */
+};
+</programlisting>
+
+and a corresponding line in <filename>backend/utils/misc/trace.c</filename>:
+
+<programlisting>
+/* file trace.c */
+static char *opt_names[] = {
+    ...
+    "foo",                     /* trace foo functions */
+    "fooparam"                         /* foo tunable parameter */
+};
+</programlisting>
+
+Options in the two files must be specified in exactly the same order.
+In the foo source files we can now reference the new flags with:
+
+<programlisting>
+/* file foo.c */
+#include "trace.h"
+#define foo_param pg_options[OPT_FOO_PARAM]
+
+int
+foo_function(int x, int y)
+{
+    TPRINTF(TRACE_FOO, "entering foo_function, foo_param=%d", foo_param);
+    if (foo_param > 10) {
+        do_more_foo(x, y);
+    }
+}
+</programlisting>
+
+<para>
+Existing files using private trace flags can be changed by simply adding
+the following code:
+
+<programlisting>
+#include "trace.h"
+/* int my_own_flag = 0; -- removed */
+#define my_own_flag pg_options[OPT_MY_OWN_FLAG]
+</programlisting>
+
+<para>
+All pg_options are initialized to zero at backend startup. If we need a
+different default value we must add some initialization code at the beginning
+of <function>PostgresMain</function>.
+
+Now we can set the foo_param and enable foo trace by writing values into the
+<filename>data/pg_options</filename> file:
+
+<programlisting>
+# file pg_options
+...
+foo=1
+fooparam=17
+</programlisting>
+
+<para>
+The new options will be read by all new backends when they are started.
+To make effective the changes for all running backends we need to send a
+SIGHUP to the postmaster. The signal will be automatically sent to all the
+backends. We can also activate the changes only for a specific backend by
+sending the SIGHUP directly to it.
+
+<para>
+pg_options can also be specified with the <option>-T</option> switch of 
+<productname>Postgres</productname>:
+
+<programlisting>
+postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
+</programlisting>
+
+<Para>
+The functions used for printing errors and debug messages can now make use
+of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
+or stderr are prefixed by a timestamp containing also the backend pid:
+
+<programlisting>
+#timestamp          #pid    #message
+980127.17:52:14.173 [29271] StartTransactionCommand
+980127.17:52:14.174 [29271] ProcessUtility: drop table t;
+980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full
+980127.17:52:14.186 [29286] Async_NotifyHandler
+980127.17:52:14.186 [29286] Waking up sleeping backend process
+980127.19:52:14.292 [29286] Async_NotifyFrontEnd
+980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
+980127.19:52:14.466 [29286] Async_NotifyHandler done
+</programlisting>
+
+<para>
+This format improves readability of the logs and allows people to understand
+exactly which backend is doing what and at which time. It also makes
+easier to write simple awk or perl scripts which monitor the log to
+detect database errors or problem, or to compute transaction time statistics.
+
+<para>
+Messages printed to syslog use the log facility LOG_LOCAL0.
+The use of syslog can be controlled with the syslog pg_option.
+Unfortunately many functions call directly <function>printf()</function>
+to print their messages to stdout or stderr and this output can't be
+redirected to syslog or have timestamps in it. 
+It would be advisable that all calls to printf would be replaced with the
+PRINTF macro and output to stderr be changed to use EPRINTF instead so that
+we can control all output in a uniform way.
+</Para>
+
+<Para>
+The new pg_options mechanism is more convenient than defining new backend
+option switches because:
+
+<ItemizedList Mark="bullet" Spacing="compact">
+<ListItem>
+<Para>
+we don't have to define a different switch for each thing we want to control.
+All options are defined as keywords in an external file stored in the data
+directory.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+we don't have to restart <productname>Postgres</productname> to change
+ the setting of some option.
+Normally backend options are specified to the postmaster and passed to each
+backend when it is started. Now they are read from a file.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+we can change options on the fly while a backend is running. We can thus
+investigate some problem by activating debug messages only when the problem
+appears. We can also try different values for tunable parameters.
+</Para>
+</ListItem>
+</ItemizedList>
+
+The format of the <filename>pg_options</filename> file is as follows:
+
+<programlisting>
+# <replaceable>comment</replaceable>
+<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable>  # set value for <replaceable>option</replaceable>
+<replaceable>option</replaceable>                # set <replaceable>option</replaceable> = 1
+<replaceable>option</replaceable>+               # set <replaceable>option</replaceable> = 1
+<replaceable>option</replaceable>-               # set <replaceable>option</replaceable> = 0
+</programlisting>
+
+Note that <replaceable class="parameter">keyword</replaceable> can also be
+an abbreviation of the option name defined in
+<filename>backend/utils/misc/trace.c</filename>.
+</Para>
+
+<Para>
+The options currently defined in
+<filename>backend/utils/misc/trace.c</filename> are the following:
+
+<variablelist>
+<varlistentry>
+<term>
+all
+
+<listitem>
+<para>
+Global trace flag. Allowed values are:
+
+<variablelist>
+<varlistentry>
+<term>
+0
+
+<listitem>
+<para>
+Trace messages enabled individually
+
+<varlistentry>
+<term>
+1
+
+<listitem>
+<para>
+Enable all trace messages
+
+<varlistentry>
+<term>
+-1
+
+<listitem>
+<para>
+Disable all trace messages
+
+</variablelist>
+
+<varlistentry>
+<term>
+verbose
+
+<listitem>
+<para>
+Verbosity flag. Allowed values are:
+
+<variablelist>
+<varlistentry>
+<term>
+0
+
+<listitem>
+<para>
+No messages. This is the default.
+
+<varlistentry>
+<term>
+1
+
+<listitem>
+<para>
+Print information messages.
+
+<varlistentry>
+<term>
+2
+
+<listitem>
+<para>
+Print more information messages.
+
+</variablelist>
+
+<varlistentry>
+<term>
+query
+
+<listitem>
+<para>
+Query trace flag. Allowed values are:
+
+<variablelist>
+<varlistentry>
+<term>
+0
+
+<listitem>
+<para>
+Don't print query.
+
+<varlistentry>
+<term>
+1
+
+<listitem>
+<para>
+Print a condensed query in one line.
+
+<varlistentry>
+<term>
+4
+
+<listitem>
+<para>
+Print the full query.
+
+</variablelist>
+
+<varlistentry>
+<term>
+plan
+
+<listitem>
+<para>
+Print query plan.
+
+<varlistentry>
+<term>
+parse
+
+<listitem>
+<para>
+Print parser output.
+
+<varlistentry>
+<term>
+rewritten
+
+<listitem>
+<para>
+Print rewritten query.
+
+<varlistentry>
+<term>
+parserstats
+
+<listitem>
+<para>
+Print parser statistics.
+
+<varlistentry>
+<term>
+plannerstats
+
+<listitem>
+<para>
+Print planner statistics.
+
+<varlistentry>
+<term>
+executorstats
+
+<listitem>
+<para>
+Print executor statistics.
+
+
+<varlistentry>
+<term>
+shortlocks
+
+<listitem>
+<para>
+Currently unused but needed to enable features in the future.
+
+<varlistentry>
+<term>
+locks
+
+<listitem>
+<para>
+Trace locks.
+
+<varlistentry>
+<term>
+userlocks
+
+<listitem>
+<para>
+Trace user locks.
+
+<varlistentry>
+<term>
+spinlocks
+
+<listitem>
+<para>
+Trace spin locks.
+
+<varlistentry>
+<term>
+notify
+
+<listitem>
+<para>
+Trace notify functions.
+
+
+<varlistentry>
+<term>
+malloc
+
+<listitem>
+<para>
+Currently unused.
+
+<varlistentry>
+<term>
+palloc
+
+<listitem>
+<para>
+Currently unused.
+
+<varlistentry>
+<term>
+lock_debug_oidmin
+
+<listitem>
+<para>
+Minimum relation oid traced by locks.
+
+<varlistentry>
+<term>
+lock_debug_relid
+
+<listitem>
+<para>
+oid, if not zero, of relation traced by locks.
+
+<varlistentry>
+<term>
+lock_read_priority
+
+<listitem>
+<para>
+Currently unused.
+
+
+<varlistentry>
+<term>
+deadlock_timeout
+
+<listitem>
+<para>
+Deadlock check timer.
+
+<varlistentry>
+<term>
+syslog
+
+<listitem>
+<para>
+syslog flag. Allowed values are:
+
+<variablelist>
+<varlistentry>
+<term>
+0
+
+<listitem>
+<para>
+Messages to stdout/stderr.
+
+<varlistentry>
+<term>
+1
+
+<listitem>
+<para>
+Messages to stdout/stderr and syslog.
+
+<varlistentry>
+<term>
+2
+
+<listitem>
+<para>
+Messages only to syslog.
+
+</variablelist>
+
+<varlistentry>
+<term>
+hostlookup
+
+<listitem>
+<para>
+Enable hostname lookup in ps_status.
+
+<varlistentry>
+<term>
+showportnumber
+
+<listitem>
+<para>
+Show port number in ps_status.
+
+<varlistentry>
+<term>
+notifyunlock
+
+<listitem>
+<para>
+Unlock of pg_listener after notify.
+
+<varlistentry>
+<term>
+notifyhack
+
+<listitem>
+<para>
+Remove duplicate tuples from pg_listener.
+
+</variablelist>
+
+For example my pg_options file contains the following values:
+
+<programlisting>
+verbose=2
+query
+hostlookup
+showportnumber
+</programlisting>
+
+</Para>
+
+
+<Para>
+Some of the existing code using private variables and option switches has
+been changed to make use of the pg_options feature, mainly in
+<filename>postgres.c</filename>. It would be advisable to modify
+all existing code
+in this way, so that we can get rid of many of the switches on
+the <productname>Postgres</productname> command line 
+and can have more tunable options 
+with a unique place to put option values.
+</Para>
+
+</Chapter>

diff --git a/doc/src/sgml/signals.sgml b/doc/src/sgml/signals.sgml
new file mode 100644 (file)
index 0000000..c5e7a93
--- /dev/null
+++ b/doc/src/sgml/signals.sgml
@@ -0,0 +1,190 @@
+<chapter id="signals">
+<DocInfo>
+<AuthorGroup>
+<Author>
+<FirstName>Massimo</FirstName>
+<Surname>Dal Zotto</Surname>
+</Author>
+</AuthorGroup>
+<Date>Transcribed 1998-10-16</Date>
+</DocInfo>
+
+<title><productname>Postgres</productname> Signals</title>
+
+<Para>
+<Note>
+<Para>
+Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
+</Para>
+</Note>
+
+<para>
+<productname>Postgres</productname> uses the following signals for
+ communication between the postmaster and backends:
+
+<para>
+<table tocentry="1">
+<title><productname>Postgres</productname> Signals</title>
+<titleabbrev>Signals</titleabbrev>
+
+<tgroup cols="2">
+<thead>
+<row>
+<entry>
+Signal
+<entry>
+<application>postmaster</application> Action
+<entry>
+Server Action
+
+<tbody>
+<row>
+<entry>
+SIGHUP
+<entry>
+kill(*,sighup)
+<entry>
+read_pg_options
+
+<row>
+<entry>
+SIGINT
+<entry>
+die
+<entry>
+cancel query
+
+<row>
+<entry>
+SIGQUIT
+<entry>
+kill(*,sigterm)
+<entry>
+handle_warn
+
+<row>
+<entry>
+SIGTERM
+<entry>
+kill(*,sigterm), kill(*,9), die
+<entry>
+die
+
+<row>
+<entry>
+SIGPIPE
+<entry>
+ignored
+<entry>
+die
+
+<row>
+<entry>
+SIGUSR1
+<entry>
+kill(*,sigusr1), die
+<entry>
+quickdie
+
+<row>
+<entry>
+SIGUSR2
+<entry>
+kill(*,sigusr2)
+<entry>
+async notify (SI flush)
+
+<row>
+<entry>
+SIGCHLD
+<entry>
+reaper
+<entry>
+ignored (alive test)
+
+<row>
+<entry>
+SIGTTIN
+<entry>
+ignored
+<entry>
+
+<row>
+<entry>
+SIGTTOU
+<entry>
+ignored
+<entry>
+
+<row>
+<entry>
+SIGCONT
+<entry>
+dumpstatus
+<entry>
+
+<row>
+<entry>
+SIGFPE
+<entry>
+<entry>
+FloatExceptionHandler
+
+</tbody>
+</tgroup>
+</table>
+
+<note>
+<para>
+<quote>kill(*,signal)</quote> means sending a signal to all backends.
+</note>
+
+<para>
+The main changes to the old signal handling are the use of SIGQUIT instead
+of SIGHUP to handle warns, SIGHUP to re-read the pg_options file and the
+redirection to all active backends of SIGHUP, SIGTERM, SIGUSR1 and SIGUSR2
+sent to the postmaster.
+In this way these signals sent to the postmaster can be sent
+automatically to all the backends without need to know their pids.
+To shut down postgres one needs only to send a SIGTERM to postmaster
+and it will stop automatically all the backends.
+
+<para>
+The SIGUSR2 signal is also used to prevent SI cache table overflow
+which happens when some backend doesn't process SI cache for a long period.
+When a backend detects the SI table full at 70% it simply sends a signal
+to the postmaster which will wake up all idle backends and make them flush
+the cache.
+
+<para>
+The typical use of signals by programmers could be the following:
+
+<programlisting>
+# stop postgres
+kill -TERM $postmaster_pid
+</programlisting>
+
+<programlisting>
+# kill all the backends
+kill -QUIT $postmaster_pid
+</programlisting>
+
+<programlisting>
+# kill only the postmaster
+kill -INT $postmaster_pid
+</programlisting>
+
+<programlisting>
+# change pg_options
+cat new_pg_options > $DATA_DIR/pg_options
+kill -HUP $postmaster_pid
+</programlisting>
+
+<programlisting>
+# change pg_options only for a backend
+cat new_pg_options > $DATA_DIR/pg_options
+kill -HUP $backend_pid
+cat old_pg_options > $DATA_DIR/pg_options
+</programlisting>
+
+</chapter>