Properly indent SGML source of libpq.sgml.

1 files changed, 4869 insertions, 4273 deletions

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index f9d73829e74..5e28f8010a7 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,50 +1,50 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.240 2007/08/31 21:33:48 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.241 2007/09/01 22:08:41 momjian Exp $ -->
 
- <chapter id="libpq">
-  <title><application>libpq</application> - C Library</title>
+<chapter id="libpq">
+ <title><application>libpq</application> - C Library</title>
 
-  <indexterm zone="libpq">
-   <primary>libpq</primary>
-  </indexterm>
-
-  <indexterm zone="libpq">
-   <primary>C</primary>
-  </indexterm>
-
-  <para>
-   <application>libpq</application> is the <acronym>C</acronym>
-   application programmer's interface to <productname>PostgreSQL</>.
-   <application>libpq</> is a set of library functions that allow
-   client programs to pass queries to the <productname>PostgreSQL</>
-   backend server and to receive the results of these queries.
-  </para>
-
-  <para>
-   <application>libpq</> is also the underlying engine for several
-   other <productname>PostgreSQL</> application interfaces, including
-   those written for C++, Perl, Python, Tcl and <application>ECPG</>.
-   So some aspects of <application>libpq</>'s behavior will be
-   important to you if you use one of those packages.  In particular,
-   <xref linkend="libpq-envars">,
-   <xref linkend="libpq-pgpass"> and
-   <xref linkend="libpq-ssl">
-   describe behavior that is visible to the user of any application
-   that uses <application>libpq</>.
-  </para>
+ <indexterm zone="libpq">
+  <primary>libpq</primary>
+ </indexterm>
 
-  <para>
-   Some short programs are included at the end of this chapter (<xref linkend="libpq-example">) to show how
-   to write programs that use <application>libpq</application>.  There are also several
-   complete examples of <application>libpq</application> applications in the
-   directory <filename>src/test/examples</filename> in the source code distribution.
-  </para>
+ <indexterm zone="libpq">
+  <primary>C</primary>
+ </indexterm>
 
-  <para>
-   Client programs that use <application>libpq</application> must
-   include the header file
-   <filename>libpq-fe.h</filename><indexterm><primary>libpq-fe.h</></>
-   and must link with the <application>libpq</application> library.
-  </para>
+ <para>
+  <application>libpq</application> is the <acronym>C</acronym>
+  application programmer's interface to <productname>PostgreSQL</>.
+  <application>libpq</> is a set of library functions that allow
+  client programs to pass queries to the <productname>PostgreSQL</>
+  backend server and to receive the results of these queries.
+ </para>
+
+ <para>
+  <application>libpq</> is also the underlying engine for several
+  other <productname>PostgreSQL</> application interfaces, including
+  those written for C++, Perl, Python, Tcl and <application>ECPG</>.
+  So some aspects of <application>libpq</>'s behavior will be
+  important to you if you use one of those packages.  In particular,
+  <xref linkend="libpq-envars">,
+  <xref linkend="libpq-pgpass"> and
+  <xref linkend="libpq-ssl">
+  describe behavior that is visible to the user of any application
+  that uses <application>libpq</>.
+ </para>
+
+ <para>
+  Some short programs are included at the end of this chapter (<xref linkend="libpq-example">) to show how
+  to write programs that use <application>libpq</application>.  There are also several
+  complete examples of <application>libpq</application> applications in the
+  directory <filename>src/test/examples</filename> in the source code distribution.
+ </para>
+
+ <para>
+  Client programs that use <application>libpq</application> must
+  include the header file
+  <filename>libpq-fe.h</filename><indexterm><primary>libpq-fe.h</></>
+  and must link with the <application>libpq</application> library.
+ </para>
 
  <sect1 id="libpq-connect">
   <title>Database Connection Control Functions</title>
@@ -70,937 +70,1031 @@
      <listitem>
       <para>
        Makes a new connection to the database server.
+
+       <synopsis>
+        PGconn *PQconnectdb(const char *conninfo);
+       </synopsis>
+     </para>
+
+     <para>
+      This function opens a new database connection using the parameters taken
+      from the string <literal>conninfo</literal>.  Unlike <function>PQsetdbLogin</> below,
+      the parameter set can be extended without changing the function signature,
+      so use of this function (or its nonblocking analogues <function>PQconnectStart</>
+      and <function>PQconnectPoll</function>) is preferred for new application programming.
+      </para>
+
+     <para>
+      The passed string
+      can be empty to use all default parameters, or it can contain one or more
+      parameter settings separated by whitespace.
+      Each parameter setting is in the form <literal>keyword = value</literal>.
+      Spaces around the equal sign are optional.
+      To write an empty value or a value containing
+      spaces, surround it with single quotes, e.g.,
+      <literal>keyword = 'a value'</literal>.
+      Single quotes and backslashes within the value must be escaped with a
+      backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
+     </para>
+
+     <para>
+      The currently recognized parameter key words are:
+
+      <variablelist>
+       <varlistentry>
+        <term><literal>host</literal></term>
+        <listitem>
+        <para>
+         Name of host to connect to.<indexterm><primary>host name</></>
+         If this begins with a slash, it specifies Unix-domain
+         communication rather than TCP/IP communication; the value is the
+         name of the directory in which the socket file is stored.  The
+         default behavior when <literal>host</literal> is not specified
+         is to connect to a Unix-domain
+         socket<indexterm><primary>Unix domain socket</></> in
+         <filename>/tmp</filename> (or whatever socket directory was specified
+         when <productname>PostgreSQL</> was built). On machines without
+         Unix-domain sockets, the default is to connect to <literal>localhost</>.
+        </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>hostaddr</literal></term>
+        <listitem>
+        <para>
+         Numeric IP address of host to connect to.  This should be in the
+         standard IPv4 address format, e.g., <literal>172.28.40.9</>.  If
+         your machine supports IPv6, you can also use those addresses.
+         TCP/IP communication is
+         always used when a nonempty string is specified for this parameter.
+        </para>
+        <para>
+         Using <literal>hostaddr</> instead of <literal>host</> allows the
+         application to avoid a host name look-up, which might be important in
+         applications with time constraints. However, Kerberos and GSSAPI authentication
+         requires the host name. The following therefore applies: If
+         <literal>host</> is specified without <literal>hostaddr</>, a host name
+         lookup occurs. If <literal>hostaddr</> is specified without
+         <literal>host</>, the value for <literal>hostaddr</> gives the remote
+         address. When Kerberos is used, a reverse name query occurs to obtain
+         the host name for Kerberos. If both
+         <literal>host</> and <literal>hostaddr</> are specified, the value for
+         <literal>hostaddr</> gives the remote address; the value for
+         <literal>host</> is ignored, unless Kerberos is used, in which case that
+         value is used for Kerberos authentication. (Note that authentication is
+         likely to fail if <application>libpq</application> is passed a host name
+         that is not the name of the machine at <literal>hostaddr</>.)  Also,
+         <literal>host</> rather than <literal>hostaddr</> is used to identify
+         the connection in <filename>~/.pgpass</> (see
+         <xref linkend="libpq-pgpass">).
+        </para>
+        <para>
+         Without either a host name or host address,
+         <application>libpq</application> will connect using a
+         local Unix-domain socket; or on machines without Unix-domain
+         sockets, it will attempt to connect to <literal>localhost</>.
+        </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>port</literal></term>
+        <listitem>
+        <para>
+         Port number to connect to at the server host, or socket file
+         name extension for Unix-domain
+         connections.<indexterm><primary>port</></>
+        </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>dbname</literal></term>
+        <listitem>
+        <para>
+         The database name.  Defaults to be the same as the user name.
+        </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>user</literal></term> 
+        <listitem>
+        <para>
+         <productname>PostgreSQL</productname> user name to connect as.
+         Defaults to be the same as the operating system name of the user
+         running the application.
+        </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>password</literal></term>
+        <listitem>
+        <para>
+         Password to be used if the server demands password authentication.
+        </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>connect_timeout</literal></term>
+        <listitem>
+        <para>
+         Maximum wait for connection, in seconds (write as a decimal integer
+         string). Zero or not specified means wait indefinitely.  It is not
+         recommended to use a timeout of less than 2 seconds.
+        </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>options</literal></term>
+        <listitem>
+         <para>
+          Command-line options to be sent to the server.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>tty</literal></term>
+        <listitem>
+        <para>
+         Ignored (formerly, this specified where to send server debug output).
+        </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>sslmode</literal></term>
+        <listitem>
+         <para>
+          This option determines whether or with what priority an
+          <acronym>SSL</> connection will be negotiated with the
+          server. There are four modes: <literal>disable</> will attempt
+          only an unencrypted <acronym>SSL</> connection;
+          <literal>allow</> will negotiate, trying first a
+          non-<acronym>SSL</> connection, then if that fails, trying an
+          <acronym>SSL</> connection; <literal>prefer</> (the default)
+          will negotiate, trying first an <acronym>SSL</> connection,
+          then if that fails, trying a regular non-<acronym>SSL</>
+          connection; <literal>require</> will try only an
+          <acronym>SSL</> connection.
+         </para>
+
+         <para>
+          If <productname>PostgreSQL</> is compiled without SSL support,
+          using option <literal>require</> will cause an error, while
+          options <literal>allow</> and <literal>prefer</> will be
+          accepted but <application>libpq</> will not in fact attempt
+          an <acronym>SSL</>
+          connection.<indexterm><primary>SSL</><secondary
+          sortas="libpq">with libpq</></indexterm>
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>requiressl</literal></term>
+        <listitem>
+         <para>
+          This option is deprecated in favor of the <literal>sslmode</>
+          setting.
+         </para>
+
+         <para>
+          If set to 1, an <acronym>SSL</acronym> connection to the server
+          is required (this is equivalent to <literal>sslmode</>
+          <literal>require</>).  <application>libpq</> will then refuse
+          to connect if the server does not accept an
+          <acronym>SSL</acronym> connection.  If set to 0 (default),
+          <application>libpq</> will negotiate the connection type with
+          the server (equivalent to <literal>sslmode</>
+          <literal>prefer</>).  This option is only available if
+          <productname>PostgreSQL</> is compiled with SSL support.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>krbsrvname</literal></term>
+        <listitem>
+         <para>
+          Kerberos service name to use when authenticating with Kerberos 5
+          or GSSAPI.
+          This must match the service name specified in the server
+          configuration for Kerberos authentication to succeed. (See also
+          <xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.)
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>gsslib</literal></term>
+        <listitem>
+         <para>
+          GSS library to use for GSSAPI authentication. Only used on Windows.
+          Set to <literal>gssapi</literal> to force libpq to use the GSSAPI
+          library for authentication instead of the default SSPI.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>service</literal></term>
+        <listitem>
+        <para>
+         Service name to use for additional parameters.  It specifies a service
+         name in <filename>pg_service.conf</filename> that holds additional connection parameters.
+         This allows applications to specify only a service name so connection parameters 
+         can be centrally maintained. See <xref linkend="libpq-pgservice">.
+        </para>
+        </listitem>
+       </varlistentry>
+      </variablelist>
+
+      If  any  parameter is unspecified, then the corresponding
+      environment variable (see <xref linkend="libpq-envars">)
+      is checked. If the  environment  variable is not set either,
+      then the indicated built-in defaults are used.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></term>
+     <listitem>
+      <para>
+       Makes a new connection to the database server.
 <synopsis>
-PGconn *PQconnectdb(const char *conninfo);
+PGconn *PQsetdbLogin(const char *pghost,
+                     const char *pgport,
+                     const char *pgoptions,
+                     const char *pgtty,
+                     const char *dbName,
+                     const char *login,
+                     const char *pwd);
 </synopsis>
-</para>
-
-<para>
-   This function opens a new database connection using the parameters taken
-   from the string <literal>conninfo</literal>.  Unlike <function>PQsetdbLogin</> below,
-   the parameter set can be extended without changing the function signature,
-   so use of this function (or its nonblocking analogues <function>PQconnectStart</>
-   and <function>PQconnectPoll</function>) is preferred for new application programming.
-   </para>
+       </para>
 
-   <para>
-   The passed string
-   can be empty to use all default parameters, or it can contain one or more
-   parameter settings separated by whitespace.
-   Each parameter setting is in the form <literal>keyword = value</literal>.
-   Spaces around the equal sign are optional.
-   To write an empty value or a value containing
-   spaces, surround it with single quotes, e.g.,
-   <literal>keyword = 'a value'</literal>.
-   Single quotes and backslashes within the value must be escaped with a
-   backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
-   </para>
+       <para>
+        This is the predecessor of <function>PQconnectdb</function> with a fixed
+        set of parameters.  It has the same functionality except that the
+        missing parameters will always take on default values.  Write <symbol>NULL</symbol> or an
+        empty string for any one of the fixed parameters that is to be defaulted.
+      </para>
 
-   <para>
-   The currently recognized parameter key words are:
+      <para>
+        If the <parameter>dbName</parameter> contains an <symbol>=</symbol> sign, it
+        is taken as a <parameter>conninfo</parameter> string in exactly the same way as
+        if it had been passed to <function>PQconnectdb</function>, and the remaining
+        parameters are then applied as above.
+      </para>
+     </listitem>
+    </varlistentry>
 
-   <variablelist>
     <varlistentry>
-     <term><literal>host</literal></term>
+     <term><function>PQsetdb</function><indexterm><primary>PQsetdb</></></term>
      <listitem>
+      <para>
+   Makes a new connection to the database server.
+<synopsis>
+PGconn *PQsetdb(char *pghost,
+                char *pgport,
+                char *pgoptions,
+                char *pgtty,
+                char *dbName);
+</synopsis>
+     </para>
+
      <para>
-      Name of host to connect to.<indexterm><primary>host name</></>
-      If this begins with a slash, it specifies Unix-domain
-      communication rather than TCP/IP communication; the value is the
-      name of the directory in which the socket file is stored.  The
-      default behavior when <literal>host</literal> is not specified
-      is to connect to a Unix-domain
-      socket<indexterm><primary>Unix domain socket</></> in
-      <filename>/tmp</filename> (or whatever socket directory was specified
-      when <productname>PostgreSQL</> was built). On machines without
-      Unix-domain sockets, the default is to connect to <literal>localhost</>.
+      This is a macro that calls <function>PQsetdbLogin</function> with null pointers
+      for the <parameter>login</> and <parameter>pwd</> parameters.  It is provided
+      for backward compatibility with very old programs.
      </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><literal>hostaddr</literal></term>
+     <term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</></></term>
+     <term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</></></term>
      <listitem>
      <para>
-      Numeric IP address of host to connect to.  This should be in the
-      standard IPv4 address format, e.g., <literal>172.28.40.9</>.  If
-      your machine supports IPv6, you can also use those addresses.
-      TCP/IP communication is
-      always used when a nonempty string is specified for this parameter.
+      <indexterm><primary>nonblocking connection</primary></indexterm>
+      Make a connection to the database server in a nonblocking manner.
+
+      <synopsis>
+       PGconn *PQconnectStart(const char *conninfo);
+      </synopsis>
+
+      <synopsis>
+       PostgresPollingStatusType PQconnectPoll(PGconn *conn);
+      </synopsis>
      </para>
+
      <para>
-      Using <literal>hostaddr</> instead of <literal>host</> allows the
-      application to avoid a host name look-up, which might be important in
-      applications with time constraints. However, Kerberos and GSSAPI authentication
-      requires the host name. The following therefore applies: If
-      <literal>host</> is specified without <literal>hostaddr</>, a host name
-      lookup occurs. If <literal>hostaddr</> is specified without
-      <literal>host</>, the value for <literal>hostaddr</> gives the remote
-      address. When Kerberos is used, a reverse name query occurs to obtain
-      the host name for Kerberos. If both
-      <literal>host</> and <literal>hostaddr</> are specified, the value for
-      <literal>hostaddr</> gives the remote address; the value for
-      <literal>host</> is ignored, unless Kerberos is used, in which case that
-      value is used for Kerberos authentication. (Note that authentication is
-      likely to fail if <application>libpq</application> is passed a host name
-      that is not the name of the machine at <literal>hostaddr</>.)  Also,
-      <literal>host</> rather than <literal>hostaddr</> is used to identify
-      the connection in <filename>~/.pgpass</> (see
-      <xref linkend="libpq-pgpass">).
+      These two functions are used to open a connection to a database server such
+      that your application's thread of execution is not blocked on remote I/O
+      whilst doing so.
+      The point of this approach is that the waits for I/O to complete can occur
+      in the application's main loop, rather than down inside
+      <function>PQconnectdb</>, and so the application can manage this
+      operation in parallel with other activities.
      </para>
+
      <para>
-      Without either a host name or host address,
-      <application>libpq</application> will connect using a
-      local Unix-domain socket; or on machines without Unix-domain
-      sockets, it will attempt to connect to <literal>localhost</>.
+      The database connection is made using the parameters taken from the string
+      <literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
+      the same format as described above for <function>PQconnectdb</function>.
      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term><literal>port</literal></term>
-     <listitem>
      <para>
-      Port number to connect to at the server host, or socket file
-      name extension for Unix-domain
-      connections.<indexterm><primary>port</></>
+      Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
+      restrictions are met:
+      <itemizedlist>
+       <listitem>
+        <para>
+         The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
+         name and reverse name queries are not made. See the documentation of
+         these parameters under <function>PQconnectdb</function> above for details.
+        </para>
+       </listitem>
+
+       <listitem>
+        <para>
+         If you call <function>PQtrace</function>, ensure that the stream object
+         into which you trace will not block.
+        </para>
+       </listitem>
+
+       <listitem>
+        <para>
+         You ensure that the socket is in the appropriate state
+         before calling <function>PQconnectPoll</function>, as described below.
+        </para>
+       </listitem>
+      </itemizedlist>
      </para>
-     </listitem>
-    </varlistentry>
 
-    <varlistentry>
-     <term><literal>dbname</literal></term>
-     <listitem>
      <para>
-      The database name.  Defaults to be the same as the user name.
+      To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
+      If <varname>conn</varname> is null, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
+      structure. Otherwise, a valid <structname>PGconn</> pointer is returned (though not yet
+      representing a valid connection to the database). On return from
+      <function>PQconnectStart</function>, call <literal>status = PQstatus(conn)</literal>. If <varname>status</varname> equals
+      <symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
      </para>
-     </listitem>
-    </varlistentry>
 
-    <varlistentry>
-     <term><literal>user</literal></term> 
-     <listitem>
      <para>
-      <productname>PostgreSQL</productname> user name to connect as.
-      Defaults to be the same as the operating system name of the user
-      running the application.
+      If <function>PQconnectStart</> succeeds, the next stage is to poll
+      <application>libpq</> so that it can proceed with the connection sequence.
+      Use <function>PQsocket(conn)</function> to obtain the descriptor of the
+      socket underlying the database connection.
+      Loop thus: If <function>PQconnectPoll(conn)</function> last returned
+      <symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to
+      read (as indicated by <function>select()</>, <function>poll()</>, or
+      similar system function).
+      Then call <function>PQconnectPoll(conn)</function> again.
+      Conversely, if <function>PQconnectPoll(conn)</function> last returned
+      <symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready
+      to write, then call <function>PQconnectPoll(conn)</function> again.
+      If you have yet to call
+      <function>PQconnectPoll</function>, i.e., just after the call to
+      <function>PQconnectStart</function>, behave as if it last returned
+      <symbol>PGRES_POLLING_WRITING</symbol>.  Continue this loop until
+      <function>PQconnectPoll(conn)</function> returns
+      <symbol>PGRES_POLLING_FAILED</symbol>, indicating the connection procedure
+      has failed, or <symbol>PGRES_POLLING_OK</symbol>, indicating the connection
+      has been successfully made.
      </para>
-     </listitem>
-    </varlistentry>
 
-    <varlistentry>
-     <term><literal>password</literal></term>
-     <listitem>
      <para>
-      Password to be used if the server demands password authentication.
+      At any time during connection, the status of the connection can be
+      checked by calling <function>PQstatus</>. If this gives <symbol>CONNECTION_BAD</>, then the
+      connection procedure has failed; if it gives <function>CONNECTION_OK</>, then the
+      connection is ready.  Both of these states are equally detectable
+      from the return value of <function>PQconnectPoll</>, described above. Other states might also occur
+      during (and only during) an asynchronous connection procedure. These
+      indicate the current stage of the connection procedure and might be useful
+      to provide feedback to the user for example. These statuses are:
+
+      <variablelist>
+       <varlistentry>
+        <term><symbol>CONNECTION_STARTED</symbol></term>
+        <listitem>
+         <para>
+          Waiting for connection to be made.
+         </para>
+        </listitem>
+       </varlistentry> 
+
+       <varlistentry>
+        <term><symbol>CONNECTION_MADE</symbol></term>
+        <listitem>
+         <para>
+          Connection OK; waiting to send.
+         </para>
+        </listitem>
+       </varlistentry>  
+
+       <varlistentry>
+        <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
+        <listitem>
+         <para>
+          Waiting for a response from the server.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><symbol>CONNECTION_AUTH_OK</symbol></term>
+        <listitem>
+         <para>
+          Received authentication; waiting for backend start-up to finish.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
+        <listitem>
+         <para>
+          Negotiating SSL encryption.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><symbol>CONNECTION_SETENV</symbol></term>
+        <listitem>
+         <para>
+          Negotiating environment-driven parameter settings.
+         </para>
+        </listitem>
+       </varlistentry>
+      </variablelist>
+
+      Note that, although these constants will remain (in order to maintain
+      compatibility), an application should never rely upon these occurring in a
+      particular order, or at all, or on the status always being one of these
+      documented values. An application might do something like this:
+<programlisting>
+switch(PQstatus(conn))
+{
+        case CONNECTION_STARTED:
+            feedback = "Connecting...";
+            break;
+
+        case CONNECTION_MADE:
+            feedback = "Connected to server...";
+            break;
+.
+.
+.
+        default:
+            feedback = "Connecting...";
+}
+</programlisting>
      </para>
-     </listitem>
-    </varlistentry>
 
-    <varlistentry>
-     <term><literal>connect_timeout</literal></term>
-     <listitem>
      <para>
-      Maximum wait for connection, in seconds (write as a decimal integer
-      string). Zero or not specified means wait indefinitely.  It is not
-      recommended to use a timeout of less than 2 seconds.
+      The <literal>connect_timeout</literal> connection parameter is ignored
+      when using <function>PQconnectPoll</function>; it is the application's
+      responsibility to decide whether an excessive amount of time has elapsed.
+      Otherwise, <function>PQconnectStart</function> followed by a
+      <function>PQconnectPoll</function> loop is equivalent to
+      <function>PQconnectdb</function>.
      </para>
-     </listitem>
-    </varlistentry>
 
-    <varlistentry>
-     <term><literal>options</literal></term>
-     <listitem>
-      <para>
-       Command-line options to be sent to the server.
-      </para>
-     </listitem>
-    </varlistentry>
+     <para>
+      Note that if <function>PQconnectStart</function> returns a non-null pointer, you must call
+      <function>PQfinish</function> when you are finished with it, in order to dispose of
+      the structure and any associated memory blocks. This must be done even if
+      the connection attempt fails or is abandoned.
+     </para>
+    </listitem>
+   </varlistentry>
 
-    <varlistentry>
-     <term><literal>tty</literal></term>
-     <listitem>
+   <varlistentry>
+    <term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></term>
+    <listitem>
      <para>
-      Ignored (formerly, this specified where to send server debug output).
+      Returns the default connection options.
+<synopsis>
+PQconninfoOption *PQconndefaults(void);
+
+typedef struct
+{
+    char   *keyword;   /* The keyword of the option */
+    char   *envvar;    /* Fallback environment variable name */
+    char   *compiled;  /* Fallback compiled in default value */
+    char   *val;       /* Option's current value, or NULL */
+    char   *label;     /* Label for field in connect dialog */
+    char   *dispchar;  /* Character to display for this field
+                          in a connect dialog. Values are:
+                          ""        Display entered value as is
+                          "*"       Password field - hide value
+                          "D"       Debug option - don't show by default */
+    int     dispsize;  /* Field size in characters for dialog */
+} PQconninfoOption;
+</synopsis>
+    </para>
+
+    <para>
+     Returns a connection options array.  This can be used to determine
+     all possible <function>PQconnectdb</function> options and their
+     current default values.  The return value points to an array of
+     <structname>PQconninfoOption</structname> structures, which ends
+     with an entry having a null <structfield>keyword</> pointer.  The
+     null pointer is returned if memory could not be allocated. Note that
+     the current default values (<structfield>val</structfield> fields)
+     will depend on environment variables and other context.  Callers
+     must treat the connection options data as read-only.
+    </para>
+
+    <para>
+     After processing the options array, free it by passing it to
+     <function>PQconninfoFree</function>.  If this is not done, a small amount of memory
+     is leaked for each call to <function>PQconndefaults</function>.
+    </para>
+
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><function>PQfinish</function><indexterm><primary>PQfinish</></></term>
+   <listitem>
+    <para>
+     Closes  the  connection to the server.  Also frees
+     memory used by the <structname>PGconn</structname> object.
+     <synopsis>
+      void PQfinish(PGconn *conn);
+     </synopsis>
+    </para>
+
+    <para>
+     Note that even if the server connection attempt fails (as
+     indicated by <function>PQstatus</function>), the application should call <function>PQfinish</function>
+     to free the memory used by the <structname>PGconn</structname> object.
+     The <structname>PGconn</> pointer must not be used again after
+     <function>PQfinish</function> has been called.
      </para>
-     </listitem>
-    </varlistentry>
+    </listitem>
+   </varlistentry>
 
-    <varlistentry>
-     <term><literal>sslmode</literal></term>
-     <listitem>
-      <para>
-       This option determines whether or with what priority an
-       <acronym>SSL</> connection will be negotiated with the
-       server. There are four modes: <literal>disable</> will attempt
-       only an unencrypted <acronym>SSL</> connection;
-       <literal>allow</> will negotiate, trying first a
-       non-<acronym>SSL</> connection, then if that fails, trying an
-       <acronym>SSL</> connection; <literal>prefer</> (the default)
-       will negotiate, trying first an <acronym>SSL</> connection,
-       then if that fails, trying a regular non-<acronym>SSL</>
-       connection; <literal>require</> will try only an
-       <acronym>SSL</> connection.
-      </para>
+   <varlistentry>
+    <term><function>PQreset</function><indexterm><primary>PQreset</></></term>
+    <listitem>
+     <para>
+      Resets the communication channel to the server.
+      <synopsis>
+       void PQreset(PGconn *conn);
+      </synopsis>
+     </para>
 
-      <para>
-       If <productname>PostgreSQL</> is compiled without SSL support,
-       using option <literal>require</> will cause an error, while
-       options <literal>allow</> and <literal>prefer</> will be
-       accepted but <application>libpq</> will not in fact attempt
-       an <acronym>SSL</>
-       connection.<indexterm><primary>SSL</><secondary
-       sortas="libpq">with libpq</></indexterm>
+     <para>
+      This function will close the connection
+      to the server and attempt to  reestablish  a  new
+      connection to the same server, using all the same
+      parameters previously used.  This might be useful for
+      error recovery if a working connection is lost.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><literal>requiressl</literal></term>
+     <term><function>PQresetStart</function><indexterm><primary>PQresetStart</></></term>
+     <term><function>PQresetPoll</function><indexterm><primary>PQresetPoll</></></term>
      <listitem>
       <para>
-       This option is deprecated in favor of the <literal>sslmode</>
-       setting.
+       Reset the communication channel to the server, in a nonblocking manner.
+
+       <synopsis>
+        int PQresetStart(PGconn *conn);
+       </synopsis>
+       <synopsis>
+        PostgresPollingStatusType PQresetPoll(PGconn *conn);
+       </synopsis>
       </para>
 
       <para>
-       If set to 1, an <acronym>SSL</acronym> connection to the server
-       is required (this is equivalent to <literal>sslmode</>
-       <literal>require</>).  <application>libpq</> will then refuse
-       to connect if the server does not accept an
-       <acronym>SSL</acronym> connection.  If set to 0 (default),
-       <application>libpq</> will negotiate the connection type with
-       the server (equivalent to <literal>sslmode</>
-       <literal>prefer</>).  This option is only available if
-       <productname>PostgreSQL</> is compiled with SSL support.
+       These functions will close the connection to the server and attempt to
+       reestablish a new connection to the same server, using all the same
+       parameters previously used. This can be useful for error recovery if a
+       working connection is lost. They differ from <function>PQreset</function> (above) in that they
+       act in a nonblocking manner. These functions suffer from the same
+       restrictions as <function>PQconnectStart</> and <function>PQconnectPoll</>.
       </para>
-     </listitem>
-    </varlistentry>
 
-    <varlistentry>
-     <term><literal>krbsrvname</literal></term>
-     <listitem>
       <para>
-       Kerberos service name to use when authenticating with Kerberos 5
-       or GSSAPI.
-       This must match the service name specified in the server
-       configuration for Kerberos authentication to succeed. (See also
-       <xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.)
+       To initiate a connection reset, call
+       <function>PQresetStart</function>. If it returns 0, the reset has
+       failed. If it returns 1, poll the reset using
+       <function>PQresetPoll</function> in exactly the same way as you
+       would create the connection using <function>PQconnectPoll</function>.
       </para>
      </listitem>
     </varlistentry>
 
-    <varlistentry>
-     <term><literal>gsslib</literal></term>
-     <listitem>
-      <para>
-       GSS library to use for GSSAPI authentication. Only used on Windows.
-       Set to <literal>gssapi</literal> to force libpq to use the GSSAPI
-       library for authentication instead of the default SSPI.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term><literal>service</literal></term>
-     <listitem>
-     <para>
-      Service name to use for additional parameters.  It specifies a service
-      name in <filename>pg_service.conf</filename> that holds additional connection parameters.
-      This allows applications to specify only a service name so connection parameters 
-      can be centrally maintained. See <xref linkend="libpq-pgservice">.
-     </para>
-     </listitem>
-    </varlistentry>
    </variablelist>
+  </para>
+ </sect1>
 
-   If  any  parameter is unspecified, then the corresponding
-   environment variable (see <xref linkend="libpq-envars">)
-   is checked. If the  environment  variable is not set either,
-   then the indicated built-in defaults are used.
-   </para>
-  </listitem>
- </varlistentry>
+ <sect1 id="libpq-status">
+  <title>Connection Status Functions</title>
 
- <varlistentry>
-  <term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></term>
-  <listitem>
-   <para>
-       Makes a new connection to the database server.
-<synopsis>
-PGconn *PQsetdbLogin(const char *pghost,
-                     const char *pgport,
-                     const char *pgoptions,
-                     const char *pgtty,
-                     const char *dbName,
-                     const char *login,
-                     const char *pwd);
-</synopsis>
-    </para>
+  <para>
+   These functions can be used to interrogate the status
+   of an existing database connection object.
+  </para>
 
-    <para>
-     This is the predecessor of <function>PQconnectdb</function> with a fixed
-     set of parameters.  It has the same functionality except that the
-     missing parameters will always take on default values.  Write <symbol>NULL</symbol> or an
-     empty string for any one of the fixed parameters that is to be defaulted.
-   </para>
+  <tip>
    <para>
-     If the <parameter>dbName</parameter> contains an <symbol>=</symbol> sign, it
-     is taken as a <parameter>conninfo</parameter> string in exactly the same way as
-     if it had been passed to <function>PQconnectdb</function>, and the remaining
-     parameters are then applied as above.
+    <indexterm><primary>libpq-fe.h</></>
+    <indexterm><primary>libpq-int.h</></>
+    <application>libpq</application> application programmers should be careful to
+    maintain the <structname>PGconn</structname> abstraction.  Use the accessor
+    functions described below to get at the contents of <structname>PGconn</structname>.
+    Reference to internal <structname>PGconn</structname> fields using 
+    <filename>libpq-int.h</> is not recommended because they are subject to change
+    in the future.
    </para>
-  </listitem>
- </varlistentry>
+   </tip>
 
- <varlistentry>
-  <term><function>PQsetdb</function><indexterm><primary>PQsetdb</></></term>
-  <listitem>
    <para>
-   Makes a new connection to the database server.
-<synopsis>
-PGconn *PQsetdb(char *pghost,
-                char *pgport,
-                char *pgoptions,
-                char *pgtty,
-                char *dbName);
-</synopsis>
-</para>
-
-<para>
-   This is a macro that calls <function>PQsetdbLogin</function> with null pointers
-   for the <parameter>login</> and <parameter>pwd</> parameters.  It is provided
-   for backward compatibility with very old programs.
-   </para>
-  </listitem>
- </varlistentry>
-
- <varlistentry>
-  <term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</></></term>
-  <term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</></></term>
-  <listitem>
-  <para>
-   <indexterm><primary>nonblocking connection</primary></indexterm>
-   Make a connection to the database server in a nonblocking manner.
-<synopsis>
-PGconn *PQconnectStart(const char *conninfo);
-</synopsis>
-<synopsis>
-PostgresPollingStatusType PQconnectPoll(PGconn *conn);
-</synopsis>
-</para>
-<para>
-   These two functions are used to open a connection to a database server such
-   that your application's thread of execution is not blocked on remote I/O
-   whilst doing so.
-   The point of this approach is that the waits for I/O to complete can occur
-   in the application's main loop, rather than down inside
-   <function>PQconnectdb</>, and so the application can manage this
-   operation in parallel with other activities.
-  </para>
-  <para>
-   The database connection is made using the parameters taken from the string
-   <literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
-   the same format as described above for <function>PQconnectdb</function>.
-  </para>
-  <para>
-   Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
-   restrictions are met:
-   <itemizedlist>
-    <listitem>
-     <para>
-      The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
-      name and reverse name queries are not made. See the documentation of
-      these parameters under <function>PQconnectdb</function> above for details.
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
-      If you call <function>PQtrace</function>, ensure that the stream object
-      into which you trace will not block.
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
-      You ensure that the socket is in the appropriate state
-      before calling <function>PQconnectPoll</function>, as described below.
-     </para>
-    </listitem>
-   </itemizedlist>
-  </para>
-
-  <para>
-   To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
-   If <varname>conn</varname> is null, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
-   structure. Otherwise, a valid <structname>PGconn</> pointer is returned (though not yet
-   representing a valid connection to the database). On return from
-   <function>PQconnectStart</function>, call <literal>status = PQstatus(conn)</literal>. If <varname>status</varname> equals
-   <symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
-  </para>
-  <para>
-   If <function>PQconnectStart</> succeeds, the next stage is to poll
-   <application>libpq</> so that it can proceed with the connection sequence.
-   Use <function>PQsocket(conn)</function> to obtain the descriptor of the
-   socket underlying the database connection.
-   Loop thus: If <function>PQconnectPoll(conn)</function> last returned
-   <symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to
-   read (as indicated by <function>select()</>, <function>poll()</>, or
-   similar system function).
-   Then call <function>PQconnectPoll(conn)</function> again.
-   Conversely, if <function>PQconnectPoll(conn)</function> last returned
-   <symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready
-   to write, then call <function>PQconnectPoll(conn)</function> again.
-   If you have yet to call
-   <function>PQconnectPoll</function>, i.e., just after the call to
-   <function>PQconnectStart</function>, behave as if it last returned
-   <symbol>PGRES_POLLING_WRITING</symbol>.  Continue this loop until
-   <function>PQconnectPoll(conn)</function> returns
-   <symbol>PGRES_POLLING_FAILED</symbol>, indicating the connection procedure
-   has failed, or <symbol>PGRES_POLLING_OK</symbol>, indicating the connection
-   has been successfully made.
-  </para>
-
-  <para>
-    At any time during connection, the status of the connection can be
-    checked by calling <function>PQstatus</>. If this gives <symbol>CONNECTION_BAD</>, then the
-    connection procedure has failed; if it gives <function>CONNECTION_OK</>, then the
-    connection is ready.  Both of these states are equally detectable
-    from the return value of <function>PQconnectPoll</>, described above. Other states might also occur
-    during (and only during) an asynchronous connection procedure. These
-    indicate the current stage of the connection procedure and might be useful
-    to provide feedback to the user for example. These statuses are:
+    The following functions return parameter values established at connection.
+    These values are fixed for the life of the <structname>PGconn</> object.
 
     <variablelist>
      <varlistentry>
-      <term><symbol>CONNECTION_STARTED</symbol></term>
-      <listitem>
-       <para>
-        Waiting for connection to be made.
-       </para>
-      </listitem>
-     </varlistentry> 
+      <term>
+       <function>PQdb</function>
+       <indexterm>
+        <primary>PQdb</primary>
+       </indexterm>
+      </term>
 
-     <varlistentry>
-      <term><symbol>CONNECTION_MADE</symbol></term>
       <listitem>
        <para>
-        Connection OK; waiting to send.
+        Returns the database name of the connection.
+        <synopsis>
+         char *PQdb(const PGconn *conn);
+        </synopsis>
        </para>
       </listitem>
-     </varlistentry>  
+     </varlistentry>
 
      <varlistentry>
-      <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
+      <term>
+       <function>PQuser</function>
+       <indexterm>
+        <primary>PQuser</primary>
+       </indexterm>
+      </term>
+
       <listitem>
        <para>
-        Waiting for a response from the server.
+        Returns the user name of the connection.
+        <synopsis>
+         char *PQuser(const PGconn *conn);
+        </synopsis>
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><symbol>CONNECTION_AUTH_OK</symbol></term>
+      <term>
+       <function>PQpass</function>
+       <indexterm>
+        <primary>PQpass</primary>
+       </indexterm>
+      </term>
+
       <listitem>
        <para>
-        Received authentication; waiting for backend start-up to finish.
+        Returns the password of the connection.
+        <synopsis>
+         char *PQpass(const PGconn *conn);
+        </synopsis>
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
+      <term>
+       <function>PQhost</function>
+       <indexterm>
+        <primary>PQhost</primary>
+       </indexterm>
+      </term>
+
       <listitem>
        <para>
-        Negotiating SSL encryption.
+        Returns the server host name of the connection.
+        <synopsis>
+         char *PQhost(const PGconn *conn);
+        </synopsis>
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><symbol>CONNECTION_SETENV</symbol></term>
-      <listitem>
-       <para>
-        Negotiating environment-driven parameter settings.
-       </para>
-      </listitem>
-     </varlistentry>
-    </variablelist>
+     <term>
+      <function>PQport</function>
+      <indexterm>
+       <primary>PQport</primary>
+      </indexterm>
+     </term>
 
-    Note that, although these constants will remain (in order to maintain
-    compatibility), an application should never rely upon these occurring in a
-    particular order, or at all, or on the status always being one of these
-    documented values. An application might do something like this:
-<programlisting>
-switch(PQstatus(conn))
-{
-    case CONNECTION_STARTED:
-        feedback = "Connecting...";
-        break;
+     <listitem>
+      <para>
+       Returns the port of the connection.
 
-    case CONNECTION_MADE:
-        feedback = "Connected to server...";
-        break;
-.
-.
-.
-    default:
-        feedback = "Connecting...";
-}
-</programlisting>
-  </para>
+       <synopsis>
+        char *PQport(const PGconn *conn);
+       </synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
 
-  <para>
-   The <literal>connect_timeout</literal> connection parameter is ignored
-   when using <function>PQconnectPoll</function>; it is the application's
-   responsibility to decide whether an excessive amount of time has elapsed.
-   Otherwise, <function>PQconnectStart</function> followed by a
-   <function>PQconnectPoll</function> loop is equivalent to
-   <function>PQconnectdb</function>.
+    <varlistentry>
+     <term>
+      <function>PQtty</function>
+      <indexterm>
+       <primary>PQtty</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the debug <acronym>TTY</acronym> of the connection.
+       (This is obsolete, since the server no longer pays attention
+       to the <acronym>TTY</acronym> setting, but the function remains
+       for backwards compatibility.)
+
+       <synopsis>
+        char *PQtty(const PGconn *conn);
+       </synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term>
+      <function>PQoptions</function>
+      <indexterm>
+       <primary>PQoptions</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the command-line options passed in the connection request.
+       <synopsis>
+        char *PQoptions(const PGconn *conn);
+       </synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
 
   <para>
-   Note that if <function>PQconnectStart</function> returns a non-null pointer, you must call
-   <function>PQfinish</function> when you are finished with it, in order to dispose of
-   the structure and any associated memory blocks. This must be done even if
-   the connection attempt fails or is abandoned.
-  </para>
-  </listitem>
- </varlistentry>
+   The following functions return status data that can change as operations
+   are executed on the <structname>PGconn</> object.
 
- <varlistentry>
-  <term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></term>
-  <listitem>
-   <para>
-   Returns the default connection options.
-<synopsis>
-PQconninfoOption *PQconndefaults(void);
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQstatus</function>
+      <indexterm>
+       <primary>PQstatus</primary>
+      </indexterm>
+     </term>
 
-typedef struct
-{
-    char   *keyword;   /* The keyword of the option */
-    char   *envvar;    /* Fallback environment variable name */
-    char   *compiled;  /* Fallback compiled in default value */
-    char   *val;       /* Option's current value, or NULL */
-    char   *label;     /* Label for field in connect dialog */
-    char   *dispchar;  /* Character to display for this field
-                          in a connect dialog. Values are:
-                          ""        Display entered value as is
-                          "*"       Password field - hide value
-                          "D"       Debug option - don't show by default */
-    int     dispsize;  /* Field size in characters for dialog */
-} PQconninfoOption;
-</synopsis>
-</para>
-
-<para>
-   Returns a connection options array.  This can be used to determine
-   all possible <function>PQconnectdb</function> options and their
-   current default values.  The return value points to an array of
-   <structname>PQconninfoOption</structname> structures, which ends
-   with an entry having a null <structfield>keyword</> pointer.  The
-   null pointer is returned if memory could not be allocated. Note that
-   the current default values (<structfield>val</structfield> fields)
-   will depend on environment variables and other context.  Callers
-   must treat the connection options data as read-only.
-   </para>
+     <listitem>
+      <para>
+       Returns the status of the connection. 
+       <synopsis>
+        ConnStatusType PQstatus(const PGconn *conn);
+       </synopsis>
+      </para>
 
-   <para>
-    After processing the options array, free it by passing it to
-    <function>PQconninfoFree</function>.  If this is not done, a small amount of memory
-    is leaked for each call to <function>PQconndefaults</function>.
-   </para>
+      <para>
+       The status can be one of a number of values.  However, only two of
+       these are seen outside of an asynchronous connection procedure:
+       <literal>CONNECTION_OK</literal> and
+       <literal>CONNECTION_BAD</literal>. A good connection to the database
+       has the status <literal>CONNECTION_OK</literal>.  A failed
+       connection attempt is signaled by status
+       <literal>CONNECTION_BAD</literal>.  Ordinarily, an OK status will
+       remain so until <function>PQfinish</function>, but a communications
+       failure might result in the status changing to
+       <literal>CONNECTION_BAD</literal> prematurely.  In that case the
+       application could try to recover by calling
+       <function>PQreset</function>.
+      </para>
 
-  </listitem>
- </varlistentry>
+      <para>
+       See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
+       to other status codes
+       that might be seen.
+      </para>
+     </listitem>
+    </varlistentry>
 
- <varlistentry>
-  <term><function>PQfinish</function><indexterm><primary>PQfinish</></></term>
-  <listitem>
-   <para>
-   Closes  the  connection to the server.  Also frees
-   memory used by the <structname>PGconn</structname> object.
-<synopsis>
-void PQfinish(PGconn *conn);
-</synopsis>
-</para>
-
-<para>
-   Note that even if the server connection attempt fails (as
-   indicated by <function>PQstatus</function>), the application should call <function>PQfinish</function>
-   to free the memory used by the <structname>PGconn</structname> object.
-   The <structname>PGconn</> pointer must not be used again after
-   <function>PQfinish</function> has been called.
-   </para>
-  </listitem>
- </varlistentry>
+    <varlistentry>
+     <term>
+      <function>PQtransactionStatus</function>
+      <indexterm>
+       <primary>PQtransactionStatus</primary>
+      </indexterm>
+     </term>
 
- <varlistentry>
-  <term><function>PQreset</function><indexterm><primary>PQreset</></></term>
-  <listitem>
-   <para>
-   Resets the communication channel to the server.
-<synopsis>
-void PQreset(PGconn *conn);
-</synopsis>
-</para>
-
-<para>
-   This function will close the connection
-   to the server and attempt to  reestablish  a  new
-   connection to the same server, using all the same
-   parameters previously used.  This might be useful for
-   error recovery if a working connection is lost.
-   </para>
-  </listitem>
- </varlistentry>
+     <listitem>
+      <para>
+       Returns the current in-transaction status of the server.
+
+       <synopsis>
+        PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
+       </synopsis>
+
+       The status can be <literal>PQTRANS_IDLE</literal> (currently idle),
+       <literal>PQTRANS_ACTIVE</literal> (a command is in progress),
+       <literal>PQTRANS_INTRANS</literal> (idle, in a valid transaction block),
+       or <literal>PQTRANS_INERROR</literal> (idle, in a failed transaction block).
+       <literal>PQTRANS_UNKNOWN</literal> is reported if the connection is bad.
+       <literal>PQTRANS_ACTIVE</literal> is reported only when a query
+       has been sent to the server and not yet completed.
+      </para>
 
- <varlistentry>
-  <term><function>PQresetStart</function><indexterm><primary>PQresetStart</></></term>
-  <term><function>PQresetPoll</function><indexterm><primary>PQresetPoll</></></term>
-  <listitem>
-   <para>
-   Reset the communication channel to the server, in a nonblocking manner.
-<synopsis>
-int PQresetStart(PGconn *conn);
-</synopsis>
-<synopsis>
-PostgresPollingStatusType PQresetPoll(PGconn *conn);
-</synopsis>
-</para>
-
-<para>
-    These functions will close the connection to the server and attempt to
-    reestablish a new connection to the same server, using all the same
-    parameters previously used. This can be useful for error recovery if a
-    working connection is lost. They differ from <function>PQreset</function> (above) in that they
-    act in a nonblocking manner. These functions suffer from the same
-    restrictions as <function>PQconnectStart</> and <function>PQconnectPoll</>.
-   </para>
-   <para>
-    To initiate a connection reset, call <function>PQresetStart</function>. If it returns 0, the reset has failed. If it returns 1,
-    poll the reset using <function>PQresetPoll</function> in exactly the same way as you would
-    create the connection using <function>PQconnectPoll</function>.
-   </para>
-  </listitem>
- </varlistentry>
+      <caution>
+       <para>
+        <function>PQtransactionStatus</> will give incorrect results when using
+        a <productname>PostgreSQL</> 7.3 server that has the parameter <literal>autocommit</>
+        set to off.  The server-side autocommit feature has been
+        deprecated and does not exist in later server versions.
+       </para>
+      </caution>
+     </listitem>
+    </varlistentry>
 
- </variablelist>
-</para>
-</sect1>
+    <varlistentry>
+     <term>
+      <function>PQparameterStatus</function>
+      <indexterm>
+       <primary>PQparameterStatus</primary>
+      </indexterm>
+     </term>
 
-<sect1 id="libpq-status">
-<title>Connection Status Functions</title>
+     <listitem>
+      <para>
+       Looks up a current parameter setting of the server.
 
-  <para>
-   These functions can be used to interrogate the status
-   of an existing database connection object.
-  </para>
+       <synopsis>
+        const char *PQparameterStatus(const PGconn *conn, const char *paramName);
+       </synopsis>
 
-<tip>
-<para>
-<indexterm><primary>libpq-fe.h</></>
-<indexterm><primary>libpq-int.h</></>
-<application>libpq</application> application programmers should be careful to
-maintain the <structname>PGconn</structname> abstraction.  Use the accessor
-functions described below to get at the contents of <structname>PGconn</structname>.
-Reference to internal <structname>PGconn</structname> fields using 
-<filename>libpq-int.h</> is not recommended because they are subject to change
-in the future.
-</para>
-</tip>
-
-<para>
-The following functions return parameter values established at connection.
-These values are fixed for the life of the <structname>PGconn</> object.
-
-<variablelist>
-<varlistentry>
-<term><function>PQdb</function><indexterm><primary>PQdb</></></term>
-<listitem>
-<para>
-         Returns the database name of the connection.
-<synopsis>
-char *PQdb(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQuser</function><indexterm><primary>PQuser</></></term>
-<listitem>
-<para>
-         Returns the user name of the connection.
-<synopsis>
-char *PQuser(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQpass</function><indexterm><primary>PQpass</></></term>
-<listitem>
-<para>
-         Returns the password of the connection.
-<synopsis>
-char *PQpass(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQhost</function><indexterm><primary>PQhost</></></term>
-<listitem>
-<para>
-         Returns the server host name of the connection.
-<synopsis>
-char *PQhost(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQport</function><indexterm><primary>PQport</></></term>
-<listitem>
-<para>
-         Returns the port of the connection.
-<synopsis>
-char *PQport(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQtty</function><indexterm><primary>PQtty</></></term>
-<listitem>
-<para>
-         Returns the debug <acronym>TTY</acronym> of the connection.
-         (This is obsolete, since the server no longer pays attention
-         to the <acronym>TTY</acronym> setting, but the function remains
-         for backwards compatibility.)
-<synopsis>
-char *PQtty(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQoptions</function><indexterm><primary>PQoptions</></></term>
-<listitem>
-<para>
-       Returns the command-line options passed in the connection request.
-<synopsis>
-char *PQoptions(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-The following functions return status data that can change as operations
-are executed on the <structname>PGconn</> object.
-
-<variablelist>
-<varlistentry>
-<term><function>PQstatus</function><indexterm><primary>PQstatus</></></term>
-<listitem>
-<para>
-         Returns the status of the connection. 
-<synopsis>
-ConnStatusType PQstatus(const PGconn *conn);
-</synopsis>
-</para>
+       Certain parameter values are reported by the server automatically at
+       connection startup or whenever their values change.
+       <function>PQparameterStatus</> can be used to interrogate these settings.
+       It returns the current value of a parameter if known, or <symbol>NULL</symbol>
+       if the parameter is not known.
+      </para>
 
       <para>
-       The status can be one of a number of values.
-       However, only two of these are
-       seen outside of an asynchronous connection procedure:
-       <literal>CONNECTION_OK</literal> and
-       <literal>CONNECTION_BAD</literal>. A good
-       connection to the database has the status <literal>CONNECTION_OK</literal>.
-       A failed connection
-       attempt is signaled by status
-       <literal>CONNECTION_BAD</literal>.
-       Ordinarily, an OK status will remain so until
-       <function>PQfinish</function>, but a
-       communications failure might result in the status changing to
-       <literal>CONNECTION_BAD</literal> prematurely.
-       In that case the application
-       could try to recover by calling <function>PQreset</function>.
+       Parameters reported as of the current release include
+       <literal>server_version</>,
+       <literal>server_encoding</>,
+       <literal>client_encoding</>,
+       <literal>is_superuser</>,
+       <literal>session_authorization</>,
+       <literal>DateStyle</>,
+       <literal>TimeZone</>,
+       <literal>integer_datetimes</>, and
+       <literal>standard_conforming_strings</>.
+       (<literal>server_encoding</>, <literal>TimeZone</>, and
+       <literal>integer_datetimes</> were not reported by releases before 8.0;
+       <literal>standard_conforming_strings</> was not reported by releases
+       before 8.1.)
+       Note that
+       <literal>server_version</>,
+       <literal>server_encoding</> and
+       <literal>integer_datetimes</>
+       cannot change after startup.
       </para>
 
       <para>
-       See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
-       to other status codes
-       that might be seen.
+       Pre-3.0-protocol servers do not report parameter settings, but
+       <application>libpq</> includes logic to obtain values for
+       <literal>server_version</> and <literal>client_encoding</> anyway.
+       Applications are encouraged to use <function>PQparameterStatus</>
+       rather than <foreignphrase>ad hoc</> code to determine these values.
+       (Beware however that on a pre-3.0 connection, changing
+       <literal>client_encoding</> via <command>SET</> after connection
+       startup will not be reflected by <function>PQparameterStatus</>.)
+       For <literal>server_version</>, see also
+       <function>PQserverVersion</>, which returns the information in a
+       numeric form that is much easier to compare against.
+      </para>
+
+      <para>
+       If no value for <literal>standard_conforming_strings</> is reported,
+       applications can assume it is <literal>off</>, that is, backslashes
+       are treated as escapes in string literals.  Also, the presence of
+       this parameter can be taken as an indication that the escape string
+       syntax (<literal>E'...'</>) is accepted.
+      </para>
+
+      <para>
+       Although the returned pointer is declared <literal>const</>, it in fact
+       points to mutable storage associated with the <literal>PGconn</> structure.
+       It is unwise to assume the pointer will remain valid across queries.
       </para>
      </listitem>
     </varlistentry>
 
-<varlistentry>
-<term><function>PQtransactionStatus</function><indexterm><primary>PQtransactionStatus</></></term>
-<listitem>
-<para>
-         Returns the current in-transaction status of the server.
-<synopsis>
-PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
-</synopsis>
+    <varlistentry>
+     <term>
+      <function>PQprotocolVersion</function>
+      <indexterm>
+       <primary>PQprotocolVersion</primary>
+      </indexterm>
+     </term>
 
-The status can be <literal>PQTRANS_IDLE</literal> (currently idle),
-<literal>PQTRANS_ACTIVE</literal> (a command is in progress),
-<literal>PQTRANS_INTRANS</literal> (idle, in a valid transaction block),
-or <literal>PQTRANS_INERROR</literal> (idle, in a failed transaction block).
-<literal>PQTRANS_UNKNOWN</literal> is reported if the connection is bad.
-<literal>PQTRANS_ACTIVE</literal> is reported only when a query
-has been sent to the server and not yet completed.
-</para>
-<caution>
-<para>
-<function>PQtransactionStatus</> will give incorrect results when using
-a <productname>PostgreSQL</> 7.3 server that has the parameter <literal>autocommit</>
-set to off.  The server-side autocommit feature has been
-deprecated and does not exist in later server versions.
-</para>
-</caution>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQparameterStatus</function><indexterm><primary>PQparameterStatus</></></term>
-<listitem>
-<para>
-         Looks up a current parameter setting of the server.
-<synopsis>
-const char *PQparameterStatus(const PGconn *conn, const char *paramName);
-</synopsis>
+     <listitem>
+      <para>
+       Interrogates the frontend/backend protocol being used.
+       <synopsis>
+        int PQprotocolVersion(const PGconn *conn);
+       </synopsis>
+       Applications might wish to use this to determine whether certain
+       features are supported.  Currently, the possible values are 2 (2.0
+       protocol), 3 (3.0 protocol), or zero (connection bad).  This will
+       not change after connection startup is complete, but it could
+       theoretically change during a connection reset.  The 3.0 protocol
+       will normally be used when communicating with
+       <productname>PostgreSQL</> 7.4 or later servers; pre-7.4 servers
+       support only protocol 2.0.  (Protocol 1.0 is obsolete and not
+       supported by <application>libpq</application>.)
+      </para>
+     </listitem>
+    </varlistentry>
 
-Certain parameter values are reported by the server automatically at
-connection startup or whenever their values change.
-<function>PQparameterStatus</> can be used to interrogate these settings.
-It returns the current value of a parameter if known, or <symbol>NULL</symbol>
-if the parameter is not known.
-</para>
-
-<para>
-Parameters reported as of the current release include
-<literal>server_version</>,
-<literal>server_encoding</>,
-<literal>client_encoding</>,
-<literal>is_superuser</>,
-<literal>session_authorization</>,
-<literal>DateStyle</>,
-<literal>TimeZone</>,
-<literal>integer_datetimes</>, and
-<literal>standard_conforming_strings</>.
-(<literal>server_encoding</>, <literal>TimeZone</>, and
-<literal>integer_datetimes</> were not reported by releases before 8.0;
-<literal>standard_conforming_strings</> was not reported by releases
-before 8.1.)
-Note that
-<literal>server_version</>,
-<literal>server_encoding</> and
-<literal>integer_datetimes</>
-cannot change after startup.
-</para>
-
-<para>
-Pre-3.0-protocol servers do not report parameter settings, but
-<application>libpq</> includes logic to obtain values for
-<literal>server_version</> and <literal>client_encoding</> anyway.
-Applications are encouraged to use <function>PQparameterStatus</>
-rather than <foreignphrase>ad hoc</> code to determine these values.
-(Beware however
-that on a pre-3.0 connection, changing <literal>client_encoding</> via
-<command>SET</> after connection startup will not be reflected by
-<function>PQparameterStatus</>.)  For <literal>server_version</>,
-see also <function>PQserverVersion</>, which returns the information
-in a numeric form that is much easier to compare against.
-</para>
-
-<para>
-If no value for <literal>standard_conforming_strings</> is reported,
-applications can assume it is <literal>off</>, that is, backslashes
-are treated as escapes in string literals.  Also, the presence of this
-parameter can be taken as an indication that the escape string syntax
-(<literal>E'...'</>) is accepted.
-</para>
-
-<para>
-Although the returned pointer is declared <literal>const</>, it in fact
-points to mutable storage associated with the <literal>PGconn</> structure.
-It is unwise to assume the pointer will remain valid across queries.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQprotocolVersion</function><indexterm><primary>PQprotocolVersion</></></term>
-<listitem>
-<para>
-         Interrogates the frontend/backend protocol being used.
-<synopsis>
-int PQprotocolVersion(const PGconn *conn);
-</synopsis>
-Applications might wish to use this to determine whether certain features
-are supported.
-Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol),
-or zero (connection bad).  This will not change after connection
-startup is complete, but it could theoretically change during a connection
-reset.  The 3.0 protocol will normally be used when communicating with
-<productname>PostgreSQL</> 7.4 or later servers; pre-7.4 servers support
-only protocol 2.0.  (Protocol 1.0 is obsolete and not supported by <application>libpq</application>.)
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQserverVersion</function><indexterm><primary>PQserverVersion</></></term>
-<listitem>
-<para>
-         Returns an integer representing the backend version.
-<synopsis>
-int PQserverVersion(const PGconn *conn);
-</synopsis>
-Applications might use this to determine the version of the database server they
-are connected to. The number is formed by converting the major, minor, and
-revision numbers into two-decimal-digit numbers and appending them
-together. For example, version 8.1.5 will be returned as 80105, and version
-8.2 will be returned as 80200 (leading zeroes are not shown).  Zero is
-returned if the connection is bad.
-</para>
-</listitem>
-</varlistentry>
+    <varlistentry>
+     <term>
+      <function>PQserverVersion</function>
+      <indexterm>
+       <primary>PQserverVersion</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns an integer representing the backend version.
+       <synopsis>
+        int PQserverVersion(const PGconn *conn);
+       </synopsis>
+       Applications might use this to determine the version of the database
+       server they are connected to. The number is formed by converting
+       the major, minor, and revision numbers into two-decimal-digit
+       numbers and appending them together. For example, version 8.1.5
+       will be returned as 80105, and version 8.2 will be returned as
+       80200 (leading zeroes are not shown).  Zero is returned if the
+       connection is bad.
+      </para>
+     </listitem>
+    </varlistentry>
 
     <varlistentry>
-     <term><function>PQerrorMessage</function><indexterm><primary>PQerrorMessage</></></term>
+     <term>
+      <function>PQerrorMessage</function>
+      <indexterm>
+       <primary>PQerrorMessage</primary>
+      </indexterm>
+     </term>
+
      <listitem>
       <para>
-       <indexterm><primary>error message</></>
-       Returns the error message most recently generated by
-       an operation on the connection.
-<synopsis>
-char *PQerrorMessage(const PGconn *conn);
-</synopsis>
+       <indexterm><primary>error message</></> Returns the error message
+       most recently generated by an operation on the connection.
+
+       <synopsis>
+        char *PQerrorMessage(const PGconn *conn);
+       </synopsis>
+
       </para>
 
       <para>
        Nearly all <application>libpq</> functions will set a message for
-       <function>PQerrorMessage</function> if they fail.
-       Note that by <application>libpq</application> convention, a nonempty
-       <function>PQerrorMessage</function> result will
-       include a trailing newline. The caller should not free the result 
-       directly. It will be freed when the associated <structname>PGconn</> 
-       handle is passed to <function>PQfinish</function>.  The result string
-       should not be expected to remain the same across operations on the
+       <function>PQerrorMessage</function> if they fail.  Note that by
+       <application>libpq</application> convention, a nonempty
+       <function>PQerrorMessage</function> result will include a trailing
+       newline. The caller should not free the result directly. It will
+       be freed when the associated <structname>PGconn</> handle is passed
+       to <function>PQfinish</function>.  The result string should not be
+       expected to remain the same across operations on the
        <literal>PGconn</> structure.
       </para>
      </listitem>
@@ -1015,9 +1109,11 @@ char *PQerrorMessage(const PGconn *conn);
        to 0; a result of -1 indicates that no server connection is
        currently open.  (This will not change during normal operation,
        but could change during connection setup or reset.)
-<synopsis>
-int PQsocket(const PGconn *conn);
-</synopsis>
+
+       <synopsis>
+        int PQsocket(const PGconn *conn);
+       </synopsis>
+
       </para>
      </listitem>
     </varlistentry>
@@ -1030,12 +1126,13 @@ int PQsocket(const PGconn *conn);
        (PID)<indexterm><primary>PID</><secondary>determining PID of
        server process</><tertiary>in libpq</></> of the backend server
        process handling this connection.
-<synopsis>
-int PQbackendPID(const PGconn *conn);
-</synopsis>
-</para>
 
-<para>
+       <synopsis>
+        int PQbackendPID(const PGconn *conn);
+       </synopsis>
+      </para>
+
+      <para>
        The backend <acronym>PID</acronym> is useful for debugging
        purposes and for comparison to <command>NOTIFY</command>
        messages (which include the <acronym>PID</acronym> of the
@@ -1052,9 +1149,11 @@ int PQbackendPID(const PGconn *conn);
       <para>
        Returns true (1) if the connection authentication method
        required a password to be supplied. Returns false (0) if not.
-<synopsis>
-int PQconnectionUsedPassword(const PGconn *conn);
-</synopsis>
+
+       <synopsis>
+        int PQconnectionUsedPassword(const PGconn *conn);
+       </synopsis>
+
       </para>
 
       <para>
@@ -1072,16 +1171,18 @@ int PQconnectionUsedPassword(const PGconn *conn);
        <indexterm><primary>SSL</><secondary sortas="libpq">in libpq</secondary></indexterm>
        Returns the SSL structure used in the connection, or null
        if SSL is not in use. 
-<synopsis>
-SSL *PQgetssl(const PGconn *conn);
-</synopsis>
-</para>
 
-<para>
-       This structure can be used to verify encryption levels, check
-       server certificates, and more. Refer to the <productname>OpenSSL</> documentation
-       for information about this structure.
+       <synopsis>
+        SSL *PQgetssl(const PGconn *conn);
+       </synopsis>
       </para>
+
+      <para>
+       This structure can be used to verify encryption levels, check server
+       certificates, and more. Refer to the <productname>OpenSSL</>
+       documentation for information about this structure.
+      </para>
+
       <para>
        You must define <symbol>USE_SSL</symbol> in order to get the
        correct prototype for this function. Doing this will also 
@@ -1090,70 +1191,83 @@ SSL *PQgetssl(const PGconn *conn);
      </listitem>
     </varlistentry>
 
-</variablelist>
-</para>
+   </variablelist>
+  </para>
 
-</sect1>
+ </sect1>
 
-<sect1 id="libpq-exec">
-<title>Command Execution Functions</title>
+ <sect1 id="libpq-exec">
+  <title>Command Execution Functions</title>
 
-<para>
-Once a connection to a database server has been successfully
-established, the functions described here are used to perform
-SQL queries and commands.
-</para>
+  <para>
+   Once a connection to a database server has been successfully
+   established, the functions described here are used to perform
+   SQL queries and commands.
+  </para>
 
-<sect2 id="libpq-exec-main">
-  <title>Main Functions</title>
+  <sect2 id="libpq-exec-main">
+   <title>Main Functions</title>
+
+   <para>
+    <variablelist>
+     <varlistentry>
+      <term>
+       <function>PQexec</function>
+       <indexterm>
+        <primary>PQexec</primary>
+       </indexterm>
+      </term>
+
+      <listitem>
+       <para>
+        Submits a command to the server and waits for the result.
+
+        <synopsis>
+         PGresult *PQexec(PGconn *conn, const char *command);
+        </synopsis>
+       </para>
+
+       <para>
+        Returns a <structname>PGresult</structname> pointer or possibly a null
+        pointer.  A non-null pointer will generally be returned except in
+        out-of-memory conditions or serious errors such as inability to send
+        the command to the server.  If a null pointer is returned, it should
+        be treated like a <symbol>PGRES_FATAL_ERROR</symbol> result.  Use
+        <function>PQerrorMessage</function> to get more information about such
+        errors.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+
+    It is allowed to include multiple SQL commands (separated by semicolons)
+    in the command string.  Multiple queries sent in a single
+    <function>PQexec</> call are processed in a single transaction, unless
+    there are explicit <command>BEGIN</command>/<command>COMMIT</command>
+    commands included in the query string to divide it into multiple
+    transactions.  Note however that the returned
+    <structname>PGresult</structname> structure describes only the result
+    of the last command executed from the string.  Should one of the
+    commands fail, processing of the string stops with it and the returned
+    <structname>PGresult</structname> describes the error condition.
+   </para>
+
+   <para>
+    <variablelist>
+     <varlistentry>
+      <term>
+       <function>PQexecParams</function>
+       <indexterm>
+        <primary>PQexecParams</primary>
+       </indexterm>
+      </term>
+
+      <listitem>
+       <para>
+        Submits a command to the server and waits for the result,
+        with the ability to pass parameters separately from the SQL
+        command text.
 
-<para>
-<variablelist>
-<varlistentry>
-<term><function>PQexec</function><indexterm><primary>PQexec</></></term>
-<listitem>
-<para>
-          Submits a command to the server
-          and waits for the result.
-<synopsis>
-PGresult *PQexec(PGconn *conn, const char *command);
-</synopsis>
-</para>
-
-<para>
-          Returns a <structname>PGresult</structname> pointer or possibly a null pointer.
-          A non-null pointer will generally be returned except in
-          out-of-memory conditions or serious errors such as inability
-          to send the command to the server.
-          If a null pointer is returned, it
-          should be treated like a <symbol>PGRES_FATAL_ERROR</symbol> result.
-          Use <function>PQerrorMessage</function> to get more information
-          about such errors.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-It is allowed to include multiple SQL commands (separated by semicolons) in
-the command string.  Multiple queries sent in a single <function>PQexec</>
-call are processed in a single transaction, unless there are explicit
-<command>BEGIN</command>/<command>COMMIT</command> commands included in the query string to divide it into multiple
-transactions.  Note however that the returned <structname>PGresult</structname>
-structure describes only the result of the last command executed from the
-string.  Should one of the commands fail, processing of the string stops with
-it and the returned <structname>PGresult</structname> describes the error
-condition.
-</para>
-
-<para>
-<variablelist>
-<varlistentry>
-<term><function>PQexecParams</function><indexterm><primary>PQexecParams</></></term>
-<listitem>
-<para>
-          Submits a command to the server and waits for the result,
-          with the ability to pass parameters separately from the SQL
-          command text.
 <synopsis>
 PGresult *PQexecParams(PGconn *conn,
                        const char *command,
@@ -1164,161 +1278,170 @@ PGresult *PQexecParams(PGconn *conn,
                        const int *paramFormats,
                        int resultFormat);
 </synopsis>
-</para>
-
-<para>
-<function>PQexecParams</> is like <function>PQexec</>, but offers additional
-functionality: parameter values can be specified separately from the command
-string proper, and query results can be requested in either text or binary
-format.  <function>PQexecParams</> is supported only in protocol 3.0 and later
-connections; it will fail when using protocol 2.0.
-</para>
-
-<para>
-The function arguments are:
-
-<variablelist>
-  <varlistentry>
-    <term><parameter>conn</parameter></term>
-    <listitem>
-      <para>
-       The connection object to send the command through.
-      </para>
-    </listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><parameter>command</parameter></term>
-    <listitem>
-      <para>
-       The SQL command string to be executed. If parameters are used, they are
-       referred to in the command string as <literal>$1</>, <literal>$2</>,
-       etc.
-      </para>
-    </listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><parameter>nParams</parameter></term>
-    <listitem>
-      <para>
-       The number of parameters supplied; it is the length of the arrays
-       <parameter>paramTypes[]</>, <parameter>paramValues[]</>,
-       <parameter>paramLengths[]</>, and <parameter>paramFormats[]</>. (The
-       array pointers can be <symbol>NULL</symbol> when <parameter>nParams</>
-       is zero.)
-      </para>
-    </listitem>
-  </varlistentry>
+       </para>
 
-  <varlistentry>
-    <term><parameter>paramTypes[]</parameter></term>
-    <listitem>
-      <para>
-       Specifies, by OID, the data types to be assigned to the parameter
-       symbols.  If <parameter>paramTypes</> is <symbol>NULL</symbol>, or any
-       particular element in the array is zero, the server infers a data type
-       for the parameter symbol in the same way it would do for an untyped
-       literal string.
-      </para>
-    </listitem>
-  </varlistentry>
+       <para>
+        <function>PQexecParams</> is like <function>PQexec</>, but offers additional
+        functionality: parameter values can be specified separately from the command
+        string proper, and query results can be requested in either text or binary
+        format.  <function>PQexecParams</> is supported only in protocol 3.0 and later
+        connections; it will fail when using protocol 2.0.
+       </para>
 
-  <varlistentry>
-    <term><parameter>paramValues[]</parameter></term>
-    <listitem>
-      <para>
-       Specifies the actual values of the parameters.
-       A null pointer in this array means the corresponding parameter is null;
-       otherwise the pointer points to a zero-terminated text string (for text
-       format) or binary data in the format expected by the server (for binary
-       format).
-      </para>
-    </listitem>
-  </varlistentry>
+       <para>
+        The function arguments are:
+
+        <variablelist>
+         <varlistentry>
+          <term><parameter>conn</parameter></term>
+
+          <listitem>
+           <para>
+            The connection object to send the command through.
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry>
+          <term><parameter>command</parameter></term>
+          <listitem>
+           <para>
+            The SQL command string to be executed. If parameters are used,
+            they are referred to in the command string as <literal>$1</>,
+            <literal>$2</>, etc.
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry>
+          <term><parameter>nParams</parameter></term>
+          <listitem>
+           <para>
+            The number of parameters supplied; it is the length of the arrays
+            <parameter>paramTypes[]</>, <parameter>paramValues[]</>,
+            <parameter>paramLengths[]</>, and <parameter>paramFormats[]</>. (The
+            array pointers can be <symbol>NULL</symbol> when <parameter>nParams</>
+            is zero.)
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry>
+          <term><parameter>paramTypes[]</parameter></term>
+          <listitem>
+           <para>
+            Specifies, by OID, the data types to be assigned to the
+            parameter symbols.  If <parameter>paramTypes</> is
+            <symbol>NULL</symbol>, or any particular element in the array
+            is zero, the server infers a data type for the parameter symbol
+            in the same way it would do for an untyped literal string.
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry>
+          <term><parameter>paramValues[]</parameter></term>
+          <listitem>
+           <para>
+            Specifies the actual values of the parameters.  A null pointer
+            in this array means the corresponding parameter is null;
+            otherwise the pointer points to a zero-terminated text string
+            (for text format) or binary data in the format expected by the
+            server (for binary format).
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry>
+          <term><parameter>paramLengths[]</parameter></term>
+          <listitem>
+           <para>
+            Specifies the actual data lengths of binary-format parameters.
+            It is ignored for null parameters and text-format parameters.
+            The array pointer can be null when there are no binary parameters.
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry>
+          <term><parameter>paramFormats[]</parameter></term>
+          <listitem>
+           <para>
+            Specifies whether parameters are text (put a zero in the
+            array entry for the corresponding parameter) or binary (put
+            a one in the array entry for the corresponding parameter).
+            If the array pointer is null then all parameters are presumed
+            to be text strings.
+           </para>
+          </listitem>
+         </varlistentry>
+
+         <varlistentry>
+          <term><parameter>resultFormat</parameter></term>
+          <listitem>
+           <para>
+            Specify zero to obtain results in text format, or one to obtain
+            results in binary format.  (There is not currently a provision
+            to obtain different result columns in different formats,
+            although that is possible in the underlying protocol.)
+           </para>
+          </listitem>
+         </varlistentry>
+        </variablelist>
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
 
-  <varlistentry>
-    <term><parameter>paramLengths[]</parameter></term>
-    <listitem>
-      <para>
-       Specifies the actual data lengths of binary-format parameters.
-       It is ignored for null parameters and text-format parameters.
-       The array pointer can be null when there are no binary parameters.
-      </para>
-    </listitem>
-  </varlistentry>
+   <para>
+    The primary advantage of <function>PQexecParams</> over
+    <function>PQexec</> is that parameter values can be separated from the
+    command string, thus avoiding the need for tedious and error-prone
+    quoting and escaping.
+   </para>
 
-  <varlistentry>
-    <term><parameter>paramFormats[]</parameter></term>
-    <listitem>
-      <para>
-       Specifies whether parameters are text (put a zero in the array entry for
-       the corresponding parameter) or binary (put a one in the array entry for
-       the corresponding parameter). If the array pointer is null then all
-       parameters are presumed to be text strings.
-      </para>
-    </listitem>
-  </varlistentry>
+   <para>
+    Unlike <function>PQexec</>, <function>PQexecParams</> allows at most
+    one SQL command in the given string.  (There can be semicolons in it,
+    but not more than one nonempty command.)  This is a limitation of the
+    underlying protocol, but has some usefulness as an extra defense against
+    SQL-injection attacks.
+   </para>
 
-  <varlistentry>
-    <term><parameter>resultFormat</parameter></term>
-    <listitem>
-      <para>
-       Specify zero to obtain results in text format, or one to obtain results
-       in binary format.  (There is not currently a provision to obtain
-       different result columns in different formats, although that is
-       possible in the underlying protocol.)
-      </para>
-    </listitem>
-  </varlistentry>
-</variablelist>
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-The primary advantage of <function>PQexecParams</> over <function>PQexec</>
-is that parameter values can be separated from the command string, thus
-avoiding the need for tedious and error-prone quoting and escaping.
-</para>
-
-<para>
-Unlike <function>PQexec</>, <function>PQexecParams</> allows at most one SQL
-command in the given string.  (There can be semicolons in it, but not more
-than one nonempty command.)  This is a limitation of the underlying protocol,
-but has some usefulness as an extra defense against SQL-injection attacks.
-</para>
-
-<tip>
-<para>
-Specifying parameter types via OIDs is tedious, particularly if you prefer
-not to hard-wire particular OID values into your program.  However, you can
-avoid doing so even in cases where the server by itself cannot determine the
-type of the parameter, or chooses a different type than you want.  In the
-SQL command text, attach an explicit cast to the parameter symbol to show what
-data type you will send.  For example:
+   <tip>
+    <para>
+     Specifying parameter types via OIDs is tedious, particularly if you prefer
+     not to hard-wire particular OID values into your program.  However, you can
+     avoid doing so even in cases where the server by itself cannot determine the
+     type of the parameter, or chooses a different type than you want.  In the
+     SQL command text, attach an explicit cast to the parameter symbol to show what
+     data type you will send.  For example:
 <programlisting>
-select * from mytable where x = $1::bigint;
+SELECT * FROM mytable WHERE x = $1::bigint;
 </programlisting>
-This forces parameter <literal>$1</> to be treated as <type>bigint</>, whereas
-by default it would be assigned the same type as <literal>x</>.  Forcing the
-parameter type decision, either this way or by specifying a numeric type OID,
-is strongly recommended when sending parameter values in binary format, because
-binary format has less redundancy than text format and so there is less chance
-that the server will detect a type mismatch mistake for you.
-</para>
-</tip>
-
-<para>
-<variablelist>
-<varlistentry>
-<term><function>PQprepare</function><indexterm><primary>PQprepare</></></term>
-<listitem>
-<para>
-          Submits a request to create a prepared statement with the
-          given parameters, and waits for completion.
+     This forces parameter <literal>$1</> to be treated as <type>bigint</>, whereas
+     by default it would be assigned the same type as <literal>x</>.  Forcing the
+     parameter type decision, either this way or by specifying a numeric type OID,
+     is strongly recommended when sending parameter values in binary format, because
+     binary format has less redundancy than text format and so there is less chance
+     that the server will detect a type mismatch mistake for you.
+    </para>
+   </tip>
+
+   <para>
+    <variablelist>
+     <varlistentry>
+      <term><function>PQprepare</function>
+       <indexterm>
+        <primary>PQprepare</primary>
+       </indexterm>
+      </term>
+
+      <listitem>
+       <para>
+        Submits a request to create a prepared statement with the
+        given parameters, and waits for completion.
 <synopsis>
 PGresult *PQprepare(PGconn *conn,
                     const char *stmtName,
@@ -1326,70 +1449,77 @@ PGresult *PQprepare(PGconn *conn,
                     int nParams,
                     const Oid *paramTypes);
 </synopsis>
-</para>
-
-<para>
-<function>PQprepare</> creates a prepared statement for later execution with
-<function>PQexecPrepared</>.
-This feature allows commands
-that will be used repeatedly to be parsed and planned just once, rather
-than each time they are executed.
-<function>PQprepare</> is supported only in protocol 3.0 and later
-connections; it will fail when using protocol 2.0.
-</para>
-
-<para>
-The function creates a prepared statement named <parameter>stmtName</>
-from the <parameter>query</> string, which must contain a single SQL command.
-<parameter>stmtName</> can be <literal>""</> to create an unnamed statement,
-in which case any pre-existing unnamed statement is automatically replaced;
-otherwise it is an error if the statement name is already defined in the
-current session.
-If any parameters are used, they are referred
-to in the query as <literal>$1</>, <literal>$2</>, etc.
-<parameter>nParams</> is the number of parameters for which types are
-pre-specified in the array <parameter>paramTypes[]</>.  (The array pointer
-can be <symbol>NULL</symbol> when <parameter>nParams</> is zero.)
-<parameter>paramTypes[]</> specifies, by OID, the data types to be assigned to
-the parameter symbols.  If <parameter>paramTypes</> is <symbol>NULL</symbol>,
-or any particular element in the array is zero, the server assigns a data type
-to the parameter symbol in the same way it would do for an untyped literal
-string.  Also, the query can use parameter symbols with numbers higher than
-<parameter>nParams</>; data types will be inferred for these symbols as
-well.  (See <function>PQdescribePrepared</function> for a means to find out
-what data types were inferred.)
-</para>
-
-<para>
-As with <function>PQexec</>, the result is normally a
-<structname>PGresult</structname> object whose contents indicate server-side
-success or failure.  A null result indicates out-of-memory or inability to
-send the command at all.
-Use <function>PQerrorMessage</function> to get more information
-about such errors.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-Prepared statements for use with <function>PQexecPrepared</> can also
-be created by executing SQL <xref linkend="sql-prepare"
-endterm="sql-prepare-title"> statements.  (But <function>PQprepare</>
-is more flexible since it does not require parameter types to be
-pre-specified.)  Also, although there is no <application>libpq</>
-function for deleting a prepared statement, the SQL <xref
-linkend="sql-deallocate" endterm="sql-deallocate-title"> statement can
-be used for that purpose.
-</para>
-
-<para>
-<variablelist>
-<varlistentry>
-<term><function>PQexecPrepared</function><indexterm><primary>PQexecPrepared</></></term>
-<listitem>
-<para>
-          Sends a request to execute a prepared statement with given
-          parameters, and waits for the result.
+       </para>
+
+       <para>
+        <function>PQprepare</> creates a prepared statement for later
+        execution with <function>PQexecPrepared</>.  This feature allows
+        commands that will be used repeatedly to be parsed and planned just
+        once, rather than each time they are executed.
+        <function>PQprepare</> is supported only in protocol 3.0 and later
+        connections; it will fail when using protocol 2.0.
+       </para>
+
+        <para>
+         The function creates a prepared statement named
+         <parameter>stmtName</> from the <parameter>query</> string, which
+         must contain a single SQL command.  <parameter>stmtName</> can be
+         <literal>""</> to create an unnamed statement, in which case any
+         pre-existing unnamed statement is automatically replaced; otherwise
+         it is an error if the statement name is already defined in the
+         current session.  If any parameters are used, they are referred
+         to in the query as <literal>$1</>, <literal>$2</>, etc.
+         <parameter>nParams</> is the number of parameters for which types
+         are pre-specified in the array <parameter>paramTypes[]</>.  (The
+         array pointer can be <symbol>NULL</symbol> when
+         <parameter>nParams</> is zero.) <parameter>paramTypes[]</>
+         specifies, by OID, the data types to be assigned to the parameter
+         symbols.  If <parameter>paramTypes</> is <symbol>NULL</symbol>,
+         or any particular element in the array is zero, the server assigns
+         a data type to the parameter symbol in the same way it would do
+         for an untyped literal string.  Also, the query can use parameter
+         symbols with numbers higher than <parameter>nParams</>; data types
+         will be inferred for these symbols as well.  (See
+         <function>PQdescribePrepared</function> for a means to find out
+         what data types were inferred.)
+        </para>
+        
+        <para>
+         As with <function>PQexec</>, the result is normally a
+         <structname>PGresult</structname> object whose contents indicate
+         server-side success or failure.  A null result indicates
+         out-of-memory or inability to send the command at all.  Use
+         <function>PQerrorMessage</function> to get more information about
+         such errors.
+        </para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+
+     Prepared statements for use with <function>PQexecPrepared</> can also
+     be created by executing SQL <xref linkend="sql-prepare"
+     endterm="sql-prepare-title"> statements.  (But <function>PQprepare</>
+     is more flexible since it does not require parameter types to be
+     pre-specified.)  Also, although there is no <application>libpq</>
+     function for deleting a prepared statement, the SQL <xref
+     linkend="sql-deallocate" endterm="sql-deallocate-title"> statement
+     can be used for that purpose.
+    </para>
+
+    <para>
+     <variablelist>
+      <varlistentry>
+       <term>
+        <function>PQexecPrepared</function>
+        <indexterm>
+         <primary>PQexecPrepared</primary>
+        </indexterm>
+       </term>
+
+       <listitem>
+        <para>
+         Sends a request to execute a prepared statement with given
+         parameters, and waits for the result.
 <synopsis>
 PGresult *PQexecPrepared(PGconn *conn,
                          const char *stmtName,
@@ -1399,563 +1529,653 @@ PGresult *PQexecPrepared(PGconn *conn,
                          const int *paramFormats,
                          int resultFormat);
 </synopsis>
-</para>
-
-<para>
-<function>PQexecPrepared</> is like <function>PQexecParams</>, but the
-command to be executed is specified by naming a previously-prepared
-statement, instead of giving a query string.
-This feature allows commands
-that will be used repeatedly to be parsed and planned just once, rather
-than each time they are executed.
-The statement must have been prepared previously in the current session.
-<function>PQexecPrepared</> is supported only in protocol 3.0 and later
-connections; it will fail when using protocol 2.0.
-</para>
-
-<para>
-The parameters are identical to <function>PQexecParams</>, except that the
-name of a prepared statement is given instead of a query string, and the
-<parameter>paramTypes[]</> parameter is not present (it is not needed since
-the prepared statement's parameter types were determined when it was created).
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQdescribePrepared</function><indexterm><primary>PQdescribePrepared</></></term>
-<listitem>
-<para>
-          Submits a request to obtain information about the specified
-          prepared statement, and waits for completion.
+        </para>
+
+        <para>
+         <function>PQexecPrepared</> is like <function>PQexecParams</>,
+         but the command to be executed is specified by naming a
+         previously-prepared statement, instead of giving a query string.
+         This feature allows commands that will be used repeatedly to be
+         parsed and planned just once, rather than each time they are
+         executed.  The statement must have been prepared previously in
+         the current session.  <function>PQexecPrepared</> is supported
+         only in protocol 3.0 and later connections; it will fail when
+         using protocol 2.0.
+        </para>
+
+        <para>
+         The parameters are identical to <function>PQexecParams</>, except that the
+         name of a prepared statement is given instead of a query string, and the
+         <parameter>paramTypes[]</> parameter is not present (it is not needed since
+         the prepared statement's parameter types were determined when it was created).
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+        <function>PQdescribePrepared</function>
+        <indexterm>
+         <primary>PQdescribePrepared</primary>
+        </indexterm>
+       </term>
+
+       <listitem>
+        <para>
+         Submits a request to obtain information about the specified
+         prepared statement, and waits for completion.
 <synopsis>
 PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
 </synopsis>
-</para>
-
-<para>
-<function>PQdescribePrepared</> allows an application to obtain information
-about a previously prepared statement.
-<function>PQdescribePrepared</> is supported only in protocol 3.0 and later
-connections; it will fail when using protocol 2.0.
-</para>
-
-<para>
-<parameter>stmtName</> can be <literal>""</> or NULL to reference the unnamed
-statement, otherwise it must be the name of an existing prepared statement.
-On success, a <structname>PGresult</> with status
-<literal>PGRES_COMMAND_OK</literal> is returned.  The functions
-<function>PQnparams</function> and <function>PQparamtype</function>
-can be applied to this <structname>PGresult</> to obtain information
-about the parameters of the prepared statement, and the functions
-<function>PQnfields</function>, <function>PQfname</function>,
-<function>PQftype</function>, etc provide information about the result
-columns (if any) of the statement.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQdescribePortal</function><indexterm><primary>PQdescribePortal</></></term>
-<listitem>
-<para>
-          Submits a request to obtain information about the specified
-          portal, and waits for completion.
+        </para>
+
+        <para>
+         <function>PQdescribePrepared</> allows an application to obtain
+         information about a previously prepared statement.
+         <function>PQdescribePrepared</> is supported only in protocol 3.0
+         and later connections; it will fail when using protocol 2.0.
+        </para>
+
+        <para>
+         <parameter>stmtName</> can be <literal>""</> or NULL to reference
+         the unnamed statement, otherwise it must be the name of an existing
+         prepared statement.  On success, a <structname>PGresult</> with
+         status <literal>PGRES_COMMAND_OK</literal> is returned.  The
+         functions <function>PQnparams</function> and
+         <function>PQparamtype</function> can be applied to this
+         <structname>PGresult</> to obtain information about the parameters
+         of the prepared statement, and the functions
+         <function>PQnfields</function>, <function>PQfname</function>,
+         <function>PQftype</function>, etc provide information about the
+         result columns (if any) of the statement.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+        <function>PQdescribePortal</function>
+        <indexterm>
+         <primary>PQdescribePortal</primary>
+        </indexterm>
+       </term>
+
+       <listitem>
+        <para>
+         Submits a request to obtain information about the specified
+         portal, and waits for completion.
 <synopsis>
 PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
 </synopsis>
-</para>
-
-<para>
-<function>PQdescribePortal</> allows an application to obtain information
-about a previously created portal.  (<application>libpq</> does not provide
-any direct access to portals, but you can use this function to inspect the
-properties of a cursor created with a <command>DECLARE CURSOR</> SQL command.)
-<function>PQdescribePortal</> is supported only in protocol 3.0 and later
-connections; it will fail when using protocol 2.0.
-</para>
-
-<para>
-<parameter>portalName</> can be <literal>""</> or NULL to reference the unnamed
-portal, otherwise it must be the name of an existing portal.
-On success, a <structname>PGresult</> with status
-<literal>PGRES_COMMAND_OK</literal> is returned.  The functions
-<function>PQnfields</function>, <function>PQfname</function>,
-<function>PQftype</function>, etc can be applied to the
-<structname>PGresult</> to obtain information about the result
-columns (if any) of the portal.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-The
-<structname>PGresult</structname><indexterm><primary>PGresult</></>
-structure encapsulates the result returned by the server.
-<application>libpq</application> application programmers should be
-careful to maintain the <structname>PGresult</structname> abstraction.
-Use the accessor functions below to get at the contents of
-<structname>PGresult</structname>.  Avoid directly referencing the
-fields of the <structname>PGresult</structname> structure because they
-are subject to change in the future.
-
-<variablelist>
-<varlistentry>
-<term><function>PQresultStatus</function><indexterm><primary>PQresultStatus</></></term>
-<listitem>
-<para>
-          Returns the result status of the command.
-<synopsis>
-ExecStatusType PQresultStatus(const PGresult *res);
-</synopsis>
-</para>
-
-<para>
-<function>PQresultStatus</function> can return one of the following values:
-
-<variablelist>
- <varlistentry>
-  <term><literal>PGRES_EMPTY_QUERY</literal></term>
-  <listitem>
-   <para>The string sent to the server was empty.</para>
-  </listitem>
- </varlistentry>
+        </para>
+
+        <para>
+         <function>PQdescribePortal</> allows an application to obtain
+         information about a previously created portal.
+         (<application>libpq</> does not provide any direct access to
+         portals, but you can use this function to inspect the properties
+         of a cursor created with a <command>DECLARE CURSOR</> SQL command.)
+         <function>PQdescribePortal</> is supported only in protocol 3.0
+         and later connections; it will fail when using protocol 2.0.
+        </para>
+
+        <para>
+         <parameter>portalName</> can be <literal>""</> or NULL to reference
+         the unnamed portal, otherwise it must be the name of an existing
+         portal.  On success, a <structname>PGresult</> with status
+         <literal>PGRES_COMMAND_OK</literal> is returned.  The functions
+         <function>PQnfields</function>, <function>PQfname</function>,
+         <function>PQftype</function>, etc can be applied to the
+         <structname>PGresult</> to obtain information about the result
+         columns (if any) of the portal.
+        </para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+    </para>
 
- <varlistentry>
-  <term><literal>PGRES_COMMAND_OK</literal></term>
-  <listitem>
-   <para>Successful completion of a command returning no data.</para>
-  </listitem>
- </varlistentry>
+    <para>
+     The <structname>PGresult</structname><indexterm><primary>PGresult</></>
+     structure encapsulates the result returned by the server.
+     <application>libpq</application> application programmers should be
+     careful to maintain the <structname>PGresult</structname> abstraction.
+     Use the accessor functions below to get at the contents of
+     <structname>PGresult</structname>.  Avoid directly referencing the
+     fields of the <structname>PGresult</structname> structure because they
+     are subject to change in the future.
+
+     <variablelist>
+      <varlistentry>
+       <term>
+        <function>PQresultStatus</function>
+        <indexterm>
+         <primary>PQresultStatus</primary>
+        </indexterm>
+       </term>
+
+       <listitem>
+        <para>
+         Returns the result status of the command.
+         <synopsis>
+          ExecStatusType PQresultStatus(const PGresult *res);
+         </synopsis>
+        </para>
+
+        <para>
+         <function>PQresultStatus</function> can return one of the following values:
+
+         <variablelist>
+          <varlistentry>
+           <term><literal>PGRES_EMPTY_QUERY</literal></term>
+           <listitem>
+            <para>
+             The string sent to the server was empty.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><literal>PGRES_COMMAND_OK</literal></term>
+           <listitem>
+            <para>
+             Successful completion of a command returning no data.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><literal>PGRES_TUPLES_OK</literal></term>
+           <listitem>
+            <para>
+             Successful completion of a command returning data (such as
+             a <command>SELECT</> or <command>SHOW</>).
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><literal>PGRES_COPY_OUT</literal></term>
+           <listitem>
+            <para>
+             Copy Out (from server) data transfer started.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><literal>PGRES_COPY_IN</literal></term>
+           <listitem>
+            <para>
+             Copy In (to server) data transfer started.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><literal>PGRES_BAD_RESPONSE</literal></term>
+           <listitem>
+            <para>
+             The server's response was not understood.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><literal>PGRES_NONFATAL_ERROR</literal></term>
+           <listitem>
+            <para>
+             A nonfatal error (a notice or warning) occurred.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><literal>PGRES_FATAL_ERROR</literal></term>
+           <listitem>
+            <para>
+             A fatal error occurred.
+            </para>
+           </listitem>
+          </varlistentry>
+         </variablelist>
+         
+         If the result status is <literal>PGRES_TUPLES_OK</literal>, then
+         the functions described below can be used to retrieve the rows
+         returned by the query.  Note that a <command>SELECT</command>
+         command that happens to retrieve zero rows still shows
+         <literal>PGRES_TUPLES_OK</literal>.
+         <literal>PGRES_COMMAND_OK</literal> is for commands that can never
+         return rows (<command>INSERT</command>, <command>UPDATE</command>,
+         etc.). A response of <literal>PGRES_EMPTY_QUERY</literal> might
+         indicate a bug in the client software.
+        </para>
+         
+        <para>
+         A result of status <symbol>PGRES_NONFATAL_ERROR</symbol> will
+         never be returned directly by <function>PQexec</function> or other
+         query execution functions; results of this kind are instead passed
+         to the notice processor (see <xref
+         linkend="libpq-notice-processing">).
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+        <function>PQresStatus</function>
+        <indexterm>
+         <primary>PQresStatus</primary>
+        </indexterm>
+       </term>
+
+       <listitem>
+        <para>
+         Converts the enumerated type returned by
+         <function>PQresultStatus</> into a string constant describing the
+         status code. The caller should not free the result.
+
+         <synopsis>
+          char *PQresStatus(ExecStatusType status);
+         </synopsis>
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+        <function>PQresultErrorMessage</function>
+        <indexterm>
+         <primary>PQresultErrorMessage</primary>
+        </indexterm>
+       </term>
+
+       <listitem>
+        <para>
+         Returns the error message associated with the command, or an empty string
+         if there was no error.
+         <synopsis>
+          char *PQresultErrorMessage(const PGresult *res);
+         </synopsis>
+         If there was an error, the returned string will include a trailing
+         newline.  The caller should not free the result directly. It will
+         be freed when the associated <structname>PGresult</> handle is
+         passed to <function>PQclear</function>.
+        </para>
+
+        <para>
+         Immediately following a <function>PQexec</function> or
+         <function>PQgetResult</function> call,
+         <function>PQerrorMessage</function> (on the connection) will return
+         the same string as <function>PQresultErrorMessage</function> (on
+         the result).  However, a <structname>PGresult</structname> will
+         retain its error message until destroyed, whereas the connection's
+         error message will change when subsequent operations are done.
+         Use <function>PQresultErrorMessage</function> when you want to
+         know the status associated with a particular
+         <structname>PGresult</structname>; use
+         <function>PQerrorMessage</function> when you want to know the
+         status from the latest operation on the connection.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><function>PQresultErrorField</function><indexterm><primary>PQresultErrorField</></></term>
+       <listitem>
+        <para>
+         Returns an individual field of an error report.
+         <synopsis>
+          char *PQresultErrorField(const PGresult *res, int fieldcode);
+         </synopsis>
+         <parameter>fieldcode</> is an error field identifier; see the symbols
+         listed below.  <symbol>NULL</symbol> is returned if the
+         <structname>PGresult</structname> is not an error or warning result,
+         or does not include the specified field.  Field values will normally
+         not include a trailing newline. The caller should not free the 
+         result directly. It will be freed when the
+         associated <structname>PGresult</> handle is passed to
+         <function>PQclear</function>.
+        </para>
+         
+        <para>
+         The following field codes are available:
+         <variablelist>
+          <varlistentry>
+           <term><symbol>PG_DIAG_SEVERITY</></term>
+           <listitem>
+            <para>
+             The severity; the field contents are <literal>ERROR</>,
+             <literal>FATAL</>, or <literal>PANIC</> (in an error message),
+             or <literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>,
+             <literal>INFO</>, or <literal>LOG</> (in a notice message), or
+             a localized translation of one of these.  Always present.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <indexterm>
+            <primary>error codes</primary>
+            <secondary>libpq</secondary>
+           </indexterm>
+           <term><symbol>PG_DIAG_SQLSTATE</></term>
+           <listitem>
+            <para>
+             The SQLSTATE code for the error. The SQLSTATE code identifies
+             the type of error that has occurred; it can be used by
+             front-end applications to perform specific operations (such
+             as error handling) in response to a particular database error.
+             For a list of the possible SQLSTATE codes, see <xref
+             linkend="errcodes-appendix">. This field is not localizable,
+             and is always present.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><symbol>PG_DIAG_MESSAGE_PRIMARY</></term>
+           <listitem>
+            <para>
+             The primary human-readable error message (typically one line).
+             Always present.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><symbol>PG_DIAG_MESSAGE_DETAIL</></term>
+           <listitem>
+            <para>
+             Detail: an optional secondary error message carrying more
+             detail about the problem.  Might run to multiple lines.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><symbol>PG_DIAG_MESSAGE_HINT</></term>
+           <listitem>
+            <para>
+             Hint: an optional suggestion what to do about the problem.
+             This is intended to differ from detail in that it offers advice
+             (potentially inappropriate) rather than hard facts.  Might
+             run to multiple lines.
+            </para>
+           </listitem>
+          </varlistentry>
+         
+          <varlistentry>
+           <term><symbol>PG_DIAG_STATEMENT_POSITION</></term>
+           <listitem>
+           <para>
+            A string containing a decimal integer indicating an error cursor
+            position as an index into the original statement string.  The
+            first character has index 1, and positions are measured in
+            characters not bytes.
+           </para>
+          </listitem>
+         </varlistentry>
+         
+         <varlistentry>
+          <term><symbol>PG_DIAG_INTERNAL_POSITION</></term>
+          <listitem>
+           <para>
+            This is defined the same as the
+            <symbol>PG_DIAG_STATEMENT_POSITION</> field, but it is used
+            when the cursor position refers to an internally generated
+            command rather than the one submitted by the client.  The
+            <symbol>PG_DIAG_INTERNAL_QUERY</> field will always appear when
+            this field appears.
+           </para>
+          </listitem>
+         </varlistentry>
+         
+         <varlistentry>
+          <term><symbol>PG_DIAG_INTERNAL_QUERY</></term>
+          <listitem>
+           <para>
+            The text of a failed internally-generated command.  This could
+            be, for example, a SQL query issued by a PL/pgSQL function.
+           </para>
+          </listitem>
+         </varlistentry>
+         
+         <varlistentry>
+          <term><symbol>PG_DIAG_CONTEXT</></term>
+          <listitem>
+           <para>
+            An indication of the context in which the error occurred.
+            Presently this includes a call stack traceback of active
+            procedural language functions and internally-generated queries.
+            The trace is one entry per line, most recent first.
+           </para>
+          </listitem>
+         </varlistentry>
+         
+         <varlistentry>
+          <term><symbol>PG_DIAG_SOURCE_FILE</></term>
+          <listitem>
+           <para>
+            The file name of the source-code location where the error was
+            reported.
+           </para>
+          </listitem>
+         </varlistentry>
+         
+         <varlistentry>
+          <term><symbol>PG_DIAG_SOURCE_LINE</></term>
+          <listitem>
+           <para>
+            The line number of the source-code location where the error
+            was reported.
+           </para>
+          </listitem>
+         </varlistentry>
+         
+         <varlistentry>
+          <term><symbol>PG_DIAG_SOURCE_FUNCTION</></term>
+          <listitem>
+           <para>
+            The name of the source-code function reporting the error.
+           </para>
+          </listitem>
+         </varlistentry>
+        </variablelist>
+       </para>
+         
+       <para>
+        The client is responsible for formatting displayed information to meet
+        its needs; in particular it should break long lines as needed.
+        Newline characters appearing in the error message fields should be
+        treated as paragraph breaks, not line breaks.
+       </para>
+         
+       <para>
+        Errors generated internally by <application>libpq</application> will
+        have severity and primary message, but typically no other fields.
+        Errors returned by a pre-3.0-protocol server will include severity and
+        primary message, and sometimes a detail message, but no other fields.
+       </para>
+         
+       <para>
+        Note that error fields are only available from
+        <structname>PGresult</structname> objects, not
+        <structname>PGconn</structname> objects; there is no
+        <function>PQerrorField</function> function.
+       </para>
+      </listitem>
+     </varlistentry>
+         
+     <varlistentry>
+      <term><function>PQclear</function><indexterm><primary>PQclear</></></term>
+      <listitem>
+       <para>
+        Frees  the  storage  associated with a
+        <structname>PGresult</structname>.  Every command result should be
+        freed via <function>PQclear</function> when it  is  no  longer
+        needed.
+
+        <synopsis>
+         void PQclear(PGresult *res);
+        </synopsis>
+       </para>
+         
+       <para>
+        You can keep a <structname>PGresult</structname> object around for
+        as long as you need it; it does not go away when you issue a new
+        command, nor even if you close the connection.  To get rid of it,
+        you must call <function>PQclear</function>.  Failure to do this
+        will result in memory leaks in your application.
+       </para>
+      </listitem>
+     </varlistentry>
+         
+     <varlistentry>
+      <term>
+       <function>PQmakeEmptyPGresult</function>
+       <indexterm>
+        <primary>PQmakeEmptyPGresult</primary>
+       </indexterm>
+      </term>
 
- <varlistentry>
-  <term><literal>PGRES_TUPLES_OK</literal></term>
-  <listitem>
-   <para>Successful completion of a command returning data (such as
-   a <command>SELECT</> or <command>SHOW</>).</para>
-  </listitem>
- </varlistentry>
+      <listitem>
+       <para>
+        Constructs an empty <structname>PGresult</structname> object with the given status.
+        <synopsis>
+         PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
+        </synopsis>
+       </para>
+         
+       <para>
+        This is <application>libpq</>'s internal function to allocate and
+        initialize an empty <structname>PGresult</structname> object.  This
+        function returns NULL if memory could not be allocated. It is
+        exported because some applications find it useful to generate result
+        objects (particularly objects with error status) themselves.  If
+        <parameter>conn</parameter> is not null and <parameter>status</>
+        indicates an error, the current error message of the specified
+        connection is copied into the <structname>PGresult</structname>.
+        Note that <function>PQclear</function> should eventually be called
+        on the object, just as with a <structname>PGresult</structname>
+        returned by <application>libpq</application> itself.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+  </sect2>
+         
+  <sect2 id="libpq-exec-select-info">
+   <title>Retrieving Query Result Information</title>
+        
+   <para>
+    These functions are used to extract information from a
+    <structname>PGresult</structname> object that represents a successful
+    query result (that is, one that has status
+    <literal>PGRES_TUPLES_OK</literal>).  They can also be used to extract
+    information from a successful Describe operation: a Describe's result
+    has all the same column information that actual execution of the query
+    would provide, but it has zero rows.  For objects with other status values,
+    these functions will act as though the result has zero rows and zero columns.
+   </para>
+        
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQntuples</function>
+      <indexterm>
+       <primary>PQntuples</primary>
+      </indexterm>
+     </term>
 
- <varlistentry>
-  <term><literal>PGRES_COPY_OUT</literal></term>
-  <listitem>
-   <para>Copy Out (from server) data transfer started.</para>
-  </listitem>
- </varlistentry>
+     <listitem>
+      <para>
+       Returns the number of rows (tuples) in the query result.
 
- <varlistentry>
-  <term><literal>PGRES_COPY_IN</literal></term>
-  <listitem>
-   <para>Copy In (to server) data transfer started.</para>
-  </listitem>
- </varlistentry>
+       <synopsis>
+        int PQntuples(const PGresult *res);
+       </synopsis>
 
- <varlistentry>
-  <term><literal>PGRES_BAD_RESPONSE</literal></term>
-  <listitem>
-   <para>The server's response was not understood.</para>
-  </listitem>
- </varlistentry>
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQnfields</function>
+      <indexterm>
+       <primary>PQnfields</primary>
+      </indexterm>
+     </term>
 
- <varlistentry>
-  <term><literal>PGRES_NONFATAL_ERROR</literal></term>
-  <listitem>
-   <para>A nonfatal error (a notice or warning) occurred.</para>
-  </listitem>
- </varlistentry>
+     <listitem>
+      <para>
+       Returns the number of columns (fields) in each row of the query
+       result.
 
- <varlistentry>
-  <term><literal>PGRES_FATAL_ERROR</literal></term>
-  <listitem>
-   <para>A fatal error occurred.</para>
-  </listitem>
- </varlistentry>
-</variablelist>
-
-If the result status is <literal>PGRES_TUPLES_OK</literal>, then the
-functions described below can be used to retrieve the rows returned by
-the query.  Note that a <command>SELECT</command> command that happens
-to retrieve zero rows still shows <literal>PGRES_TUPLES_OK</literal>.
-<literal>PGRES_COMMAND_OK</literal> is for commands that can never
-return rows (<command>INSERT</command>, <command>UPDATE</command>,
-etc.). A response of <literal>PGRES_EMPTY_QUERY</literal> might indicate
-a bug in the client software.
-</para>
-
-<para>
-A result of status <symbol>PGRES_NONFATAL_ERROR</symbol> will never be
-returned directly by <function>PQexec</function> or other query
-execution functions; results of this kind are instead passed to the notice
-processor (see <xref linkend="libpq-notice-processing">).
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQresStatus</function><indexterm><primary>PQresStatus</></></term>
-<listitem>
-<para>
-        Converts the enumerated type returned by <function>PQresultStatus</> into
-        a string constant describing the status code. The caller should not 
-        free the result.
-<synopsis>
-char *PQresStatus(ExecStatusType status);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQresultErrorMessage</function><indexterm><primary>PQresultErrorMessage</></></term>
-<listitem>
-<para>
-Returns the error message associated with the command, or an empty string
-if there was no error.
-<synopsis>
-char *PQresultErrorMessage(const PGresult *res);
-</synopsis>
-If there was an error, the returned string will include a trailing newline. 
-The caller should not free the result directly. It will be freed when the 
-associated <structname>PGresult</> handle is passed to 
-<function>PQclear</function>.
-</para>
-
-<para>
-Immediately following a <function>PQexec</function> or <function>PQgetResult</function>
-call, <function>PQerrorMessage</function> (on the connection) will return the same
-string as <function>PQresultErrorMessage</function> (on the result).  However, a
-<structname>PGresult</structname> will retain its error message
-until destroyed, whereas the connection's error message will change when
-subsequent operations are done.  Use <function>PQresultErrorMessage</function> when you want to
-know the status associated with a particular <structname>PGresult</structname>; use <function>PQerrorMessage</function>
-when you want to know the status from the latest operation on the connection.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQresultErrorField</function><indexterm><primary>PQresultErrorField</></></term>
-<listitem>
-<para>
-Returns an individual field of an error report.
-<synopsis>
-char *PQresultErrorField(const PGresult *res, int fieldcode);
-</synopsis>
-<parameter>fieldcode</> is an error field identifier; see the symbols
-listed below.  <symbol>NULL</symbol> is returned if the
-<structname>PGresult</structname> is not an error or warning result,
-or does not include the specified field.  Field values will normally
-not include a trailing newline. The caller should not free the 
-result directly. It will be freed when the
-associated <structname>PGresult</> handle is passed to
-<function>PQclear</function>.
-</para>
-
-<para>
-The following field codes are available:
-<variablelist>
-
-<varlistentry>
-<term><symbol>PG_DIAG_SEVERITY</></term>
-<listitem>
-<para>
-The severity; the field contents are <literal>ERROR</>,
-<literal>FATAL</>, or <literal>PANIC</> (in an error message), or
-<literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>,
-<literal>INFO</>, or <literal>LOG</> (in a notice message), or a
-localized translation of one of these.  Always present.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
- <indexterm>
-  <primary>error codes</primary>
-  <secondary>libpq</secondary>
- </indexterm>
-<term><symbol>PG_DIAG_SQLSTATE</>
-</term>
-<listitem>
-<para>
-The SQLSTATE code for the error. The SQLSTATE code identifies the type
-of error that has occurred; it can be used by front-end applications
-to perform specific operations (such as error handling) in response to
-a particular database error. For a list of the possible SQLSTATE
-codes, see <xref linkend="errcodes-appendix">. This field is not
-localizable, and is always present.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_MESSAGE_PRIMARY</></term>
-<listitem>
-<para>
-The primary human-readable error message (typically one line).  Always
-present.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_MESSAGE_DETAIL</></term>
-<listitem>
-<para>
-Detail: an optional secondary error message carrying more detail about
-the problem.  Might run to multiple lines.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_MESSAGE_HINT</></term>
-<listitem>
-<para>
-Hint: an optional suggestion what to do about the problem.  This is
-intended to differ from detail in that it offers advice (potentially
-inappropriate) rather than hard facts.  Might run to multiple lines.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_STATEMENT_POSITION</></term>
-<listitem>
-<para>
-A string containing a decimal integer indicating an error cursor
-position as an index into the original statement string.  The first
-character has index 1, and positions are measured in characters not
-bytes.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_INTERNAL_POSITION</></term>
-<listitem>
-<para>
-This is defined the same as the <symbol>PG_DIAG_STATEMENT_POSITION</>
-field, but it is used when the cursor position refers to an internally
-generated command rather than the one submitted by the client.
-The <symbol>PG_DIAG_INTERNAL_QUERY</> field will always appear when this field
-appears.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_INTERNAL_QUERY</></term>
-<listitem>
-<para>
-The text of a failed internally-generated command.
-This could be, for example, a SQL query issued by a PL/pgSQL function.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_CONTEXT</></term>
-<listitem>
-<para>
-An indication of the context in which the error occurred.
-Presently this includes a call stack traceback of active
-procedural language functions and internally-generated queries.
-The trace is one entry per line, most recent first.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_SOURCE_FILE</></term>
-<listitem>
-<para>
-The file name of the source-code location where the error was
-reported.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_SOURCE_LINE</></term>
-<listitem>
-<para>
-The line number of the source-code location where the error was
-reported.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><symbol>PG_DIAG_SOURCE_FUNCTION</></term>
-<listitem>
-<para>
-The name of the source-code function reporting the error.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-The client is responsible for formatting displayed information to meet
-its needs; in particular it should break long lines as needed.
-Newline characters appearing in the error message fields should be
-treated as paragraph breaks, not line breaks.
-</para>
-
-<para>
-Errors generated internally by <application>libpq</application> will
-have severity and primary message, but typically no other fields.
-Errors returned by a pre-3.0-protocol server will include severity and
-primary message, and sometimes a detail message, but no other fields.
-</para>
-
-<para>
-Note that error fields are only available from
-<structname>PGresult</structname> objects, not
-<structname>PGconn</structname> objects; there is no
-<function>PQerrorField</function> function.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQclear</function><indexterm><primary>PQclear</></></term>
-<listitem>
-<para>
-          Frees  the  storage  associated with a <structname>PGresult</structname>.
-          Every command result should be freed via <function>PQclear</function> when
-          it  is  no  longer needed.
-<synopsis>
-void PQclear(PGresult *res);
-</synopsis>
-</para>
-
-<para>
-          You can keep a <structname>PGresult</structname> object around for as long as you
-          need it; it does not go away when you issue a new command,
-          nor even if you close the connection.  To get rid of it,
-          you must call <function>PQclear</function>.  Failure to do this will
-          result in memory leaks in your application.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQmakeEmptyPGresult</function><indexterm><primary>PQmakeEmptyPGresult</></></term>
-<listitem>
-<para>
-          Constructs an empty <structname>PGresult</structname> object with the given status.
-<synopsis>
-PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
-</synopsis>
-</para>
-
-<para>
-This is <application>libpq</>'s internal function to allocate and
-initialize an empty <structname>PGresult</structname> object.  This
-function returns NULL if memory could not be allocated. It is exported
-because some applications find it useful to generate result objects
-(particularly objects with error status) themselves.  If
-<parameter>conn</parameter> is not null and <parameter>status</>
-indicates an error, the current error message of the specified
-connection is copied into the <structname>PGresult</structname>.  Note
-that <function>PQclear</function> should eventually be called on the
-object, just as with a <structname>PGresult</structname> returned by
-<application>libpq</application> itself.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-</sect2>
-
-<sect2 id="libpq-exec-select-info">
-  <title>Retrieving Query Result Information</title>
-
-<para>
-These functions are used to extract information from a
-<structname>PGresult</structname> object that represents a successful
-query result (that is, one that has status
-<literal>PGRES_TUPLES_OK</literal>).  They can also be used to extract
-information from a successful Describe operation: a Describe's result
-has all the same column information that actual execution of the query
-would provide, but it has zero rows.  For objects with other status values,
-these functions will act as though the result has zero rows and zero columns.
-</para>
-
-<variablelist>
-<varlistentry>
-<term><function>PQntuples</function><indexterm><primary>PQntuples</></></term>
-<listitem>
-<para>
-          Returns the number of rows (tuples)
-          in the query result.
-<synopsis>
-int PQntuples(const PGresult *res);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQnfields</function><indexterm><primary>PQnfields</></></term>
-<listitem>
-<para>
-          Returns the number of columns (fields)
-          in each row of the query result.
-<synopsis>
-int PQnfields(const PGresult *res);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQfname</function><indexterm><primary>PQfname</></></term>
-<listitem>
-<para>
-Returns the column name associated with the given column number.
-Column numbers start at 0. The caller should not free the result
-directly. It will be freed when the associated <structname>PGresult</>
-handle is passed to <function>PQclear</function>.
-<synopsis>
-char *PQfname(const PGresult *res,
-              int column_number);
-</synopsis>
-</para>
-
-<para>
-<symbol>NULL</symbol> is returned if the column number is out of range.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQfnumber</function><indexterm><primary>PQfnumber</></></term>
-<listitem>
-<para>
-          Returns the column number associated with the given column name.
-<synopsis>
-int PQfnumber(const PGresult *res,
-              const char *column_name);
-</synopsis>
-</para>
+       <synopsis>
+        int PQnfields(const PGresult *res);
+       </synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQfname</function>
+      <indexterm>
+       <primary>PQfname</primary>
+      </indexterm>
+     </term>
 
-<para>
-        -1 is returned if the given name does not match any column.
-</para>
+     <listitem>
+      <para>
+       Returns the column name associated with the given column number.
+       Column numbers start at 0. The caller should not free the result
+       directly. It will be freed when the associated
+       <structname>PGresult</> handle is passed to
+       <function>PQclear</function>.
+       <synopsis>
+        char *PQfname(const PGresult *res,
+                      int column_number);
+       </synopsis>
+      </para>
+        
+      <para>
+       <symbol>NULL</symbol> is returned if the column number is out of range.
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQfnumber</function>
+      <indexterm>
+       <primary>PQfnumber</primary>
+      </indexterm>
+     </term>
 
-<para>
-        The given name is treated like an identifier in an SQL command,
-        that is, it is downcased unless double-quoted.  For example,
-        given a query result generated from the SQL command:
+     <listitem>
+      <para>
+       Returns the column number associated with the given column name.
+       <synopsis>
+        int PQfnumber(const PGresult *res,
+                      const char *column_name);
+       </synopsis>
+      </para>
+       
+      <para>
+       -1 is returned if the given name does not match any column.
+      </para>
+        
+      <para>
+       The given name is treated like an identifier in an SQL command,
+       that is, it is downcased unless double-quoted.  For example, given
+       a query result generated from the SQL command:
 <programlisting>
-select 1 as FOO, 2 as "BAR";
+SELECT 1 AS FOO, 2 AS "BAR";
 </programlisting>
-        we would have the results:
+       we would have the results:
 <programlisting>
 PQfname(res, 0)              <lineannotation>foo</lineannotation>
 PQfname(res, 1)              <lineannotation>BAR</lineannotation>
@@ -1964,441 +2184,544 @@ PQfnumber(res, "foo")        <lineannotation>0</lineannotation>
 PQfnumber(res, "BAR")        <lineannotation>-1</lineannotation>
 PQfnumber(res, "\"BAR\"")    <lineannotation>1</lineannotation>
 </programlisting>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQftable</function><indexterm><primary>PQftable</></></term>
-<listitem>
-<para>
- Returns the OID of the table from which the given column was fetched.
- Column numbers start at 0.
-<synopsis>
-Oid PQftable(const PGresult *res,
-             int column_number);
-</synopsis>
-</para>
-
-<para>
-<literal>InvalidOid</> is returned if the column number is out of range,
-or if the specified column is not a simple reference to a table column,
-or when using pre-3.0 protocol.
-You can query the system table <literal>pg_class</literal> to determine
-exactly which table is referenced.
-</para>
-
-<para>
-          The type <type>Oid</type> and the constant
-          <literal>InvalidOid</literal> will be defined when you include
-          the <application>libpq</application> header file. They will
-          both be some integer type.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQftablecol</function><indexterm><primary>PQftablecol</></></term>
-<listitem>
-<para>
- Returns the column number (within its table) of the column making up
- the specified query result column.
- Query-result column numbers start at 0, but table columns have nonzero
- numbers.
-<synopsis>
-int PQftablecol(const PGresult *res,
-                int column_number);
-</synopsis>
-</para>
-
-<para>
-Zero is returned if the column number is out of range,
-or if the specified column is not a simple reference to a table column,
-or when using pre-3.0 protocol.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQfformat</function><indexterm><primary>PQfformat</></></term>
-<listitem>
-<para>
- Returns the format code indicating the format of the given column.
- Column numbers start at 0.
-<synopsis>
-int PQfformat(const PGresult *res,
-              int column_number);
-</synopsis>
-</para>
-
-<para>
-Format code zero indicates textual data representation, while format
-code one indicates binary representation.  (Other codes are reserved
-for future definition.)
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQftype</function><indexterm><primary>PQftype</></></term>
-<listitem>
-<para>
-          Returns the data type associated with the
-          given  column number.  The  integer  returned is the
-          internal OID number of the type.  Column numbers start
-          at 0.
-<synopsis>
-Oid PQftype(const PGresult *res,
-            int column_number);
-</synopsis>
-</para>
-
-<para>
-You can query the system table <literal>pg_type</literal> to obtain
-the names and properties of the various data types. The <acronym>OID</acronym>s
-of the built-in data types are defined in the file <filename>src/include/catalog/pg_type.h</filename>
-in the source tree.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQfmod</function><indexterm><primary>PQfmod</></></term>
-<listitem>
-<para>
-          Returns  the type modifier of the column
-          associated with the given column number.
-          Column numbers start at 0.
-<synopsis>
-int PQfmod(const PGresult *res,
-           int column_number);
-</synopsis>
-</para>
-
-<para>
-The interpretation of modifier values is type-specific; they typically
-indicate precision or size limits.  The value -1 is used to indicate
-<quote>no information available</>.  Most data types do not use modifiers,
-in which case the value is always -1.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQfsize</function><indexterm><primary>PQfsize</></></term>
-<listitem>
-<para>
-          Returns  the  size  in bytes of the column
-          associated with the given column number.
-          Column numbers start at 0.
-<synopsis>
-int PQfsize(const PGresult *res,
-            int column_number);
-</synopsis>
-</para>
-
-<para>
-<function>PQfsize</> returns the space allocated for this column in a database
-row, in other words the size of the server's internal representation
-of the data type.  (Accordingly, it is not really very useful to clients.)
-A negative value indicates the data type is variable-length.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQbinaryTuples</function><indexterm><primary>PQbinaryTuples</></></term>
-<listitem>
-<para>
-Returns 1 if the <structname>PGresult</> contains binary data
-and 0 if it contains text data.
-<synopsis>
-int PQbinaryTuples(const PGresult *res);
-</synopsis>
-</para>
-
-<para>
-This function is deprecated (except for its use in connection with
-<command>COPY</>), because it is possible for a single
-<structname>PGresult</>
-to contain text data in some columns and binary data in others.
-<function>PQfformat</> is preferred.  <function>PQbinaryTuples</>
-returns 1 only if all columns of the result are binary (format 1).
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQgetvalue</function><indexterm><primary>PQgetvalue</></></term>
-<listitem>
-<para>
-            Returns a single field value of one row of a
-            <structname>PGresult</structname>.  Row and column numbers
-            start at 0.  The caller should not free the result
-            directly.  It will be freed when the associated
-            <structname>PGresult</> handle is passed to
-            <function>PQclear</function>.
-<synopsis>
-char *PQgetvalue(const PGresult *res,
-                 int row_number,
-                 int column_number);
-</synopsis>
-</para>
-
-<para>
-For data in text format, the value returned by <function>PQgetvalue</function>
-is a null-terminated character string  representation
-of the field value.  For data in binary format, the value is in the binary
-representation determined by the data type's <function>typsend</> and
-<function>typreceive</> functions.  (The value is actually followed by
-a zero byte in this case too, but that is not ordinarily useful, since
-the value is likely to contain embedded nulls.)
-</para>
-
-<para>
-An empty string is returned if the field value is null.  See
-<function>PQgetisnull</> to distinguish null values from empty-string values.
-</para>
-
-<para>
-The pointer
-returned  by  <function>PQgetvalue</function> points to storage that is
-part of the <structname>PGresult</structname> structure.  One should not modify the data it points to,
-and one must explicitly 
-copy the data into other storage if it is to
-be used past the lifetime of the  <structname>PGresult</structname>  structure itself.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQgetisnull</function><indexterm><primary>PQgetisnull</></></term>
-<indexterm><primary>null value</><secondary sortas="libpq">in libpq</></indexterm><listitem>
-<para>
-           Tests a field for a null value.
-           Row and column numbers start at 0.
-<synopsis>
-int PQgetisnull(const PGresult *res,
-                int row_number,
-                int column_number);
-</synopsis>
-</para>
-
-<para>
-This function returns  1 if the field is null and 0 if
-it contains a non-null value.  (Note that <function>PQgetvalue</function>
-will return an empty string, not a null pointer, for a null field.)
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQgetlength</function><indexterm><primary>PQgetlength</></></term>
-<listitem>
-<para>
-          Returns the actual length of a field value in bytes.
-          Row and column numbers start at 0.
-<synopsis>
-int PQgetlength(const PGresult *res,
-                int row_number,
-                int column_number);
-</synopsis>
-</para>
-
-<para>
-This is the actual data length for the particular data value, that is, the
-size of the object pointed to by <function>PQgetvalue</function>.  For text
-data format this is the same as <function>strlen()</>.  For binary format
-this is essential information.  Note that one should <emphasis>not</> rely
-on <function>PQfsize</function> to obtain the actual data length.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQnparams</function><indexterm><primary>PQnparams</></></term>
-<listitem>
-<para>
-          Returns the number of parameters of a prepared statement.
-<synopsis>
-int PQnparams(const PGresult *res);
-</synopsis>
-</para>
-
-<para>
-This function is only useful when inspecting the result of
-<function>PQdescribePrepared</>.  For other types of queries it will
-return zero.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQparamtype</function><indexterm><primary>PQparamtype</></></term>
-<listitem>
-<para>
-          Returns the data type of the indicated statement parameter.
-          Parameter numbers start at 0.
-<synopsis>
-Oid PQparamtype(const PGresult *res, int param_number);
-</synopsis>
-</para>
-
-<para>
-This function is only useful when inspecting the result of
-<function>PQdescribePrepared</>.  For other types of queries it will
-return zero.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQprint</function><indexterm><primary>PQprint</></></term>
-<listitem>
-<para>
-          Prints out all the rows and,  optionally,  the
-          column names  to  the specified output stream.
-<synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+       
+    <varlistentry>
+     <term>
+      <function>PQftable</function>
+      <indexterm>
+       <primary>PQftable</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the OID of the table from which the given column was
+       fetched.  Column numbers start at 0.
+       <synopsis>
+        Oid PQftable(const PGresult *res,
+                     int column_number);
+       </synopsis>
+      </para>
+       
+      <para>
+       <literal>InvalidOid</> is returned if the column number is out of range,
+       or if the specified column is not a simple reference to a table column,
+       or when using pre-3.0 protocol.
+       You can query the system table <literal>pg_class</literal> to determine
+       exactly which table is referenced.
+      </para>
+
+      <para>
+       The type <type>Oid</type> and the constant
+       <literal>InvalidOid</literal> will be defined when you include
+       the <application>libpq</application> header file. They will both
+       be some integer type.
+      </para>
+     </listitem>
+    </varlistentry>
+       
+    <varlistentry>
+     <term>
+      <function>PQftablecol</function>
+      <indexterm>
+       <primary>PQftablecol</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the column number (within its table) of the column making
+       up the specified query result column.  Query-result column numbers
+       start at 0, but table columns have nonzero numbers.
+       <synopsis>
+       int PQftablecol(const PGresult *res,
+                       int column_number);
+       </synopsis>
+      </para>
+      
+      <para>
+       Zero is returned if the column number is out of range, or if the
+       specified column is not a simple reference to a table column, or
+       when using pre-3.0 protocol.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term>
+      <function>PQfformat</function>
+      <indexterm>
+       <primary>PQfformat</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the format code indicating the format of the given
+       column.  Column numbers start at 0.
+       <synopsis>
+        int PQfformat(const PGresult *res,
+                      int column_number);
+       </synopsis>
+      </para>
+     
+      <para>
+       Format code zero indicates textual data representation, while format
+       code one indicates binary representation.  (Other codes are reserved
+       for future definition.)
+      </para>
+     </listitem>
+    </varlistentry>
+      
+    <varlistentry>
+     <term>
+      <function>PQftype</function>
+      <indexterm>
+       <primary>PQftype</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the data type associated with the given  column number.
+       The  integer  returned is the internal OID number of the type.
+       Column numbers start at 0.
+       <synopsis>
+        Oid PQftype(const PGresult *res,
+                    int column_number);
+       </synopsis>
+      </para>
+      
+      <para>
+       You can query the system table <literal>pg_type</literal> to
+       obtain the names and properties of the various data types. The
+       <acronym>OID</acronym>s of the built-in data types are defined
+       in the file <filename>src/include/catalog/pg_type.h</filename>
+       in the source tree.
+      </para>
+     </listitem>
+    </varlistentry>
+      
+    <varlistentry>
+     <term>
+      <function>PQfmod</function>
+      <indexterm>
+       <primary>PQfmod</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns  the type modifier of the column associated with the
+       given column number.  Column numbers start at 0.
+       <synopsis>
+        int PQfmod(const PGresult *res,
+                   int column_number);
+       </synopsis>
+      </para>
+      
+      <para>
+       The interpretation of modifier values is type-specific; they
+       typically indicate precision or size limits.  The value -1 is
+       used to indicate <quote>no information available</>.  Most data
+       types do not use modifiers, in which case the value is always
+       -1.
+      </para>
+     </listitem>
+    </varlistentry>
+      
+    <varlistentry>
+     <term>
+      <function>PQfsize</function>
+      <indexterm>
+       <primary>PQfsize</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns  the  size  in bytes of the column associated with the
+       given column number.  Column numbers start at 0.
+       <synopsis>
+        int PQfsize(const PGresult *res,
+                    int column_number);
+       </synopsis>
+      </para>
+      
+      <para>
+       <function>PQfsize</> returns the space allocated for this column
+       in a database row, in other words the size of the server's
+       internal representation of the data type.  (Accordingly, it is
+       not really very useful to clients.) A negative value indicates
+       the data type is variable-length.
+      </para>
+     </listitem>
+    </varlistentry>
+      
+    <varlistentry>
+     <term>
+      <function>PQbinaryTuples</function>
+      <indexterm>
+       <primary>PQbinaryTuples</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+     <para>
+      Returns 1 if the <structname>PGresult</> contains binary data
+      and 0 if it contains text data.
+     <synopsis>
+      int PQbinaryTuples(const PGresult *res);
+     </synopsis>
+    </para>
+     
+    <para>
+     This function is deprecated (except for its use in connection with
+     <command>COPY</>), because it is possible for a single
+     <structname>PGresult</> to contain text data in some columns and
+     binary data in others.  <function>PQfformat</> is preferred.
+     <function>PQbinaryTuples</> returns 1 only if all columns of the
+     result are binary (format 1).
+    </para>
+   </listitem>
+  </varlistentry>
+     
+  <varlistentry>
+   <term>
+    <function>PQgetvalue</function>
+     <indexterm>
+      <primary>PQgetvalue</primary>
+     </indexterm>
+   </term>
+
+   <listitem>
+    <para>
+     Returns a single field value of one row of a
+     <structname>PGresult</structname>.  Row and column numbers start
+     at 0.  The caller should not free the result directly.  It will
+     be freed when the associated <structname>PGresult</> handle is
+     passed to <function>PQclear</function>.
+     <synopsis>
+      char *PQgetvalue(const PGresult *res,
+                       int row_number,
+                       int column_number);
+     </synopsis>
+    </para>
+   
+    <para>
+     For data in text format, the value returned by
+     <function>PQgetvalue</function> is a null-terminated character
+     string  representation of the field value.  For data in binary
+     format, the value is in the binary representation determined by
+     the data type's <function>typsend</> and <function>typreceive</>
+     functions.  (The value is actually followed by a zero byte in
+     this case too, but that is not ordinarily useful, since the
+     value is likely to contain embedded nulls.)
+    </para>
+   
+    <para>
+     An empty string is returned if the field value is null.  See
+     <function>PQgetisnull</> to distinguish null values from
+     empty-string values.
+    </para>
+    
+    <para>
+     The pointer returned  by  <function>PQgetvalue</function> points
+     to storage that is part of the <structname>PGresult</structname>
+     structure.  One should not modify the data it points to, and one
+     must explicitly copy the data into other storage if it is to be
+     used past the lifetime of the  <structname>PGresult</structname>
+     structure itself.
+    </para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term>
+    <function>PQgetisnull</function>
+    <indexterm>
+     <primary>PQgetisnull</primary>
+    </indexterm>
+    <indexterm>
+     <primary>null value</primary>
+     <secondary sortas="libpq">in libpq</secondary>
+    </indexterm>
+   </term>
+
+   <listitem>
+    <para>
+     Tests a field for a null value.  Row and column numbers start
+     at 0.
+     <synopsis>
+      int PQgetisnull(const PGresult *res,
+                      int row_number,
+                      int column_number);
+     </synopsis>
+    </para>
+   
+    <para>
+     This function returns  1 if the field is null and 0 if it
+     contains a non-null value.  (Note that
+     <function>PQgetvalue</function> will return an empty string,
+     not a null pointer, for a null field.)
+    </para>
+   </listitem>
+  </varlistentry>
+   
+  <varlistentry>
+   <term>
+   <function>PQgetlength</function>
+   <indexterm>
+    <primary>PQgetlength</primary>
+   </indexterm></term>
+
+  <listitem>
+   <para>
+    Returns the actual length of a field value in bytes.  Row and
+    column numbers start at 0.
+    <synopsis>
+     int PQgetlength(const PGresult *res,
+                     int row_number,
+                     int column_number);
+    </synopsis>
+   </para>
+   
+   <para>
+    This is the actual data length for the particular data value,
+    that is, the size of the object pointed to by
+    <function>PQgetvalue</function>.  For text data format this is
+    the same as <function>strlen()</>.  For binary format this is
+    essential information.  Note that one should <emphasis>not</>
+    rely on <function>PQfsize</function> to obtain the actual data
+    length.
+   </para>
+  </listitem>
+ </varlistentry>
+   
+ <varlistentry>
+  <term>
+   <function>PQnparams</function>
+   <indexterm>
+    <primary>PQnparams</primary>
+   </indexterm>
+  </term>
+
+  <listitem>
+   <para>
+    Returns the number of parameters of a prepared statement.
+    <synopsis>
+     int PQnparams(const PGresult *res);
+    </synopsis>
+   </para>
+   
+   <para>
+    This function is only useful when inspecting the result of
+    <function>PQdescribePrepared</>.  For other types of queries it
+    will return zero.
+   </para>
+  </listitem>
+ </varlistentry>
+   
+ <varlistentry>
+  <term>
+   <function>PQparamtype</function>
+   <indexterm>
+    <primary>PQparamtype</primary>
+   </indexterm></term>
+
+   <listitem>
+    <para>
+     Returns the data type of the indicated statement parameter.
+     Parameter numbers start at 0.
+     <synopsis>
+      Oid PQparamtype(const PGresult *res, int param_number);
+     </synopsis>
+    </para>
+    
+    <para>
+     This function is only useful when inspecting the result of
+     <function>PQdescribePrepared</>.  For other types of queries it
+     will return zero.
+    </para>
+   </listitem>
+  </varlistentry>
+    
+  <varlistentry>
+   <term>
+    <function>PQprint</function>
+    <indexterm>
+     <primary>PQprint</primary>
+    </indexterm>
+   </term>
+
+   <listitem>
+    <para>
+     Prints out all the rows and,  optionally,  the column names  to
+     the specified output stream.
+     <synopsis>
 void PQprint(FILE *fout,      /* output stream */
              const PGresult *res,
              const PQprintOpt *po);
-
 typedef struct {
-    pqbool  header;      /* print output field headings and row count */
-    pqbool  align;       /* fill align the fields */
-    pqbool  standard;    /* old brain dead format */
-    pqbool  html3;       /* output HTML tables */
-    pqbool  expanded;    /* expand tables */
-    pqbool  pager;       /* use pager for output if needed */
-    char    *fieldSep;   /* field separator */
-    char    *tableOpt;   /* attributes for HTML table element */
-    char    *caption;    /* HTML table caption */
-    char    **fieldName; /* null-terminated array of replacement field names */
+  pqbool  header;      /* print output field headings and row count */
+  pqbool  align;       /* fill align the fields */
+  pqbool  standard;    /* old brain dead format */
+  pqbool  html3;       /* output HTML tables */
+  pqbool  expanded;    /* expand tables */
+  pqbool  pager;       /* use pager for output if needed */
+  char    *fieldSep;   /* field separator */
+  char    *tableOpt;   /* attributes for HTML table element */
+  char    *caption;    /* HTML table caption */
+  char    **fieldName; /* null-terminated array of replacement field names */
 } PQprintOpt;
-</synopsis>
-</para>
-
-<para>
-This function was formerly used by <application>psql</application>
-to print query results, but this is no longer the case.  Note that it
-assumes all the data is in text format.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</sect2>
-
-<sect2 id="libpq-exec-nonselect">
-  <title>Retrieving Result Information for Other Commands</title>
-
-<para>
-These functions are used to extract information from
-<structname>PGresult</structname> objects that are not <command>SELECT</>
-results.
-</para>
-
-<variablelist>
-<varlistentry>
-<term><function>PQcmdStatus</function><indexterm><primary>PQcmdStatus</></></term>
-<listitem>
-<para>
-          Returns the command status tag from the SQL command that
-          generated the <structname>PGresult</structname>.
-<synopsis>
-char *PQcmdStatus(PGresult *res);
-</synopsis>
-</para>
-<para>
-Commonly this is just the name of the command, but it might include additional
-data such as the number of rows processed. The caller should
-not free the result directly. It will be freed when the
-associated <structname>PGresult</> handle is passed to
-<function>PQclear</function>.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQcmdTuples</function><indexterm><primary>PQcmdTuples</></></term>
-<listitem>
-<para>
-          Returns the number of rows affected by the SQL command.
-<synopsis>
-char *PQcmdTuples(PGresult *res);
-</synopsis>
-</para>
-
-<para>
-          This function returns a string containing the number of rows
-          affected by the <acronym>SQL</> statement that generated the
-          <structname>PGresult</>. This function can only be used
-          following the execution of an <command>INSERT</>,
-          <command>UPDATE</>, <command>DELETE</>, <command>MOVE</>,
-          <command>FETCH</>, or <command>COPY</> statement,
-          or an <command>EXECUTE</> of a
-          prepared query that contains an <command>INSERT</>,
-          <command>UPDATE</>, or <command>DELETE</> statement.  If the
-          command that generated the <structname>PGresult</> was
-          anything else, <function>PQcmdTuples</> returns an empty
-          string. The caller should not free the return value
-          directly. It will be freed when the associated
-          <structname>PGresult</> handle is passed to
-          <function>PQclear</function>.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQoidValue</function><indexterm><primary>PQoidValue</></></term>
-<listitem>
-<para>
-          Returns the OID<indexterm><primary>OID</><secondary>in
-          libpq</></> of the inserted row, if the <acronym>SQL</>
-          command was an <command>INSERT</> that inserted exactly one
-          row into a table that has OIDs, or a <command>EXECUTE</> of
-          a prepared query containing a suitable <command>INSERT</>
-          statement.  Otherwise, this function returns
-          <literal>InvalidOid</literal>. This function will also
-          return <literal>InvalidOid</literal> if the table affected
-          by the <command>INSERT</> statement does not contain OIDs.
-<synopsis>
-Oid PQoidValue(const PGresult *res);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQoidStatus</function><indexterm><primary>PQoidStatus</></></term>
-<listitem>
-<para>
-          Returns a string with the OID of the inserted row, if the
-          <acronym>SQL</acronym> command was an
-          <command>INSERT</command> that inserted exactly one row, or
-          a <command>EXECUTE</command> of a prepared statement
-          consisting of a suitable <command>INSERT</command>.  (The string will be
-          <literal>0</> if the <command>INSERT</command> did not
-          insert exactly one row, or if the target table does not have
-          OIDs.)  If the command was not an <command>INSERT</command>,
-          returns an empty string.
-<synopsis>
-char *PQoidStatus(const PGresult *res);
-</synopsis>
-</para>
+       </synopsis>
+      </para>
+     
+      <para>
+       This function was formerly used by <application>psql</application>
+       to print query results, but this is no longer the case.  Note
+       that it assumes all the data is in text format.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </sect2>
+         
+  <sect2 id="libpq-exec-nonselect">
+   <title>Retrieving Result Information for Other Commands</title>
+         
+   <para>
+    These functions are used to extract information from
+    <structname>PGresult</structname> objects that are not
+    <command>SELECT</> results.
+   </para>
+         
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQcmdStatus</function>
+      <indexterm>
+       <primary>PQcmdStatus</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the command status tag from the SQL command that generated
+       the <structname>PGresult</structname>.
+       <synopsis>
+        char *PQcmdStatus(PGresult *res);
+       </synopsis>
+      </para>
 
-<para>
-This function is deprecated in favor of <function>PQoidValue</function>.
-It is not thread-safe.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
+      <para>
+       Commonly this is just the name of the command, but it might include
+       additional data such as the number of rows processed. The caller
+       should not free the result directly. It will be freed when the
+       associated <structname>PGresult</> handle is passed to
+       <function>PQclear</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQcmdTuples</function>
+      <indexterm>
+       <primary>PQcmdTuples</primary>
+      </indexterm>
+     </term>
 
-</sect2>
+     <listitem>
+      <para>
+       Returns the number of rows affected by the SQL command.
+       <synopsis>
+        char *PQcmdTuples(PGresult *res);
+       </synopsis>
+      </para>
+        
+      <para>
+       This function returns a string containing the number of rows
+       affected by the <acronym>SQL</> statement that generated the
+       <structname>PGresult</>. This function can only be used following
+       the execution of an <command>INSERT</>, <command>UPDATE</>,
+       <command>DELETE</>, <command>MOVE</>, <command>FETCH</>, or
+       <command>COPY</> statement, or an <command>EXECUTE</> of a
+       prepared query that contains an <command>INSERT</>,
+       <command>UPDATE</>, or <command>DELETE</> statement.  If the
+       command that generated the <structname>PGresult</> was anything
+       else, <function>PQcmdTuples</> returns an empty string. The caller
+       should not free the return value directly. It will be freed when
+       the associated <structname>PGresult</> handle is passed to
+       <function>PQclear</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQoidValue</function>
+      <indexterm>
+       <primary>PQoidValue</primary>
+      </indexterm>
+     </term>
 
-<sect2 id="libpq-exec-escape-string">
-  <title>Escaping Strings for Inclusion in SQL Commands</title>
+     <listitem>
+      <para>
+       Returns the OID<indexterm><primary>OID</><secondary>in libpq</></>
+       of the inserted row, if the <acronym>SQL</> command was an
+       <command>INSERT</> that inserted exactly one row into a table that
+       has OIDs, or a <command>EXECUTE</> of a prepared query containing
+       a suitable <command>INSERT</> statement.  Otherwise, this function
+       returns <literal>InvalidOid</literal>. This function will also
+       return <literal>InvalidOid</literal> if the table affected by the
+       <command>INSERT</> statement does not contain OIDs.
+       <synopsis>
+        Oid PQoidValue(const PGresult *res);
+       </synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQoidStatus</function>
+      <indexterm>
+       <primary>PQoidStatus</primary>
+      </indexterm>
+     </term>
 
+     <listitem>
+      <para>
+       Returns a string with the OID of the inserted row, if the
+       <acronym>SQL</acronym> command was an <command>INSERT</command>
+       that inserted exactly one row, or a <command>EXECUTE</command> of
+       a prepared statement consisting of a suitable
+       <command>INSERT</command>.  (The string will be <literal>0</> if
+       the <command>INSERT</command> did not insert exactly one row, or
+       if the target table does not have OIDs.)  If the command was not
+       an <command>INSERT</command>, returns an empty string.
+       <synopsis>
+        char *PQoidStatus(const PGresult *res);
+       </synopsis>
+      </para>
+        
+      <para>
+       This function is deprecated in favor of
+       <function>PQoidValue</function>.  It is not thread-safe.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+        
+  </sect2>
+        
+  <sect2 id="libpq-exec-escape-string">
+   <title>Escaping Strings for Inclusion in SQL Commands</title>
+        
    <indexterm zone="libpq-exec-escape-string">
     <primary>PQescapeStringConn</primary>
    </indexterm>
@@ -2409,2126 +2732,2394 @@ It is not thread-safe.
     <primary>escaping strings</primary>
     <secondary>in libpq</secondary>
    </indexterm>
+        
+   <para>
+    <function>PQescapeStringConn</function> escapes a string for use within an SQL
+    command.  This is useful when inserting data values as literal constants
+    in SQL commands.  Certain characters (such as quotes and backslashes) must
+    be escaped to prevent them from being interpreted specially by the SQL parser.
+    <function>PQescapeStringConn</> performs this operation.
+   </para>
+        
+   <tip>
+    <para>
+     It is especially important to do proper escaping when handling strings that
+     were received from an untrustworthy source.  Otherwise there is a security
+     risk: you are vulnerable to <quote>SQL injection</> attacks wherein unwanted
+     SQL commands are fed to your database.
+    </para>
+   </tip>
+        
+   <para>
+    Note that it is not necessary nor correct to do escaping when a data
+    value is passed as a separate parameter in <function>PQexecParams</> or
+    its sibling routines.
+    
+    <synopsis>
+     size_t PQescapeStringConn (PGconn *conn,
+                                char *to, const char *from, size_t length,
+                                int *error);
+    </synopsis>
+   </para>
+        
+   <para>
+    <function>PQescapeStringConn</> writes an escaped version of the
+    <parameter>from</> string to the <parameter>to</> buffer, escaping
+    special characters so that they cannot cause any harm, and adding a
+    terminating zero byte.  The single quotes that must surround
+    <productname>PostgreSQL</> string literals are not included in the
+    result string; they should be provided in the SQL command that the
+    result is inserted into.  The parameter <parameter>from</> points to
+    the first character of the string that is to be escaped, and the
+    <parameter>length</> parameter gives the number of bytes in this
+    string.  A terminating zero byte is not required, and should not be
+    counted in <parameter>length</>.  (If a terminating zero byte is found
+    before <parameter>length</> bytes are processed,
+    <function>PQescapeStringConn</> stops at the zero; the behavior is
+    thus rather like <function>strncpy</>.) <parameter>to</> shall point
+    to a buffer that is able to hold at least one more byte than twice
+    the value of <parameter>length</>, otherwise the behavior is undefined.
+    Behavior is likewise undefined if the <parameter>to</> and
+    <parameter>from</> strings overlap.
+   </para>
+
+   <para>
+    If the <parameter>error</> parameter is not NULL, then
+    <literal>*error</> is set to zero on success, nonzero on error.
+    Presently the only possible error conditions involve invalid multibyte
+    encoding in the source string.  The output string is still generated
+    on error, but it can be expected that the server will reject it as
+    malformed.  On error, a suitable message is stored in the
+    <parameter>conn</> object, whether or not <parameter>error</> is NULL.
+   </para>
 
-<para>
-<function>PQescapeStringConn</function> escapes a string for use within an SQL
-command.  This is useful when inserting data values as literal constants
-in SQL commands.  Certain characters (such as quotes and backslashes) must
-be escaped to prevent them from being interpreted specially by the SQL parser.
-<function>PQescapeStringConn</> performs this operation.
-</para>
-
-<tip>
-<para>
-It is especially important to do proper escaping when handling strings that
-were received from an untrustworthy source.  Otherwise there is a security
-risk: you are vulnerable to <quote>SQL injection</> attacks wherein unwanted
-SQL commands are fed to your database.
-</para>
-</tip>
-
-<para>
-Note that it is not necessary nor correct to do escaping when a data
-value is passed as a separate parameter in <function>PQexecParams</> or
-its sibling routines.
+   <para>
+    <function>PQescapeStringConn</> returns the number of bytes written
+    to <parameter>to</>, not including the terminating zero byte.
+   </para>
+    
+   <para>
+    <synopsis>
+     size_t PQescapeString (char *to, const char *from, size_t length);
+    </synopsis>
+   </para>
+    
+   <para>
+    <function>PQescapeString</> is an older, deprecated version of
+    <function>PQescapeStringConn</>; the difference is that it does
+    not take <parameter>conn</> or <parameter>error</> parameters.
+    Because of this, it cannot adjust its behavior depending on the
+    connection properties (such as character encoding) and therefore
+    <emphasis>it might give the wrong results</>.  Also, it has no way
+    to report error conditions.
+   </para>
 
-<synopsis>
-size_t PQescapeStringConn (PGconn *conn,
-                           char *to, const char *from, size_t length,
-                           int *error);
-</synopsis>
-</para>
-
-<para>
-<function>PQescapeStringConn</> writes an escaped
-version of the <parameter>from</> string to the <parameter>to</>
-buffer, escaping special characters so that they cannot cause any
-harm, and adding a terminating zero byte.  The single quotes that
-must surround <productname>PostgreSQL</> string literals are not
-included in the result string; they should be provided in the SQL
-command that the result is inserted into.
-The parameter <parameter>from</> points to the first character of the string
-that is to be escaped, and the <parameter>length</> parameter gives the
-number of bytes in this string.  A terminating zero byte is not
-required, and should not be counted in <parameter>length</>.  (If
-a terminating zero byte is found before <parameter>length</> bytes are
-processed, <function>PQescapeStringConn</> stops at the zero; the behavior
-is thus rather like <function>strncpy</>.)
-<parameter>to</> shall point to a
-buffer that is able to hold at least one more byte than twice
-the value of <parameter>length</>, otherwise the behavior is
-undefined.
-Behavior is likewise undefined if the <parameter>to</> and <parameter>from</>
-strings overlap.
-</para>
-<para>
-If the <parameter>error</> parameter is not NULL, then <literal>*error</>
-is set to zero on success, nonzero on error.  Presently the only possible
-error conditions involve invalid multibyte encoding in the source string.
-The output string is still generated on error, but it can be expected that
-the server will reject it as malformed.  On error, a suitable message is
-stored in the <parameter>conn</> object, whether or not <parameter>error</>
-is NULL.
-</para>
-<para>
-<function>PQescapeStringConn</> returns the number of bytes written
-to <parameter>to</>, not including the terminating zero byte.
-</para>
-
-<para>
-<synopsis>
-size_t PQescapeString (char *to, const char *from, size_t length);
-</synopsis>
-</para>
-
-<para>
-<function>PQescapeString</> is an older, deprecated version of
-<function>PQescapeStringConn</>; the difference is that it does not
-take <parameter>conn</> or <parameter>error</> parameters.  Because of this,
-it cannot adjust its behavior depending on the connection properties (such as
-character encoding) and therefore <emphasis>it might give the wrong results</>.
-Also, it has no way to report error conditions.
-</para>
-<para>
-<function>PQescapeString</> can be used safely in single-threaded client
-programs that work with only one <productname>PostgreSQL</> connection at
-a time (in this case it can find out what it needs to know <quote>behind the
-scenes</>).  In other contexts it is a security hazard and should be avoided
-in favor of <function>PQescapeStringConn</>.
-</para>
-</sect2>
-
-
- <sect2 id="libpq-exec-escape-bytea">
-  <title>Escaping Binary Strings for Inclusion in SQL Commands</title>
-
-  <indexterm zone="libpq-exec-escape-bytea">
-   <primary>bytea</primary>
-   <secondary sortas="libpq">in libpq</secondary>
+   <para>
+    <function>PQescapeString</> can be used safely in single-threaded
+    client programs that work with only one <productname>PostgreSQL</>
+    connection at a time (in this case it can find out what it needs to
+    know <quote>behind the scenes</>).  In other contexts it is a security
+    hazard and should be avoided in favor of
+    <function>PQescapeStringConn</>.
+   </para>
+  </sect2>
+        
+        
+  <sect2 id="libpq-exec-escape-bytea">
+   <title>Escaping Binary Strings for Inclusion in SQL Commands</title>
+        
+   <indexterm zone="libpq-exec-escape-bytea">
+    <primary>bytea</primary>
+    <secondary sortas="libpq">in libpq</secondary>
+   </indexterm>
+        
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQescapeByteaConn</function>
+      <indexterm>
+       <primary>PQescapeByteaConn</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+     <para>
+       Escapes binary data for use within an SQL command with the type
+       <type>bytea</type>.  As with <function>PQescapeStringConn</function>,
+       this is only used when inserting data directly into an SQL command string.
+       <synopsis>
+        unsigned char *PQescapeByteaConn(PGconn *conn,
+                                         const unsigned char *from,
+                                         size_t from_length,
+                                         size_t *to_length);
+       </synopsis>
+      </para>
+        
+      <para>
+       Certain byte values <emphasis>must</emphasis> be escaped (but all
+       byte values <emphasis>can</emphasis> be escaped) when used as part
+       of a <type>bytea</type> literal in an <acronym>SQL</acronym>
+       statement. In general, to escape a byte, it is converted into the
+       three digit octal number equal to the octet value, and preceded by
+       usually two backslashes. The single quote (<literal>'</>) and backslash
+       (<literal>\</>) characters have special alternative escape
+       sequences. See <xref linkend="datatype-binary"> for more
+       information. <function>PQescapeByteaConn</function> performs this
+       operation, escaping only the minimally required bytes.
+      </para>
+   
+      <para>
+       The <parameter>from</parameter> parameter points to the first
+       byte of the string that is to be escaped, and the
+       <parameter>from_length</parameter> parameter gives the number of
+       bytes in this binary string.  (A terminating zero byte is
+       neither necessary nor counted.)  The <parameter>to_length</parameter>
+       parameter points to a variable that will hold the resultant
+       escaped string length. This result string length includes the terminating
+       zero byte of the result.
+      </para>
+   
+      <para>
+       <function>PQescapeByteaConn</> returns an escaped version of the
+       <parameter>from</parameter> parameter binary string in memory
+       allocated with <function>malloc()</>.  This memory must be freed using
+       <function>PQfreemem()</> when the result is no longer needed.  The
+       return string has all special characters replaced so that they can
+       be properly processed by the <productname>PostgreSQL</productname>
+       string literal parser, and the <type>bytea</type> input function. A
+       terminating zero byte is also added.  The single quotes that must
+       surround <productname>PostgreSQL</productname> string literals are
+       not part of the result string.
+      </para>
+   
+      <para>
+       On error, a NULL pointer is returned, and a suitable error message
+       is stored in the <parameter>conn</> object.  Currently, the only
+       possible error is insufficient memory for the result string.
+      </para>
+     </listitem>
+    </varlistentry>
+   
+    <varlistentry>
+     <term>
+      <function>PQescapeBytea</function>
+      <indexterm>
+       <primary>PQescapeBytea</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       <function>PQescapeBytea</> is an older, deprecated version of
+       <function>PQescapeByteaConn</>.
+       <synopsis>
+        unsigned char *PQescapeBytea(const unsigned char *from,
+                                     size_t from_length,
+                                     size_t *to_length);
+       </synopsis>
+      </para>
+       
+      <para>
+       The only difference from <function>PQescapeByteaConn</> is that
+       <function>PQescapeBytea</> does not take a <structname>PGconn</>
+       parameter.  Because of this, it cannot adjust its behavior
+       depending on the connection properties (in particular, whether
+       standard-conforming strings are enabled) and therefore
+       <emphasis>it might give the wrong results</>.  Also, it has no
+       way to return an error message on failure.
+      </para>
+       
+      <para>
+       <function>PQescapeBytea</> can be used safely in single-threaded
+       client programs that work with only one <productname>PostgreSQL</>
+       connection at a time (in this case it can find out what it needs
+       to know <quote>behind the scenes</>).  In other contexts it is
+       a security hazard and should be avoided in favor of
+       <function>PQescapeByteaConn</>.
+      </para>
+     </listitem>
+    </varlistentry>
+       
+    <varlistentry>
+     <term>
+      <function>PQunescapeBytea</function>
+      <indexterm>
+       <primary>PQunescapeBytea</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Converts a string representation of binary data into binary data
+       &mdash; the reverse of <function>PQescapeBytea</function>.  This
+       is needed when retrieving <type>bytea</type> data in text format,
+       but not when retrieving it in binary format.
+        
+       <synopsis>
+        unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
+       </synopsis>
+      </para>
+      
+      <para>
+       The <parameter>from</parameter> parameter points to a string
+       such as might be returned by <function>PQgetvalue</function> when applied
+       to a <type>bytea</type> column. <function>PQunescapeBytea</function>
+       converts this string representation into its binary representation.
+       It returns a pointer to a buffer allocated with
+       <function>malloc()</function>, or null on error, and puts the size of
+       the buffer in <parameter>to_length</parameter>. The result must be
+       freed using <function>PQfreemem</> when it is no longer needed.
+      </para>
+    
+      <para>
+       This conversion is not exactly the inverse of
+       <function>PQescapeBytea</function>, because the string is not expected
+       to be <quote>escaped</> when received from <function>PQgetvalue</function>.
+       In particular this means there is no need for string quoting considerations,
+       and so no need for a <structname>PGconn</> parameter.
+      </para>
+     </listitem>
+    </varlistentry>
+      
+    <varlistentry>
+     <term>
+      <function>PQfreemem</function>
+      <indexterm>
+       <primary>PQfreemem</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Frees memory allocated by <application>libpq</>.
+       <synopsis>
+        void PQfreemem(void *ptr);
+       </synopsis>
+      </para>
+      
+      <para>
+       Frees memory allocated by <application>libpq</>, particularly
+       <function>PQescapeByteaConn</function>,
+       <function>PQescapeBytea</function>,
+       <function>PQunescapeBytea</function>,
+       and <function>PQnotifies</function>.
+       It is particularly important that this function, rather than
+       <function>free()</>, be used on Microsoft Windows.  This is because
+       allocating memory in a DLL and releasing it in the application works
+       only if multithreaded/single-threaded, release/debug, and static/dynamic
+       flags are the same for the DLL and the application.  On non-Microsoft
+       Windows platforms, this function is the same as the standard library
+       function <function>free()</>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+         
+  </sect2>
+
+ </sect1>
+        
+ <sect1 id="libpq-async">
+  <title>Asynchronous Command Processing</title>
+        
+  <indexterm zone="libpq-async">
+   <primary>nonblocking connection</primary>
   </indexterm>
+        
+  <para>
+   The <function>PQexec</function> function is adequate for submitting
+   commands in normal, synchronous applications.  It has a couple of
+   deficiencies, however, that can be of importance to some users:
+   
+   <itemizedlist>
+    <listitem>
+     <para>
+      <function>PQexec</function> waits for the command to be completed.
+      The application might have other work to do (such as maintaining a
+      user interface), in which case it won't want to block waiting for
+      the response.
+     </para>
+    </listitem>
 
-  <variablelist>
-  <varlistentry>
-  <term><function>PQescapeByteaConn</function><indexterm><primary>PQescapeByteaConn</></></term>
-  <listitem>
+    <listitem>
+     <para>
+      Since the execution of the client application is suspended while it
+      waits for the result, it is hard for the application to decide that
+      it would like to try to cancel the ongoing command.  (It can be done
+      from a signal handler, but not otherwise.)
+     </para>
+    </listitem>
+  
+    <listitem>
+     <para>
+      <function>PQexec</function> can return only one
+      <structname>PGresult</structname> structure.  If the submitted command
+      string contains multiple <acronym>SQL</acronym> commands, all but
+      the last <structname>PGresult</structname> are discarded by
+      <function>PQexec</function>.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+   
   <para>
-   Escapes binary data for use within an SQL command with the type
-   <type>bytea</type>.  As with <function>PQescapeStringConn</function>,
-   this is only used when inserting data directly into an SQL command string.
-<synopsis>
-unsigned char *PQescapeByteaConn(PGconn *conn,
-                                 const unsigned char *from,
-                                 size_t from_length,
-                                 size_t *to_length);
-</synopsis>
-</para>
-
-<para>
-   Certain byte values <emphasis>must</emphasis> be escaped (but all
-   byte values <emphasis>can</emphasis> be escaped) when used as part
-   of a <type>bytea</type> literal in an <acronym>SQL</acronym>
-   statement. In general, to escape a byte, it is converted into the
-   three digit octal number equal to the octet value, and preceded by
-   usually two backslashes. The single quote (<literal>'</>) and backslash
-   (<literal>\</>) characters have special alternative escape
-   sequences. See <xref linkend="datatype-binary"> for more
-   information. <function>PQescapeByteaConn</function> performs this
-   operation, escaping only the minimally required bytes.
+   Applications that do not like these limitations can instead use the
+   underlying functions that <function>PQexec</function> is built from:
+   <function>PQsendQuery</function> and <function>PQgetResult</function>.
+   There are also
+   <function>PQsendQueryParams</function>,
+   <function>PQsendPrepare</function>,
+   <function>PQsendQueryPrepared</function>,
+   <function>PQsendDescribePrepared</function>, and
+   <function>PQsendDescribePortal</function>,
+   which can be used with <function>PQgetResult</function> to duplicate
+   the functionality of
+   <function>PQexecParams</function>,
+   <function>PQprepare</function>,
+   <function>PQexecPrepared</function>,
+   <function>PQdescribePrepared</function>, and
+   <function>PQdescribePortal</function>
+   respectively.
+   
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQsendQuery</function>
+      <indexterm>
+       <primary>PQsendQuery</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Submits a command to the server without waiting for the result(s).
+       1 is returned if the command was successfully dispatched and 0 if
+       not (in which case, use <function>PQerrorMessage</> to get more
+       information about the failure).
+       <synopsis>
+        int PQsendQuery(PGconn *conn, const char *command);
+       </synopsis>
+        
+       After successfully calling <function>PQsendQuery</function>, call
+       <function>PQgetResult</function> one or more times to obtain the
+       results.  <function>PQsendQuery</function> cannot be called again
+       (on the same connection) until <function>PQgetResult</function>
+       has returned a null pointer, indicating that the command is done.
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQsendQueryParams</function>
+      <indexterm>
+       <primary>PQsendQueryParams</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Submits a command and separate parameters to the server without
+       waiting for the result(s).
+       <synopsis>
+        int PQsendQueryParams(PGconn *conn,
+                              const char *command,
+                              int nParams,
+                              const Oid *paramTypes,
+                              const char * const *paramValues,
+                              const int *paramLengths,
+                              const int *paramFormats,
+                              int resultFormat);
+       </synopsis>
+        
+       This is equivalent to <function>PQsendQuery</function> except that
+       query parameters can be specified separately from the query string.
+       The function's parameters are handled identically to
+       <function>PQexecParams</function>.  Like
+       <function>PQexecParams</function>, it will not work on 2.0-protocol
+       connections, and it allows only one command in the query string.
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQsendPrepare</>
+      <indexterm>
+       <primary>PQsendPrepare</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Sends a request to create a prepared statement with the given
+       parameters, without waiting for completion.
+       <synopsis>
+        int PQsendPrepare(PGconn *conn,
+                          const char *stmtName,
+                          const char *query,
+                          int nParams,
+                          const Oid *paramTypes);
+       </synopsis>
+       
+       This is an asynchronous version of <function>PQprepare</>: it
+       returns 1 if it was able to dispatch the request, and 0 if not.
+       After a successful call, call <function>PQgetResult</function> to
+       determine whether the server successfully created the prepared
+       statement.  The function's parameters are handled identically to
+       <function>PQprepare</function>.  Like
+       <function>PQprepare</function>, it will not work on 2.0-protocol
+       connections.
+      </para>
+     </listitem>
+    </varlistentry>
+       
+    <varlistentry>
+     <term>
+      <function>PQsendQueryPrepared</function>
+      <indexterm>
+       <primary>PQsendQueryPrepared</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Sends a request to execute a prepared statement with given
+       parameters, without waiting for the result(s).
+       <synopsis>
+        int PQsendQueryPrepared(PGconn *conn,
+                                const char *stmtName,
+                                int nParams,
+                                const char * const *paramValues,
+                                const int *paramLengths,
+                                const int *paramFormats,
+                                int resultFormat);
+       </synopsis>
+      
+       This is similar to <function>PQsendQueryParams</function>, but
+       the command to be executed is specified by naming a
+       previously-prepared statement, instead of giving a query string.
+       The function's parameters are handled identically to
+       <function>PQexecPrepared</function>.  Like
+       <function>PQexecPrepared</function>, it will not work on
+       2.0-protocol connections.
+      </para>
+     </listitem>
+    </varlistentry>
+       
+    <varlistentry>
+     <term>
+      <function>PQsendDescribePrepared</>
+      <indexterm>
+       <primary>PQsendDescribePrepared</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Submits a request to obtain information about the specified
+       prepared statement, without waiting for completion.
+       <synopsis>
+        int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
+       </synopsis>
+       
+       This is an asynchronous version of <function>PQdescribePrepared</>:
+       it returns 1 if it was able to dispatch the request, and 0 if not.
+       After a successful call, call <function>PQgetResult</function> to
+       obtain the results.  The function's parameters are handled
+       identically to <function>PQdescribePrepared</function>.  Like
+       <function>PQdescribePrepared</function>, it will not work on
+       2.0-protocol connections.
+      </para>
+     </listitem>
+    </varlistentry>
+       
+    <varlistentry>
+     <term>
+      <function>PQsendDescribePortal</>
+      <indexterm>
+       <primary>PQsendDescribePortal</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Submits a request to obtain information about the specified
+       portal, without waiting for completion.
+       <synopsis>
+        int PQsendDescribePortal(PGconn *conn, const char *portalName);
+       </synopsis>
+       
+       This is an asynchronous version of <function>PQdescribePortal</>:
+       it returns 1 if it was able to dispatch the request, and 0 if not.
+       After a successful call, call <function>PQgetResult</function> to
+       obtain the results.  The function's parameters are handled
+       identically to <function>PQdescribePortal</function>.  Like
+       <function>PQdescribePortal</function>, it will not work on
+       2.0-protocol connections.
+      </para>
+     </listitem>
+    </varlistentry>
+       
+    <varlistentry>
+     <term>
+      <function>PQgetResult</function>
+      <indexterm>
+       <primary>PQgetResult</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Waits for the next result from a prior
+       <function>PQsendQuery</function>,
+       <function>PQsendQueryParams</function>,
+       <function>PQsendPrepare</function>, or
+       <function>PQsendQueryPrepared</function> call, and returns it.
+       A null pointer is returned when the command is complete and there
+       will be no more results.
+       <synopsis>
+        PGresult *PQgetResult(PGconn *conn);
+       </synopsis>
+      </para>
+       
+      <para>
+       <function>PQgetResult</function> must be called repeatedly until
+       it returns a null pointer, indicating that the command is done.
+       (If called when no command is active,
+       <function>PQgetResult</function> will just return a null pointer
+       at once.) Each non-null result from
+       <function>PQgetResult</function> should be processed using the
+       same <structname>PGresult</> accessor functions previously
+       described.  Don't forget to free each result object with
+       <function>PQclear</function> when done with it.  Note that
+       <function>PQgetResult</function> will block only if a command is
+       active and the necessary response data has not yet been read by
+       <function>PQconsumeInput</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+       
+  <para>
+   Using <function>PQsendQuery</function> and
+   <function>PQgetResult</function> solves one of
+   <function>PQexec</function>'s problems:  If a command string contains
+   multiple <acronym>SQL</acronym> commands, the results of those commands
+   can be obtained individually.  (This allows a simple form of overlapped
+   processing, by the way: the client can be handling the results of one
+   command while the server is still working on later queries in the same
+   command string.)  However, calling <function>PQgetResult</function>
+   will still cause the client to block until the server completes the
+   next <acronym>SQL</acronym> command.  This can be avoided by proper
+   use of two more functions:
+       
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQconsumeInput</function>
+      <indexterm>
+       <primary>PQconsumeInput</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       If input is available from the server, consume it.
+       <synopsis>
+        int PQconsumeInput(PGconn *conn);
+       </synopsis>
+      </para>
+       
+      <para>
+       <function>PQconsumeInput</function> normally returns 1 indicating
+       <quote>no error</quote>, but returns 0 if there was some kind of
+       trouble (in which case <function>PQerrorMessage</function> can be
+       consulted).  Note that the result does not say whether any input
+       data was actually collected. After calling
+       <function>PQconsumeInput</function>, the application can check
+       <function>PQisBusy</function> and/or
+       <function>PQnotifies</function> to see if their state has changed.
+      </para>
+
+      <para>
+       <function>PQconsumeInput</function> can be called even if the
+       application is not prepared to deal with a result or notification
+       just yet.  The function will read available data and save it in
+       a buffer, thereby causing a <function>select()</function>
+       read-ready indication to go away.  The application can thus use
+       <function>PQconsumeInput</function> to clear the
+       <function>select()</function> condition immediately, and then
+       examine the results at leisure.
+      </para>
+     </listitem>
+    </varlistentry>
+       
+    <varlistentry>
+     <term>
+      <function>PQisBusy</function>
+      <indexterm>
+       <primary>PQisBusy</primary>
+      </indexterm>
+     </term>
 
+     <listitem>
+      <para>
+       Returns 1 if a command is busy, that is,
+       <function>PQgetResult</function> would block waiting for input.
+       A 0 return indicates that <function>PQgetResult</function> can be
+       called with assurance of not blocking.
+       <synopsis>
+        int PQisBusy(PGconn *conn);
+       </synopsis>
+      </para>
+      
+      <para>
+       <function>PQisBusy</function> will not itself attempt to read data
+       from the server; therefore <function>PQconsumeInput</function>
+       must be invoked first, or the busy state will never end.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+       
   <para>
-   The <parameter>from</parameter> parameter points to the first
-   byte of the string that is to be escaped, and the
-   <parameter>from_length</parameter> parameter gives the number of
-   bytes in this binary string.  (A terminating zero byte is
-   neither necessary nor counted.)  The <parameter>to_length</parameter>
-   parameter points to a variable that will hold the resultant
-   escaped string length. This result string length includes the terminating
-   zero byte of the result.
+   A typical application using these functions will have a main loop that
+   uses <function>select()</function> or <function>poll()</> to wait for
+   all the conditions that it must respond to.  One of the conditions
+   will be input available from the server, which in terms of
+   <function>select()</function> means readable data on the file
+   descriptor identified by <function>PQsocket</function>.  When the main
+   loop detects input ready, it should call
+   <function>PQconsumeInput</function> to read the input.  It can then
+   call <function>PQisBusy</function>, followed by
+   <function>PQgetResult</function> if <function>PQisBusy</function>
+   returns false (0).  It can also call <function>PQnotifies</function>
+   to detect <command>NOTIFY</> messages (see <xref
+   linkend="libpq-notify">).
   </para>
-
+       
   <para>
-   <function>PQescapeByteaConn</> returns an escaped version of the
-   <parameter>from</parameter> parameter binary string in memory
-   allocated with <function>malloc()</>.  This memory must be freed using
-   <function>PQfreemem()</> when the result is no longer needed.  The
-   return string has all special characters replaced so that they can
-   be properly processed by the <productname>PostgreSQL</productname>
-   string literal parser, and the <type>bytea</type> input function. A
-   terminating zero byte is also added.  The single quotes that must
-   surround <productname>PostgreSQL</productname> string literals are
-   not part of the result string.
+   A client that uses
+   <function>PQsendQuery</function>/<function>PQgetResult</function>
+   can also attempt to cancel a command that is still being processed
+   by the server; see <xref linkend="libpq-cancel">.  But regardless of
+   the return value of <function>PQcancel</function>, the application
+   must continue with the normal result-reading sequence using
+   <function>PQgetResult</function>.  A successful cancellation will
+   simply cause the command to terminate sooner than it would have
+   otherwise.
   </para>
+   
+  <para>
+   By using the functions described above, it is possible to avoid
+   blocking while waiting for input from the database server.  However,
+   it is still possible that the application will block waiting to send
+   output to the server.  This is relatively uncommon but can happen if
+   very long SQL commands or data values are sent.  (It is much more
+   probable if the application sends data via <command>COPY IN</command>,
+   however.)  To prevent this possibility and achieve completely
+   nonblocking database operation, the following additional functions
+   can be used.
+      
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQsetnonblocking</function>
+      <indexterm>
+       <primary>PQsetnonblocking</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Sets the nonblocking status of the connection.
+       <synopsis>
+        int PQsetnonblocking(PGconn *conn, int arg);
+       </synopsis>
+      </para>
+      
+      <para>
+       Sets the state of the connection to nonblocking if
+       <parameter>arg</parameter> is 1, or blocking if
+       <parameter>arg</parameter> is 0.  Returns 0 if OK, -1 if error.
+      </para>
+
+      <para>
+       In the nonblocking state, calls to
+       <function>PQsendQuery</function>, <function>PQputline</function>,
+       <function>PQputnbytes</function>, and
+       <function>PQendcopy</function> will not block but instead return
+       an error if they need to be called again.
+      </para>
+
+      <para>
+       Note that <function>PQexec</function> does not honor nonblocking
+       mode; if it is called, it will act in blocking fashion anyway.
+      </para>
+     </listitem>
+    </varlistentry>
+      
+    <varlistentry>
+     <term>
+      <function>PQisnonblocking</function>
+      <indexterm>
+       <primary>PQisnonblocking</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Returns the blocking status of the database connection.
+       <synopsis>
+        int PQisnonblocking(const PGconn *conn);
+       </synopsis>
+      </para>
+      
+      <para>
+       Returns 1 if the connection is set to nonblocking mode and 0 if
+       blocking.
+      </para>
+     </listitem>
+    </varlistentry>
+      
+    <varlistentry>
+     <term>
+      <function>PQflush</function>
+       <indexterm>
+        <primary>PQflush</primary>
+       </indexterm>
+      </term>
 
+      <listitem>
+       <para>
+       Attempts to flush any queued output data to the server.  Returns
+       0 if successful (or if the send queue is empty), -1 if it failed
+       for some reason, or 1 if it was unable to send all the data in
+       the send queue yet (this case can only occur if the connection
+       is nonblocking).
+       <synopsis>
+        int PQflush(PGconn *conn);
+       </synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+      
   <para>
-   On error, a NULL pointer is returned, and a suitable error message
-   is stored in the <parameter>conn</> object.  Currently, the only
-   possible error is insufficient memory for the result string.
+   After sending any command or data on a nonblocking connection, call
+   <function>PQflush</function>.  If it returns 1, wait for the socket
+   to be write-ready and call it again; repeat until it returns 0.  Once
+   <function>PQflush</function> returns 0, wait for the socket to be
+   read-ready and then read the response as described above.
   </para>
-  </listitem>
-  </varlistentry>
+      
+ </sect1>
+       
+ <sect1 id="libpq-cancel">
+  <title>Cancelling Queries in Progress</title>
+        
+  <indexterm zone="libpq-cancel">
+   <primary>canceling</primary>
+   <secondary>SQL command</secondary>
+  </indexterm>
+        
+  <para>
+   A client application can request cancellation of a command that is
+   still being processed by the server, using the functions described in
+   this section.
+        
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQgetCancel</function>
+      <indexterm>
+       <primary>PQgetCancel</primary>
+      </indexterm>
+     </term>
 
-  <varlistentry>
-  <term><function>PQescapeBytea</function><indexterm><primary>PQescapeBytea</></></term>
-  <listitem>
+     <listitem>
+      <para>
+       Creates a data structure containing the information needed to cancel
+       a command issued through a particular database connection.
+       <synopsis>
+        PGcancel *PQgetCancel(PGconn *conn);
+       </synopsis>
+      </para>
+         
+      <para>
+       <function>PQgetCancel</function> creates a
+       <structname>PGcancel</><indexterm><primary>PGcancel</></> object
+       given a <structname>PGconn</> connection object.  It will return
+       NULL if the given <parameter>conn</> is NULL or an invalid
+       connection.  The <structname>PGcancel</> object is an opaque
+       structure that is not meant to be accessed directly by the
+       application; it can only be passed to <function>PQcancel</function>
+       or <function>PQfreeCancel</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term>
+      <function>PQfreeCancel</function>
+      <indexterm>
+       <primary>PQfreeCancel</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Frees a data structure created by <function>PQgetCancel</function>.
+       <synopsis>
+        void PQfreeCancel(PGcancel *cancel);
+       </synopsis>
+      </para>
+        
+      <para>
+       <function>PQfreeCancel</function> frees a data object previously created
+       by <function>PQgetCancel</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQcancel</function>
+      <indexterm>
+       <primary>PQcancel</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Requests that the server abandon processing of the current command.
+       <synopsis>
+        int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
+       </synopsis>
+      </para>
+        
+      <para>
+       The return value is 1 if the cancel request was successfully
+       dispatched and 0 if not.  If not, <parameter>errbuf</> is filled
+       with an error message explaining why not.  <parameter>errbuf</>
+       must be a char array of size <parameter>errbufsize</> (the
+       recommended size is 256 bytes).
+      </para>
+        
+      <para>
+       Successful dispatch is no guarantee that the request will have
+       any effect, however.  If the cancellation is effective, the current
+       command will terminate early and return an error result.  If the
+       cancellation fails (say, because the server was already done
+       processing the command), then there will be no visible result at
+       all.
+      </para>
+      
+      <para>
+       <function>PQcancel</function> can safely be invoked from a signal
+       handler, if the <parameter>errbuf</> is a local variable in the
+       signal handler.  The <structname>PGcancel</> object is read-only
+       as far as <function>PQcancel</function> is concerned, so it can
+       also be invoked from a thread that is separate from the one
+       manipulating the <structname>PGconn</> object.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+       
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQrequestCancel</function>
+      <indexterm>
+       <primary>PQrequestCancel</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Requests that the server abandon processing of the current
+       command.
+       <synopsis>
+        int PQrequestCancel(PGconn *conn);
+       </synopsis>
+      </para>
+      
+      <para>
+       <function>PQrequestCancel</function> is a deprecated variant of
+       <function>PQcancel</function>.  It operates directly on the
+       <structname>PGconn</> object, and in case of failure stores the
+       error message in the <structname>PGconn</> object (whence it can
+       be retrieved by <function>PQerrorMessage</function>).  Although
+       the functionality is the same, this approach creates hazards for
+       multiple-thread programs and signal handlers, since it is possible
+       that overwriting the <structname>PGconn</>'s error message will
+       mess up the operation currently in progress on the connection.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+      
+ </sect1>
+        
+ <sect1 id="libpq-fastpath">
+  <title>The Fast-Path Interface</title>
+        
+  <indexterm zone="libpq-fastpath">
+   <primary>fast path</primary>
+  </indexterm>
+        
   <para>
-   <function>PQescapeBytea</> is an older, deprecated version of
-   <function>PQescapeByteaConn</>.
-<synopsis>
-unsigned char *PQescapeBytea(const unsigned char *from,
-                             size_t from_length,
-                             size_t *to_length);
-</synopsis>
-</para>
-
-<para>
-   The only difference from <function>PQescapeByteaConn</> is that
-   <function>PQescapeBytea</> does not
-   take a <structname>PGconn</> parameter.  Because of this, it cannot adjust
-   its behavior depending on the connection properties (in particular,
-   whether standard-conforming strings are enabled)
-   and therefore <emphasis>it might give the wrong results</>.  Also, it
-   has no way to return an error message on failure.
+   <productname>PostgreSQL</productname> provides a fast-path interface
+   to send simple function calls to the server.
   </para>
-
+        
+  <tip>
+   <para>
+    This interface is somewhat obsolete, as one can achieve similar
+    performance and greater functionality by setting up a prepared
+    statement to define the function call.  Then, executing the statement
+    with binary transmission of parameters and results substitutes for a
+    fast-path function call.
+   </para>
+  </tip>
+        
   <para>
-   <function>PQescapeBytea</> can be used safely in single-threaded client
-   programs that work with only one <productname>PostgreSQL</> connection at
-   a time (in this case it can find out what it needs to know <quote>behind the
-   scenes</>).  In other contexts it is a security hazard and should be
-   avoided in favor of <function>PQescapeByteaConn</>.
+   The function <function>PQfn</function><indexterm><primary>PQfn</></>
+   requests execution of a server function via the fast-path interface:
+   <synopsis>
+    PGresult *PQfn(PGconn *conn,
+                   int fnid,
+                   int *result_buf,
+                   int *result_len,
+                   int result_is_int,
+                   const PQArgBlock *args,
+                   int nargs);
+        
+    typedef struct {
+        int len;
+        int isint;
+        union {
+            int *ptr;
+            int integer;
+        } u;
+    } PQArgBlock;
+   </synopsis>
   </para>
-  </listitem>
-  </varlistentry>
-
-  <varlistentry>
-  <term><function>PQunescapeBytea</function><indexterm><primary>PQunescapeBytea</></></term>
-  <listitem>
+        
   <para>
-   Converts a string representation of binary data into binary
-   data &mdash; the reverse of <function>PQescapeBytea</function>.
-   This is needed when retrieving <type>bytea</type> data in text format,
-   but not when retrieving it in binary format.
-
-<synopsis>
-unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
-</synopsis>
-</para>
-
+   The <parameter>fnid</> argument is the OID of the function to be
+   executed.  <parameter>args</> and <parameter>nargs</> define the
+   parameters to be passed to the function; they must match the declared
+   function argument list.  When the <parameter>isint</> field of a
+   parameter structure is true, the <parameter>u.integer</> value is sent
+   to the server as an integer of the indicated length (this must be 1,
+   2, or 4 bytes); proper byte-swapping occurs.  When <parameter>isint</>
+   is false, the indicated number of bytes at <parameter>*u.ptr</> are
+   sent with no processing; the data must be in the format expected by
+   the server for binary transmission of the function's argument data
+   type.  <parameter>result_buf</parameter> is the buffer in which to
+   place the return value.  The caller must  have  allocated sufficient
+   space to store the return value.  (There is no check!) The actual result
+   length will be returned in the integer pointed to  by
+   <parameter>result_len</parameter>.  If a 1, 2, or 4-byte integer result
+   is expected, set <parameter>result_is_int</parameter> to 1, otherwise
+   set it to 0.  Setting <parameter>result_is_int</parameter> to 1 causes
+   <application>libpq</> to byte-swap the value if necessary, so that it
+   is delivered as a proper <type>int</type> value for the client machine.
+   When <parameter>result_is_int</> is 0, the binary-format byte string
+   sent by the server is returned unmodified.
+  </para>
+        
   <para>
-   The <parameter>from</parameter> parameter points to a string
-   such as might be returned by <function>PQgetvalue</function> when applied
-   to a <type>bytea</type> column. <function>PQunescapeBytea</function>
-   converts this string representation into its binary representation.
-   It returns a pointer to a buffer allocated with
-   <function>malloc()</function>, or null on error, and puts the size of
-   the buffer in <parameter>to_length</parameter>. The result must be
-   freed using <function>PQfreemem</> when it is no longer needed.
+   <function>PQfn</function> always returns a valid
+   <structname>PGresult</structname> pointer. The result status should be
+   checked before the result is used.   The caller is responsible for
+   freeing  the  <structname>PGresult</structname>  with
+   <function>PQclear</function> when it is no longer needed.
   </para>
-
+        
   <para>
-   This conversion is not exactly the inverse of
-   <function>PQescapeBytea</function>, because the string is not expected
-   to be <quote>escaped</> when received from <function>PQgetvalue</function>.
-   In particular this means there is no need for string quoting considerations,
-   and so no need for a <structname>PGconn</> parameter.
+   Note that it is not possible to handle null arguments, null results,
+   nor set-valued results when using this interface.
   </para>
-  </listitem>
-  </varlistentry>
-
-  <varlistentry>
-  <term><function>PQfreemem</function><indexterm><primary>PQfreemem</></></term>
-  <listitem>
+        
+ </sect1>
+        
+ <sect1 id="libpq-notify">
+  <title>Asynchronous Notification</title>
+        
+  <indexterm zone="libpq-notify">
+   <primary>NOTIFY</primary>
+   <secondary>in libpq</secondary>
+  </indexterm>
+        
   <para>
-   Frees memory allocated by <application>libpq</>.
-<synopsis>
-void PQfreemem(void *ptr);
-</synopsis>
-</para>
-
-<para>
-   Frees memory allocated by <application>libpq</>, particularly
-   <function>PQescapeByteaConn</function>,
-   <function>PQescapeBytea</function>,
-   <function>PQunescapeBytea</function>,
-   and <function>PQnotifies</function>.
-   It is particularly important that this function, rather than
-   <function>free()</>, be used on Microsoft Windows.  This is because
-   allocating memory in a DLL and releasing it in the application works
-   only if multithreaded/single-threaded, release/debug, and static/dynamic
-   flags are the same for the DLL and the application.  On non-Microsoft
-   Windows platforms, this function is the same as the standard library
-   function <function>free()</>.
+   <productname>PostgreSQL</productname> offers asynchronous notification
+   via the <command>LISTEN</command> and <command>NOTIFY</command>
+   commands.  A client session registers its interest in a particular
+   notification condition with the <command>LISTEN</command> command (and
+   can stop listening with the <command>UNLISTEN</command> command).  All
+   sessions listening on a particular condition will be notified
+   asynchronously when a <command>NOTIFY</command> command with that
+   condition name is executed by any session.  No additional information
+   is passed from the notifier to the listener.  Thus, typically, any
+   actual data that needs to be communicated is transferred through a
+   database table.  Commonly, the condition name is the same as the
+   associated table, but it is not necessary for there to be any associated
+   table.
   </para>
-  </listitem>
-  </varlistentry>
-  </variablelist>
+        
+  <para>
+   <application>libpq</application> applications submit
+   <command>LISTEN</command> and <command>UNLISTEN</command> commands as
+   ordinary SQL commands.  The arrival of <command>NOTIFY</command>
+   messages can subsequently be detected by calling
+   <function>PQnotifies</function>.<indexterm><primary>PQnotifies</></>
+  </para>
+        
+  <para>
+   The function <function>PQnotifies</function>
+             returns  the next notification from a list of unhandled
+             notification messages received from the server.  It returns a null pointer if
+             there are no pending notifications.  Once a notification is
+             returned from <function>PQnotifies</>, it is considered handled and will be
+             removed from the list of notifications.
+   <synopsis>
+   PGnotify *PQnotifies(PGconn *conn);
    
- </sect2>
-</sect1>
-
-<sect1 id="libpq-async">
-<title>Asynchronous Command Processing</title>
-
-  <indexterm zone="libpq-async">
-   <primary>nonblocking connection</primary>
+   typedef struct pgNotify {
+       char *relname;              /* notification condition name */
+       int  be_pid;                /* process ID of notifying server process */
+       char *extra;                /* notification parameter */
+   } PGnotify;
+   </synopsis>
+   After processing a <structname>PGnotify</structname> object returned
+   by <function>PQnotifies</function>, be sure to free it with
+   <function>PQfreemem</function>.  It is sufficient to free the
+   <structname>PGnotify</structname> pointer; the
+   <structfield>relname</structfield> and <structfield>extra</structfield>
+   fields do not represent separate allocations.  (At present, the
+   <structfield>extra</structfield> field is unused and will always point
+   to an empty string.)
+  </para>
+   
+  <para>
+   <xref linkend="libpq-example-2"> gives a sample program that illustrates
+   the use of asynchronous notification.
+  </para>
+   
+  <para>
+   <function>PQnotifies</function> does not actually read data from the
+   server; it just returns messages previously absorbed by another
+   <application>libpq</application> function.  In prior releases of
+   <application>libpq</application>, the only way to ensure timely receipt
+   of <command>NOTIFY</> messages was to constantly submit commands, even
+   empty ones, and then check <function>PQnotifies</function> after each
+   <function>PQexec</function>.  While this still works, it is deprecated
+   as a waste of processing power.
+  </para>
+   
+  <para>
+   A better way to check for <command>NOTIFY</> messages when you have no
+   useful commands to execute is to call
+   <function>PQconsumeInput</function>, then check
+   <function>PQnotifies</function>.  You can use
+   <function>select()</function> to wait for data to arrive from the
+   server, thereby using no <acronym>CPU</acronym> power unless there is
+   something to do.  (See <function>PQsocket</function> to obtain the file
+   descriptor number to use with <function>select()</function>.) Note that
+   this will work OK whether you submit commands with
+   <function>PQsendQuery</function>/<function>PQgetResult</function> or
+   simply use <function>PQexec</function>.  You should, however, remember
+   to check <function>PQnotifies</function> after each
+   <function>PQgetResult</function> or <function>PQexec</function>, to
+   see if any notifications came in during the processing of the command.
+  </para>
+   
+ </sect1>
+        
+ <sect1 id="libpq-copy">
+  <title>Functions Associated with the <command>COPY</command> Command</title>
+        
+  <indexterm zone="libpq-copy">
+   <primary>COPY</primary>
+   <secondary>with libpq</secondary>
   </indexterm>
+        
+  <para>
+   The <command>COPY</command> command in
+   <productname>PostgreSQL</productname> has options to read from or write
+   to the network connection used by <application>libpq</application>.
+   The functions described in this section allow applications to take
+   advantage of this capability by supplying or consuming copied data.
+  </para>
+        
+  <para>
+   The overall process is that the application first issues the SQL
+   <command>COPY</command> command via <function>PQexec</function> or one
+   of the equivalent functions.  The response to this (if there is no
+   error in the command) will be a <structname>PGresult</> object bearing
+   a status code of <literal>PGRES_COPY_OUT</literal> or
+   <literal>PGRES_COPY_IN</literal> (depending on the specified copy
+   direction).  The application should then use the functions of this
+   section to receive or transmit data rows.  When the data transfer is
+   complete, another <structname>PGresult</> object is returned to indicate
+   success or failure of the transfer.  Its status will be
+   <literal>PGRES_COMMAND_OK</literal> for success or
+   <literal>PGRES_FATAL_ERROR</literal> if some problem was encountered.
+   At this point further SQL commands can be issued via
+   <function>PQexec</function>.  (It is not possible to execute other SQL
+   commands using the same connection while the <command>COPY</command>
+   operation is in progress.)
+  </para>
+  
+  <para>
+   If a <command>COPY</command> command is issued via
+   <function>PQexec</function> in a string that could contain additional
+   commands, the application must continue fetching results via
+   <function>PQgetResult</> after completing the <command>COPY</command>
+   sequence.  Only when <function>PQgetResult</> returns
+   <symbol>NULL</symbol> is it certain that the <function>PQexec</function>
+   command string is done and it is safe to issue more commands.
+  </para>
+  
+  <para>
+   The functions of this section should be executed only after obtaining
+   a result status of <literal>PGRES_COPY_OUT</literal> or
+   <literal>PGRES_COPY_IN</literal> from <function>PQexec</function> or
+   <function>PQgetResult</function>.
+  </para>
+  
+  <para>
+   A <structname>PGresult</> object bearing one of these status values
+   carries some additional data about the <command>COPY</command> operation
+   that is starting.  This additional data is available using functions
+   that are also used in connection with query results:
+        
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQnfields</function>
+      <indexterm>
+       <primary>PQnfields</primary>
+       <secondary>with COPY</secondary>
+      </indexterm>
+     </term>
 
-<para>
-The <function>PQexec</function> function is adequate for submitting commands in
-normal, synchronous
-applications.  It has a couple of deficiencies, however, that can be of importance to some users:
-
-<itemizedlist>
-<listitem>
-<para>
-<function>PQexec</function> waits for the command to be completed.  The application might have other
-work to do (such as maintaining a user interface), in which case it won't
-want to block waiting for the response.
-</para>
-</listitem>
-<listitem>
-<para>
-Since the execution of the client application is suspended while it
-waits for the result, it is hard for the application to decide that it
-would like to try to cancel the ongoing command.  (It can be done from
-a signal handler, but not otherwise.)
-</para>
-</listitem>
-<listitem>
-<para>
-<function>PQexec</function> can return only one <structname>PGresult</structname> structure.  If the submitted command
-string contains multiple <acronym>SQL</acronym> commands, all but the last <structname>PGresult</structname> are
-discarded by <function>PQexec</function>.
-</para>
-</listitem>
-</itemizedlist>
-</para>
-
-<para>
-Applications that do not like these limitations can instead use the
-underlying functions that <function>PQexec</function> is built from:
-<function>PQsendQuery</function> and <function>PQgetResult</function>.
-There are also
-<function>PQsendQueryParams</function>,
-<function>PQsendPrepare</function>,
-<function>PQsendQueryPrepared</function>,
-<function>PQsendDescribePrepared</function>, and
-<function>PQsendDescribePortal</function>,
-which can be used with <function>PQgetResult</function> to duplicate the
-functionality of
-<function>PQexecParams</function>,
-<function>PQprepare</function>,
-<function>PQexecPrepared</function>,
-<function>PQdescribePrepared</function>, and
-<function>PQdescribePortal</function>
-respectively.
-
-<variablelist>
-<varlistentry>
-<term><function>PQsendQuery</function><indexterm><primary>PQsendQuery</></></term>
-<listitem>
-<para>
-          Submits a command to the server without
-          waiting for the result(s).  1 is returned if the command was
-          successfully dispatched and 0 if not (in which case, use
-          <function>PQerrorMessage</> to get more information about the failure).
-<synopsis>
-int PQsendQuery(PGconn *conn, const char *command);
-</synopsis>
-
-          After successfully calling <function>PQsendQuery</function>, call
-          <function>PQgetResult</function> one or more
-          times to obtain the results.  <function>PQsendQuery</function> cannot be called
-          again (on the same connection) until <function>PQgetResult</function> has returned a null pointer,
-          indicating that the command is done.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQsendQueryParams</function><indexterm><primary>PQsendQueryParams</></></term>
-<listitem>
-<para>
-          Submits a command and separate parameters to the server without
-          waiting for the result(s).
-<synopsis>
-int PQsendQueryParams(PGconn *conn,
-                      const char *command,
-                      int nParams,
-                      const Oid *paramTypes,
-                      const char * const *paramValues,
-                      const int *paramLengths,
-                      const int *paramFormats,
-                      int resultFormat);
-</synopsis>
-
-        This is equivalent to <function>PQsendQuery</function> except that
-        query parameters can be specified separately from the query string.
-        The function's parameters are handled identically to
-        <function>PQexecParams</function>.  Like
-        <function>PQexecParams</function>, it will not work on 2.0-protocol
-        connections, and it allows only one command in the query string.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQsendPrepare</><indexterm><primary>PQsendPrepare</></></term>
-<listitem>
-<para>
-        Sends a request to create a prepared statement with the given
-        parameters, without waiting for completion.
-<synopsis>
-int PQsendPrepare(PGconn *conn,
-                  const char *stmtName,
-                  const char *query,
-                  int nParams,
-                  const Oid *paramTypes);
-</synopsis>
-
-        This is an asynchronous version of <function>PQprepare</>: it
-        returns 1 if it was able to dispatch the request, and 0 if not.
-        After a successful call, call <function>PQgetResult</function>
-        to determine whether the server successfully created the prepared
-        statement.
-        The function's parameters are handled identically to
-        <function>PQprepare</function>.  Like
-        <function>PQprepare</function>, it will not work on 2.0-protocol
-        connections.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQsendQueryPrepared</function><indexterm><primary>PQsendQueryPrepared</></></term>
-<listitem>
-<para>
-          Sends a request to execute a prepared statement with given
-          parameters, without waiting for the result(s).
-<synopsis>
-int PQsendQueryPrepared(PGconn *conn,
-                        const char *stmtName,
-                        int nParams,
-                        const char * const *paramValues,
-                        const int *paramLengths,
-                        const int *paramFormats,
-                        int resultFormat);
-</synopsis>
-
-        This is similar to <function>PQsendQueryParams</function>, but the
-        command to be executed is specified by naming a previously-prepared
-        statement, instead of giving a query string.
-        The function's parameters are handled identically to
-        <function>PQexecPrepared</function>.  Like
-        <function>PQexecPrepared</function>, it will not work on 2.0-protocol
-        connections.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQsendDescribePrepared</><indexterm><primary>PQsendDescribePrepared</></></term>
-<listitem>
-<para>
-        Submits a request to obtain information about the specified
-        prepared statement, without waiting for completion.
-<synopsis>
-int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
-</synopsis>
+     <listitem>
+      <para>
+       Returns the number of columns (fields) to be copied.
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQbinaryTuples</function>
+      <indexterm>
+       <primary>PQbinaryTuples</primary>
+       <secondary>with COPY</secondary>
+      </indexterm>
+     </term>
 
-        This is an asynchronous version of <function>PQdescribePrepared</>: it
-        returns 1 if it was able to dispatch the request, and 0 if not.
-        After a successful call, call <function>PQgetResult</function>
-        to obtain the results.
-        The function's parameters are handled identically to
-        <function>PQdescribePrepared</function>.  Like
-        <function>PQdescribePrepared</function>, it will not work on 2.0-protocol
-        connections.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQsendDescribePortal</><indexterm><primary>PQsendDescribePortal</></></term>
-<listitem>
-<para>
-        Submits a request to obtain information about the specified
-        portal, without waiting for completion.
-<synopsis>
-int PQsendDescribePortal(PGconn *conn, const char *portalName);
-</synopsis>
+     <listitem>
+      <para>
+       0 indicates the overall copy format is textual (rows separated by
+       newlines, columns separated by separator characters, etc).  1
+       indicates the overall copy format is binary.  See <xref
+       linkend="sql-copy" endterm="sql-copy-title"> for more information.
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQfformat</function>
+      <indexterm>
+       <primary>PQfformat</primary>
+       <secondary>with COPY</secondary>
+      </indexterm>
+     </term>
 
-        This is an asynchronous version of <function>PQdescribePortal</>: it
-        returns 1 if it was able to dispatch the request, and 0 if not.
-        After a successful call, call <function>PQgetResult</function>
-        to obtain the results.
-        The function's parameters are handled identically to
-        <function>PQdescribePortal</function>.  Like
-        <function>PQdescribePortal</function>, it will not work on 2.0-protocol
-        connections.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQgetResult</function><indexterm><primary>PQgetResult</></></term>
-<listitem>
-<para>
-          Waits for the next result from a prior
-          <function>PQsendQuery</function>,
-          <function>PQsendQueryParams</function>,
-          <function>PQsendPrepare</function>, or
-          <function>PQsendQueryPrepared</function> call,
-          and returns it.  A null pointer is returned when the command is complete
-          and there will be no more results.
-<synopsis>
-PGresult *PQgetResult(PGconn *conn);
-</synopsis>
-</para>
-
-<para>
-          <function>PQgetResult</function> must be called repeatedly until it returns a null pointer,
-          indicating that the command is done.  (If called when no command is
-          active, <function>PQgetResult</function> will just return a null pointer at once.)
-          Each non-null result from <function>PQgetResult</function> should be processed using
-          the same <structname>PGresult</> accessor functions previously described.
-          Don't forget to free each result object with <function>PQclear</function> when done with it.
-          Note that <function>PQgetResult</function> will block only if a command is active and the
-          necessary response data has not yet been read by <function>PQconsumeInput</function>.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-Using <function>PQsendQuery</function> and <function>PQgetResult</function>
-solves one of <function>PQexec</function>'s problems:
-If a command string contains multiple <acronym>SQL</acronym> commands, the results of those
-commands can be obtained individually.  (This allows a simple form of
-overlapped processing, by the way: the client can be handling the
-results of one command while the server is still working on later
-queries in the same command string.)  However, calling <function>PQgetResult</function> will
-still cause the client to block until the server completes the
-next <acronym>SQL</acronym> command.  This can be avoided by proper use of two
-more functions:
-
-<variablelist>
-<varlistentry>
-<term><function>PQconsumeInput</function><indexterm><primary>PQconsumeInput</></></term>
-<listitem>
-<para>
-          If input is available from the server, consume it.
-<synopsis>
-int PQconsumeInput(PGconn *conn);
-</synopsis>
-</para>
-
-<para>
-<function>PQconsumeInput</function> normally returns 1 indicating <quote>no error</quote>,
-but returns 0 if there was some kind of trouble (in which case
-<function>PQerrorMessage</function> can be consulted).  Note that the result
-does not say 
-whether any input data was actually collected. After calling
-<function>PQconsumeInput</function>, the application can check
-<function>PQisBusy</function> and/or <function>PQnotifies</function> to see if
-their state has changed.
-</para>
-<para>
-<function>PQconsumeInput</function> can be called even if the application is not
-prepared to deal with a result or notification just yet.  The
-function will read available data and save it in a buffer, thereby
-causing a <function>select()</function> read-ready indication to go away.  The
-application can thus use <function>PQconsumeInput</function> to clear the
-<function>select()</function> condition immediately, and then examine the results at leisure.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQisBusy</function><indexterm><primary>PQisBusy</></></term>
-<listitem>
-<para>
-Returns 1 if a command is busy, that is, <function>PQgetResult</function> would block
-waiting for input.  A 0 return indicates that <function>PQgetResult</function> can
-be called with assurance of not blocking.
-<synopsis>
-int PQisBusy(PGconn *conn);
-</synopsis>
-</para>
-
-<para>
-<function>PQisBusy</function> will not itself attempt to read data from the server;
-therefore <function>PQconsumeInput</function> must be invoked first, or the busy
-state will never end.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-A typical application using these functions will have a main loop that uses
-<function>select()</function> or <function>poll()</> to wait for all the
-conditions that it must
-respond to.  One of the conditions will be input available from the server,
-which in terms of <function>select()</function> means readable data on the file
-descriptor identified by <function>PQsocket</function>.
-When the main loop detects input ready, it should call
-<function>PQconsumeInput</function> to read the input.  It can then call
-<function>PQisBusy</function>, followed by <function>PQgetResult</function>
-if <function>PQisBusy</function> returns false (0).  It can also call
-<function>PQnotifies</function> to detect <command>NOTIFY</> messages (see <xref linkend="libpq-notify">).
-</para>
-
-<para>
-A client that uses
-<function>PQsendQuery</function>/<function>PQgetResult</function> can
-also attempt to cancel a command that is still being processed by the
-server; see <xref linkend="libpq-cancel">.  But regardless of the return value
-of <function>PQcancel</function>, the application must continue with the
-normal result-reading sequence using <function>PQgetResult</function>.
-A successful cancellation will simply cause the command to terminate
-sooner than it would have otherwise.
-</para>
-
-<para>
-By using the functions described above, it is possible to avoid blocking
-while waiting for input from the database server.  However, it is still
-possible that the application will block waiting to send output to the
-server.  This is relatively uncommon but can happen if very long SQL commands
-or data values are sent.  (It is much more probable if the application
-sends data via <command>COPY IN</command>, however.)  To prevent this possibility and achieve
-completely nonblocking database operation, the following additional
-functions can be used.
-
-<variablelist>
-<varlistentry>
- <term><function>PQsetnonblocking</function><indexterm><primary>PQsetnonblocking</></></term>
- <listitem>
+     <listitem>
+      <para>
+       Returns the format code (0 for text, 1 for binary) associated with
+       each column of the copy operation.  The per-column format codes
+       will always be zero when the overall copy format is textual, but
+       the binary format can support both text and binary columns.
+       (However, as of the current implementation of <command>COPY</>,
+       only binary columns appear in a binary copy; so the per-column
+       formats always match the overall format at present.)
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+        
+  <note>
    <para>
-    Sets the nonblocking status of the connection.
-<synopsis>
-int PQsetnonblocking(PGconn *conn, int arg);
-</synopsis>
-</para>
-
-<para>
-    Sets the state of the connection to nonblocking if
-    <parameter>arg</parameter> is 1, or
-    blocking if <parameter>arg</parameter> is 0.  Returns 0 if OK, -1 if error.
+    These additional data values are only available when using protocol
+    3.0.  When using protocol 2.0, all these functions will return 0.
    </para>
+  </note>
+        
+  <sect2 id="libpq-copy-send">
+   <title>Functions for Sending <command>COPY</command> Data</title>
+        
    <para>
-    In the nonblocking state, calls to
-    <function>PQsendQuery</function>,
-    <function>PQputline</function>, <function>PQputnbytes</function>,
-    and <function>PQendcopy</function>
-    will not block but instead return an error if they need to be called
-    again.
+    These functions are used to send data during <literal>COPY FROM
+    STDIN</>.  They will fail if called when the connection is not in
+    <literal>COPY_IN</> state.
    </para>
+        
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQputCopyData</function>
+      <indexterm>
+       <primary>PQputCopyData</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Sends data to the server during <literal>COPY_IN</> state.
+       <synopsis>
+        int PQputCopyData(PGconn *conn,
+                          const char *buffer,
+                          int nbytes);
+       </synopsis>
+      </para>
+        
+      <para>
+       Transmits the <command>COPY</command> data in the specified
+       <parameter>buffer</>, of length <parameter>nbytes</>, to the server.
+       The result is 1 if the data was sent, zero if it was not sent
+       because the attempt would block (this case is only possible if the
+       connection is in nonblocking mode), or -1 if an error occurred.
+       (Use <function>PQerrorMessage</function> to retrieve details if
+       the return value is -1.  If the value is zero, wait for write-ready
+       and try again.)
+      </para>
+        
+      <para>
+       The application can divide the <command>COPY</command> data stream
+       into buffer loads of any convenient size.  Buffer-load boundaries
+       have no semantic significance when sending.  The contents of the
+       data stream must match the data format expected by the
+       <command>COPY</> command; see <xref linkend="sql-copy"
+       endterm="sql-copy-title"> for details.
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQputCopyEnd</function>
+      <indexterm>
+       <primary>PQputCopyEnd</primary>
+      </indexterm>
+     </term>
+
+     <listitem>
+      <para>
+       Sends end-of-data indication to the server during <literal>COPY_IN</> state.
+       <synopsis>
+        int PQputCopyEnd(PGconn *conn,
+                         const char *errormsg);
+       </synopsis>
+      </para>
+        
+      <para>
+       Ends the <literal>COPY_IN</> operation successfully if
+       <parameter>errormsg</> is <symbol>NULL</symbol>.  If
+       <parameter>errormsg</> is not <symbol>NULL</symbol> then the
+       <command>COPY</> is forced to fail, with the string pointed to by
+       <parameter>errormsg</> used as the error message.  (One should not
+       assume that this exact error message will come back from the server,
+       however, as the server might have already failed the
+       <command>COPY</> for its own reasons.  Also note that the option
+       to force failure does not work when using pre-3.0-protocol
+       connections.)
+      </para>
+        
+      <para>
+       The result is 1 if the termination data was sent, zero if it was
+       not sent because the attempt would block (this case is only possible
+       if the connection is in nonblocking mode), or -1 if an error
+       occurred.  (Use <function>PQerrorMessage</function> to retrieve
+       details if the return value is -1.  If the value is zero, wait for
+       write-ready and try again.)
+      </para>
+        
+      <para>
+       After successfully calling <function>PQputCopyEnd</>, call
+       <function>PQgetResult</> to obtain the final result status of the
+       <command>COPY</> command.  One can wait for this result to be
+       available in the usual way.  Then return to normal operation.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+        
+  </sect2>
+        
+  <sect2 id="libpq-copy-receive">
+   <title>Functions for Receiving <command>COPY</command> Data</title>
+        
    <para>
-    Note that <function>PQexec</function> does not honor nonblocking mode;
-    if it is called, it will act in blocking fashion anyway.
+    These functions are used to receive data during <literal>COPY TO
+    STDOUT</>.  They will fail if called when the connection is not in
+    <literal>COPY_OUT</> state.
    </para>
- </listitem>
-</varlistentry>
+        
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQgetCopyData</function>
+      <indexterm>
+       <primary>PQgetCopyData</primary>
+      </indexterm>
+     </term>
 
-<varlistentry>
-<term><function>PQisnonblocking</function><indexterm><primary>PQisnonblocking</></></term>
-<listitem>
-<para>
-       Returns the blocking status of the database connection.
-<synopsis>
-int PQisnonblocking(const PGconn *conn);
-</synopsis>
-</para>
-
-<para>
-       Returns 1 if the connection is set to nonblocking mode and
-       0 if blocking.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQflush</function><indexterm><primary>PQflush</></></term>
-<listitem>
-<para>
-Attempts to flush any queued output data to the server.
-Returns 0 if successful (or if the send queue is empty), -1 if it failed for
-some reason, or 1 if it was unable to send all the data in the send queue yet
-(this case can only occur if the connection is nonblocking).
-<synopsis>
-int PQflush(PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-After sending any command or data on a nonblocking connection, call
-<function>PQflush</function>.  If it returns 1, wait for the socket to be
-write-ready and call it again; repeat until it returns 0.  Once
-<function>PQflush</function> returns 0, wait for the socket to be read-ready
-and then read the response as described above.
-</para>
-
-</sect1>
-
-<sect1 id="libpq-cancel">
-<title>Cancelling Queries in Progress</title>
-
-<indexterm zone="libpq-cancel">
- <primary>canceling</primary>
- <secondary>SQL command</secondary>
-</indexterm>
-
-<para>
-A client application can request cancellation of
-a command that is still being processed by the
-server, using the functions described in this section.
-
-<variablelist>
-<varlistentry>
-<term><function>PQgetCancel</function><indexterm><primary>PQgetCancel</></></term>
-<listitem>
-<para>
-          Creates a data structure containing the information needed to cancel
-          a command issued through a particular database connection.
-<synopsis>
-PGcancel *PQgetCancel(PGconn *conn);
-</synopsis>
-</para>
-
-<para>
-<function>PQgetCancel</function> creates a 
-<structname>PGcancel</><indexterm><primary>PGcancel</></> object given
-a <structname>PGconn</> connection object.  It will return NULL if the
-given <parameter>conn</> is NULL or an invalid connection.  The
-<structname>PGcancel</> object is an opaque structure that is not meant
-to be accessed directly by the application; it can only be passed to
-<function>PQcancel</function> or <function>PQfreeCancel</function>.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQfreeCancel</function><indexterm><primary>PQfreeCancel</></></term>
-<listitem>
-<para>
-          Frees a data structure created by <function>PQgetCancel</function>.
-<synopsis>
-void PQfreeCancel(PGcancel *cancel);
-</synopsis>
-</para>
-
-<para>
-<function>PQfreeCancel</function> frees a data object previously created
-by <function>PQgetCancel</function>.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQcancel</function><indexterm><primary>PQcancel</></></term>
-<listitem>
-<para>
-          Requests that the server abandon
-          processing of the current command.
-<synopsis>
-int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
-</synopsis>
-</para>
-
-<para>
-The return value is 1 if the cancel request was successfully
-dispatched and 0 if not.  If not, <parameter>errbuf</> is filled with an error
-message explaining why not.  <parameter>errbuf</> must be a char array of size
-<parameter>errbufsize</> (the recommended size is 256 bytes).
-</para>
-
-<para>
-Successful dispatch is no guarantee that the request will have any effect,
-however.  If the cancellation is effective, the current command will terminate
-early and return an error result.  If the cancellation fails (say, because the
-server was already done processing the command), then there will be no visible
-result at all.
-</para>
-
-<para>
-<function>PQcancel</function> can safely be invoked from a signal handler,
-if the <parameter>errbuf</> is a local variable in the signal handler.  The
-<structname>PGcancel</> object is read-only as far as
-<function>PQcancel</function> is concerned, so it can also be invoked from a
-thread that is separate from the one manipulating the <structname>PGconn</>
-object.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-<variablelist>
-<varlistentry>
-<term><function>PQrequestCancel</function><indexterm><primary>PQrequestCancel</></></term>
-<listitem>
-<para>
-          Requests that the server abandon
-          processing of the current command.
-<synopsis>
-int PQrequestCancel(PGconn *conn);
-</synopsis>
-</para>
-
-<para>
-<function>PQrequestCancel</function> is a deprecated variant of
-<function>PQcancel</function>.  It operates directly on the
-<structname>PGconn</> object, and in case of failure stores the
-error message in the <structname>PGconn</> object (whence it can be
-retrieved by <function>PQerrorMessage</function>).  Although the
-functionality is the same, this approach creates hazards for multiple-thread
-programs and signal handlers, since it is possible that overwriting the
-<structname>PGconn</>'s error message will mess up the operation currently
-in progress on the connection.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-</sect1>
-
-<sect1 id="libpq-fastpath">
-<title>The Fast-Path Interface</title>
-
-<indexterm zone="libpq-fastpath">
- <primary>fast path</primary>
-</indexterm>
-
-<para>
-<productname>PostgreSQL</productname> provides a fast-path interface to send
-simple function calls to the server.
-</para>
-
-<tip>
-<para>
-This interface is somewhat obsolete, as one can achieve similar performance
-and greater functionality by setting up a prepared statement to define the
-function call.  Then, executing the statement with binary transmission of
-parameters and results substitutes for a fast-path function call.
-</para>
-</tip>
-
-<para>
-The function <function>PQfn</function><indexterm><primary>PQfn</></>
-requests execution of a server function via the fast-path interface:
-<synopsis>
-PGresult *PQfn(PGconn *conn,
-               int fnid,
-               int *result_buf,
-               int *result_len,
-               int result_is_int,
-               const PQArgBlock *args,
-               int nargs);
+     <listitem>
+      <para>
+       Receives data from the server during <literal>COPY_OUT</> state.
+       <synopsis>
+        int PQgetCopyData(PGconn *conn,
+                          char **buffer,
+                          int async);
+       </synopsis>
+      </para>
+        
+      <para>
+       Attempts to obtain another row of data from the server during a
+       <command>COPY</command>.  Data is always returned one data row at
+       a time; if only a partial row is available, it is not returned.
+       Successful return of a data row involves allocating a chunk of
+       memory to hold the data.  The <parameter>buffer</> parameter must
+       be non-<symbol>NULL</symbol>.  <parameter>*buffer</> is set to
+       point to the allocated memory, or to <symbol>NULL</symbol> in cases
+       where no buffer is returned.  A non-<symbol>NULL</symbol> result
+       buffer must be freed using <function>PQfreemem</> when no longer
+       needed.
+      </para>
+        
+      <para>
+       When a row is successfully returned, the return value is the number
+       of data bytes in the row (this will always be greater than zero).
+       The returned string is always null-terminated, though this is
+       probably only useful for textual <command>COPY</command>.  A result
+       of zero indicates that the <command>COPY</command> is still in
+       progress, but no row is yet available (this is only possible when
+       <parameter>async</> is true).  A result of -1 indicates that the
+       <command>COPY</command> is done.  A result of -2 indicates that an
+       error occurred (consult <function>PQerrorMessage</> for the reason).
+      </para>
+        
+      <para>
+       When <parameter>async</> is true (not zero),
+       <function>PQgetCopyData</> will not block waiting for input; it
+       will return zero if the <command>COPY</command> is still in progress
+       but no complete row is available.  (In this case wait for read-ready
+       and then call <function>PQconsumeInput</> before calling
+       <function>PQgetCopyData</> again.)  When <parameter>async</> is
+       false (zero), <function>PQgetCopyData</> will block until data is
+       available or the operation completes.
+      </para>
+        
+      <para>
+       After <function>PQgetCopyData</> returns -1, call
+       <function>PQgetResult</> to obtain the final result status of the
+       <command>COPY</> command.  One can wait for this result to be
+       available in the usual way.  Then return to normal operation.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+        
+  </sect2>
+        
+  <sect2 id="libpq-copy-deprecated">
+   <title>Obsolete Functions for <command>COPY</command></title>
+        
+   <para>
+    These functions represent older methods of handling <command>COPY</>.
+    Although they still work, they are deprecated due to poor error handling,
+    inconvenient methods of detecting end-of-data, and lack of support for binary
+    or nonblocking transfers.
+   </para>
+        
+   <variablelist>
+    <varlistentry>
+     <term>
+      <function>PQgetline</function>
+      <indexterm>
+       <primary>PQgetline</primary>
+      </indexterm>
+     </term>
 
-typedef struct {
-    int len;
-    int isint;
-    union {
-        int *ptr;
-        int integer;
-    } u;
-} PQArgBlock;
-</synopsis>
-</para>
-
-<para>
-     The <parameter>fnid</> argument is the OID of the function to be
-     executed.  <parameter>args</> and <parameter>nargs</> define the
-     parameters to be passed to the function; they must match the declared
-     function argument list.  When the <parameter>isint</> field of a
-     parameter
-     structure is true,
-     the <parameter>u.integer</> value is sent to the server as an integer
-     of the indicated length (this must be 1, 2, or 4 bytes); proper
-     byte-swapping occurs.  When <parameter>isint</> is false, the
-     indicated number of bytes at <parameter>*u.ptr</> are sent with no
-     processing; the data must be in the format expected by the server for
-     binary transmission of the function's argument data type.
-     <parameter>result_buf</parameter> is the buffer in which
-     to place the return value.  The caller must  have  allocated
-     sufficient space to store the return value.  (There is no check!)
-     The actual result length will be returned in the integer pointed
-     to  by  <parameter>result_len</parameter>.
-     If a 1, 2, or 4-byte integer result is expected, set
-     <parameter>result_is_int</parameter> to 1, otherwise set it to 0.
-     Setting <parameter>result_is_int</parameter> to 1
-     causes <application>libpq</> to byte-swap the value if necessary, so that
-     it is
-     delivered as a proper <type>int</type> value for the client machine.  When
-     <parameter>result_is_int</> is 0, the binary-format byte string sent by
-     the server is returned unmodified.
-</para>
-
-<para>
-<function>PQfn</function> always returns a valid <structname>PGresult</structname> pointer. The result status
-should be checked before the result is used.   The
-caller is responsible for  freeing  the  <structname>PGresult</structname>  with
-<function>PQclear</function> when it is no longer needed.
-</para>
-
-<para>
-Note that it is not possible to handle null arguments, null results, nor
-set-valued results when using this interface.
-</para>
-
-</sect1>
-
-<sect1 id="libpq-notify">
-<title>Asynchronous Notification</title>
+     <listitem>
+      <para>
+       Reads  a  newline-terminated  line  of  characters (transmitted
+       by the server) into a buffer string of size <parameter>length</>.
+       <synopsis>
+        int PQgetline(PGconn *conn,
+                      char *buffer,
+                      int length);
+       </synopsis>
+      </para>
+        
+      <para>
+       This function copies up to <parameter>length</>-1 characters into
+       the buffer and converts the terminating newline into a zero byte.
+       <function>PQgetline</function> returns <symbol>EOF</symbol> at the
+       end of input, 0 if the entire line has been read, and 1 if the
+       buffer is full but the terminating newline has not yet been read.
+       </para>
+       <para>
+       Note that the application must check to see if a new line consists
+       of  the  two characters  <literal>\.</literal>, which  indicates
+       that the server has finished sending the results  of  the
+       <command>COPY</command> command.  If  the  application might receive
+       lines that are more than <parameter>length</>-1  characters  long,
+       care is needed to be sure it recognizes the <literal>\.</literal>
+       line correctly (and does not, for example, mistake the end of a
+       long data line for a terminator line).
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQgetlineAsync</function>
+      <indexterm>
+       <primary>PQgetlineAsync</primary>
+      </indexterm>
+     </term>
 
-  <indexterm zone="libpq-notify">
-   <primary>NOTIFY</primary>
-   <secondary>in libpq</secondary>
-  </indexterm>
+     <listitem>
+      <para>
+       Reads a row of <command>COPY</command> data (transmitted  by the
+       server) into a buffer without blocking.
+       <synopsis>
+        int PQgetlineAsync(PGconn *conn,
+                           char *buffer,
+                           int bufsize);
+       </synopsis>
+      </para>
+        
+      <para>
+       This function is similar to <function>PQgetline</function>, but it can be used
+       by applications
+       that must read <command>COPY</command> data asynchronously, that is, without blocking.
+       Having issued the <command>COPY</command> command and gotten a <literal>PGRES_COPY_OUT</literal>
+       response, the
+       application should call <function>PQconsumeInput</function> and
+       <function>PQgetlineAsync</function> until the
+       end-of-data signal is detected.
+       </para>
+       <para>
+       Unlike <function>PQgetline</function>, this function takes
+       responsibility for detecting end-of-data.
+      </para>
 
-<para>
-<productname>PostgreSQL</productname> offers asynchronous notification via the
-<command>LISTEN</command> and <command>NOTIFY</command> commands.  A client session registers its interest in a particular
-notification condition with the <command>LISTEN</command> command (and can stop listening
-with the <command>UNLISTEN</command> command).  All sessions listening on a
-particular condition will be notified asynchronously when a <command>NOTIFY</command> command with that
-condition name is executed by any session.  No additional information is
-passed from the notifier to the listener.  Thus, typically, any actual data
-that needs to be communicated is transferred through a database table.
-Commonly, the condition name is the same as the associated table, but it is
-not necessary for there to be any associated table.
-</para>
-
-<para>
-<application>libpq</application> applications submit
-<command>LISTEN</command> and <command>UNLISTEN</command> commands as
-ordinary SQL commands.  The arrival of <command>NOTIFY</command>
-messages can subsequently be detected by calling
-<function>PQnotifies</function>.<indexterm><primary>PQnotifies</></>
-</para>
-
-<para>
-The function <function>PQnotifies</function>
-          returns  the next notification from a list of unhandled
-          notification messages received from the server.  It returns a null pointer if
-          there are no pending notifications.  Once a notification is
-          returned from <function>PQnotifies</>, it is considered handled and will be
-          removed from the list of notifications.
-<synopsis>
-PGnotify *PQnotifies(PGconn *conn);
+      <para>
+       On each call, <function>PQgetlineAsync</function> will return data if a
+       complete data row is available in <application>libpq</>'s input buffer.
+       Otherwise, no data is returned until the rest of the row arrives.
+       The function returns -1 if the end-of-copy-data marker has been recognized,
+       or 0 if no data is available, or a positive number giving the number of
+       bytes of data returned.  If -1 is returned, the caller must next call
+       <function>PQendcopy</function>, and then return to normal processing.
+      </para>
 
-typedef struct pgNotify {
-    char *relname;              /* notification condition name */
-    int  be_pid;                /* process ID of notifying server process */
-    char *extra;                /* notification parameter */
-} PGnotify;
-</synopsis>
-After processing a <structname>PGnotify</structname> object returned by
-<function>PQnotifies</function>, be sure to free it with
-<function>PQfreemem</function>.  It is sufficient to free the
-<structname>PGnotify</structname> pointer; the
-<structfield>relname</structfield> and <structfield>extra</structfield> fields
-do not represent separate allocations.
-(At present, the <structfield>extra</structfield> field is unused and will
-always point to an empty string.)
-</para>
-
-<para>
-<xref linkend="libpq-example-2"> gives a sample program that illustrates the use
-of asynchronous notification.
-</para>
-
-<para>
-<function>PQnotifies</function> does not actually read data from the server; it just
-returns messages previously absorbed by another <application>libpq</application>
-function.  In prior releases of <application>libpq</application>, the only way
-to ensure timely receipt of <command>NOTIFY</> messages was to constantly submit commands,
-even empty ones, and then check <function>PQnotifies</function> after each
-<function>PQexec</function>.  While this still works, it is
-deprecated as a waste of processing power.
-</para>
-
-<para>
-A better way to check for <command>NOTIFY</>
-messages when you have no useful commands to execute is to call
-<function>PQconsumeInput</function>, then check
-<function>PQnotifies</function>.
-You can use <function>select()</function> to wait for data to
-arrive from the server, thereby using no <acronym>CPU</acronym> power unless there is something
-to do.  (See <function>PQsocket</function> to obtain the file descriptor
-number to use with <function>select()</function>.)
-Note that this will work OK whether you submit commands with
-<function>PQsendQuery</function>/<function>PQgetResult</function> or simply
-use <function>PQexec</function>.  You should, however, remember to
-check <function>PQnotifies</function> after each
-<function>PQgetResult</function> or <function>PQexec</function>, to see
-if any notifications came in during the processing of the command.
-</para>
-
-</sect1>
-
-<sect1 id="libpq-copy">
-<title>Functions Associated with the <command>COPY</command> Command</title>
-
-<indexterm zone="libpq-copy">
- <primary>COPY</primary>
- <secondary>with libpq</secondary>
-</indexterm>
-
-<para>
- The <command>COPY</command> command in <productname>PostgreSQL</productname>
- has options to read from or write to the network connection used by
- <application>libpq</application>.  The functions described in this section
- allow applications to take advantage of this capability by supplying or
- consuming copied data.
-</para>
-
-<para>
- The overall process is that the application first issues the SQL
- <command>COPY</command> command via <function>PQexec</function> or one
- of the equivalent functions.  The response to this (if there is no error
- in the command) will be a <structname>PGresult</> object bearing a status
- code of <literal>PGRES_COPY_OUT</literal> or <literal>PGRES_COPY_IN</literal>
- (depending on the specified copy direction).  The application should then
- use the functions of this section to receive or transmit data rows.
- When the data transfer is complete, another <structname>PGresult</> object
- is returned to indicate success or failure of the transfer.  Its status
- will be <literal>PGRES_COMMAND_OK</literal> for success or
- <literal>PGRES_FATAL_ERROR</literal> if some problem was encountered.
- At this point further SQL commands can be issued via
- <function>PQexec</function>.  (It is not possible to execute other SQL
- commands using the same connection while the <command>COPY</command>
- operation is in progress.)
-</para>
-
-<para>
- If a <command>COPY</command> command is issued via
- <function>PQexec</function> in a string that could contain additional
- commands, the application must continue fetching results via
- <function>PQgetResult</> after completing the <command>COPY</command>
- sequence.  Only when <function>PQgetResult</> returns <symbol>NULL</symbol> is it certain
- that the <function>PQexec</function> command string is done and it is
- safe to issue more commands.
-</para>
-
-<para>
- The functions of this section should be executed only after obtaining a
- result status of <literal>PGRES_COPY_OUT</literal> or
- <literal>PGRES_COPY_IN</literal> from <function>PQexec</function> or
- <function>PQgetResult</function>.
-</para>
-
-<para>
- A <structname>PGresult</> object bearing one of these status values
- carries some additional data about the <command>COPY</command> operation that
- is starting.  This additional data is available using functions that are
- also used in connection with query results:
-
-<variablelist>
-<varlistentry>
-<term><function>PQnfields</function><indexterm><primary>PQnfields</><secondary>with COPY</></></term>
-<listitem>
-<para>
-          Returns the number of columns (fields) to be copied.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQbinaryTuples</function><indexterm><primary>PQbinaryTuples</><secondary>with COPY</></></term>
-<listitem>
-<para>
-                0 indicates the overall copy format is textual (rows
-                separated by newlines, columns separated by separator
-                characters, etc).
-                1 indicates the overall copy format is binary.
-                See <xref linkend="sql-copy" endterm="sql-copy-title">
-                for more information.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQfformat</function><indexterm><primary>PQfformat</><secondary>with COPY</></></term>
-<listitem>
-<para>
-          Returns the format code (0 for text, 1 for binary) associated
-          with each column of the copy operation.  The per-column format
-          codes will always be zero when the overall copy format is textual,
-          but the binary format can support both text and binary columns.
-          (However, as of the current implementation of <command>COPY</>,
-          only binary columns appear in a binary copy; so the per-column
-          formats always match the overall format at present.)
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<note>
-<para>
-These additional data values are only available when using protocol 3.0.
-When using protocol 2.0, all these functions will return 0.
-</para>
-</note>
-
-<sect2 id="libpq-copy-send">
-  <title>Functions for Sending <command>COPY</command> Data</title>
-
-<para>
- These functions are used to send data during <literal>COPY FROM STDIN</>.
- They will fail if called when the connection is not in <literal>COPY_IN</>
- state.
-</para>
-
-<variablelist>
-<varlistentry>
-<term><function>PQputCopyData</function><indexterm><primary>PQputCopyData</></></term>
-<listitem>
-<para>
- Sends data to the server during <literal>COPY_IN</> state.
-<synopsis>
-int PQputCopyData(PGconn *conn,
-                  const char *buffer,
-                  int nbytes);
-</synopsis>
-</para>
-
-<para>
-Transmits the <command>COPY</command> data in the specified <parameter>buffer</>, of length
-<parameter>nbytes</>, to the server.  The result is 1 if the data was sent,
-zero if it was not sent because the attempt would block (this case is only
-possible if the connection is in nonblocking mode), or -1 if an error occurred.
-(Use <function>PQerrorMessage</function> to retrieve details if the return
-value is -1.  If the value is zero, wait for write-ready and try again.)
-</para>
-
-<para>
-The application can divide the <command>COPY</command> data stream into buffer loads of any
-convenient size.  Buffer-load boundaries have no semantic significance when
-sending.  The contents of the data stream must match the data format expected
-by the <command>COPY</> command; see
-<xref linkend="sql-copy" endterm="sql-copy-title"> for details.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQputCopyEnd</function><indexterm><primary>PQputCopyEnd</></></term>
-<listitem>
-<para>
- Sends end-of-data indication to the server during <literal>COPY_IN</> state.
-<synopsis>
-int PQputCopyEnd(PGconn *conn,
-                 const char *errormsg);
-</synopsis>
-</para>
-
-<para>
-Ends the <literal>COPY_IN</> operation successfully if <parameter>errormsg</>
-is <symbol>NULL</symbol>.  If <parameter>errormsg</> is not <symbol>NULL</symbol> then the <command>COPY</>
-is forced to fail, with the string pointed to by <parameter>errormsg</>
-used as the error message.  (One should not assume that this exact error
-message will come back from the server, however, as the server might have
-already failed the <command>COPY</> for its own reasons.  Also note that the
-option to force failure does not work when using pre-3.0-protocol connections.)
-</para>
-
-<para>
-The result is 1 if the termination data was sent,
-zero if it was not sent because the attempt would block (this case is only
-possible if the connection is in nonblocking mode), or -1 if an error occurred.
-(Use <function>PQerrorMessage</function> to retrieve details if the return
-value is -1.  If the value is zero, wait for write-ready and try again.)
-</para>
-
-<para>
-After successfully calling <function>PQputCopyEnd</>, call
-<function>PQgetResult</> to obtain the final result status of the
-<command>COPY</> command.  One can wait for
-this result to be available in the usual way.  Then return to normal
-operation.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-</sect2>
-
-<sect2 id="libpq-copy-receive">
-  <title>Functions for Receiving <command>COPY</command> Data</title>
-
-<para>
- These functions are used to receive data during <literal>COPY TO STDOUT</>.
- They will fail if called when the connection is not in <literal>COPY_OUT</>
- state.
-</para>
-
-<variablelist>
-<varlistentry>
-<term><function>PQgetCopyData</function><indexterm><primary>PQgetCopyData</></></term>
-<listitem>
-<para>
- Receives data from the server during <literal>COPY_OUT</> state.
-<synopsis>
-int PQgetCopyData(PGconn *conn,
-                  char **buffer,
-                  int async);
-</synopsis>
-</para>
-
-<para>
-Attempts to obtain another row of data from the server during a <command>COPY</command>.
-Data is always returned one data row at a time; if only a partial row
-is available, it is not returned.  Successful return of a data row
-involves allocating a chunk of memory to hold the data.  The
-<parameter>buffer</> parameter must be non-<symbol>NULL</symbol>.  <parameter>*buffer</>
-is set to point to the allocated memory, or to <symbol>NULL</symbol> in cases where no
-buffer is returned.  A non-<symbol>NULL</symbol> result buffer must be freed using
-<function>PQfreemem</> when no longer needed.
-</para>
-
-<para>
-When a row is successfully returned, the return value is the number of
-data bytes in the row (this will always be greater than zero).  The
-returned string is always null-terminated, though this is probably only
-useful for textual <command>COPY</command>.  A result of zero indicates that the <command>COPY</command> is
-still in progress, but no row is yet available (this is only possible
-when <parameter>async</> is true).  A
-result of -1 indicates that the <command>COPY</command> is done.
-A result of -2 indicates that an error occurred (consult
-<function>PQerrorMessage</> for the reason).
-</para>
-
-<para>
-When <parameter>async</> is true (not zero), <function>PQgetCopyData</>
-will not block waiting for input; it will return zero if the <command>COPY</command> is still
-in progress but no complete row is available.  (In this case wait for
-read-ready and then call <function>PQconsumeInput</> before calling
-<function>PQgetCopyData</> again.)  When <parameter>async</> is
-false (zero), <function>PQgetCopyData</> will block until data is available
-or the operation completes.
-</para>
-
-<para>
-After <function>PQgetCopyData</> returns -1, call
-<function>PQgetResult</> to obtain the final result status of the
-<command>COPY</> command.  One can wait for
-this result to be available in the usual way.  Then return to normal
-operation.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-</sect2>
-
-<sect2 id="libpq-copy-deprecated">
-  <title>Obsolete Functions for <command>COPY</command></title>
-
-<para>
- These functions represent older methods of handling <command>COPY</>.
- Although they still work, they are deprecated due to poor error handling,
- inconvenient methods of detecting end-of-data, and lack of support for binary
- or nonblocking transfers.
-</para>
-
-<variablelist>
-<varlistentry>
-<term><function>PQgetline</function><indexterm><primary>PQgetline</></></term>
-<listitem>
-<para>
-          Reads  a  newline-terminated  line  of  characters
-          (transmitted  by the server) into a buffer
-          string of size <parameter>length</>.
-<synopsis>
-int PQgetline(PGconn *conn,
-              char *buffer,
-              int length);
-</synopsis>
-</para>
-
-<para>
-This function copies up to <parameter>length</>-1 characters
-into the buffer and converts
-the terminating newline into a zero byte.
-<function>PQgetline</function> returns <symbol>EOF</symbol> at the end of input, 0 if the
-entire line has been read, and 1 if the buffer is full but the
-terminating newline has not yet been read.
-</para>
-<para>
-Note that the application must check to see if a
-new line consists of  the  two characters  <literal>\.</literal>,
-which  indicates  that the server has finished sending
-the results  of  the <command>COPY</command> command.
-If  the  application might
-receive lines that are more than <parameter>length</>-1  characters  long,
-care is needed to be sure it recognizes the <literal>\.</literal> line correctly
-(and does not, for example, mistake the end of a long data line
-for a terminator line).
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQgetlineAsync</function><indexterm><primary>PQgetlineAsync</></></term>
-<listitem>
-<para>
-          Reads a row of <command>COPY</command> data
-          (transmitted  by the server) into a buffer
-          without blocking.
-<synopsis>
-int PQgetlineAsync(PGconn *conn,
-                   char *buffer,
-                   int bufsize);
-</synopsis>
-</para>
-
-<para>
-This function is similar to <function>PQgetline</function>, but it can be used
-by applications
-that must read <command>COPY</command> data asynchronously, that is, without blocking.
-Having issued the <command>COPY</command> command and gotten a <literal>PGRES_COPY_OUT</literal>
-response, the
-application should call <function>PQconsumeInput</function> and
-<function>PQgetlineAsync</function> until the
-end-of-data signal is detected.
-</para>
-<para>
-Unlike <function>PQgetline</function>, this function takes
-responsibility for detecting end-of-data.
-</para>
-<para>
-On each call, <function>PQgetlineAsync</function> will return data if a
-complete data row is available in <application>libpq</>'s input buffer.
-Otherwise, no data is returned until the rest of the row arrives.
-The function returns -1 if the end-of-copy-data marker has been recognized,
-or 0 if no data is available, or a positive number giving the number of
-bytes of data returned.  If -1 is returned, the caller must next call
-<function>PQendcopy</function>, and then return to normal processing.
-</para>
-<para>
-The data returned will not extend beyond a data-row boundary.  If possible
-a whole row will be returned at one time.  But if the buffer offered by
-the caller is too small to hold a row sent by the server, then a partial
-data row will be returned.  With textual data this can be detected by testing
-whether the last returned byte is <literal>\n</literal> or not.  (In a binary
-<command>COPY</>, actual parsing of the <command>COPY</> data format will be needed to make the
-equivalent determination.)
-The returned string is not null-terminated.  (If you want to add a
-terminating null, be sure to pass a <parameter>bufsize</parameter> one smaller
-than the room actually available.)
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQputline</function><indexterm><primary>PQputline</></></term>
-<listitem>
-<para>
-Sends  a  null-terminated  string  to  the server.
-Returns 0 if OK and <symbol>EOF</symbol> if unable to send the string.
-<synopsis>
-int PQputline(PGconn *conn,
-              const char *string);
-</synopsis>
-</para>
-
-<para>
-The <command>COPY</command> data stream sent by a series of calls to
-<function>PQputline</function> has the same format as that returned by
-<function>PQgetlineAsync</function>, except that applications are not
-obliged to send exactly one data row per <function>PQputline</function>
-call; it is okay to send a partial line or multiple lines per call.
-</para>
-
-<note>
-<para>
-Before <productname>PostgreSQL</productname> protocol 3.0, it was necessary
-for the application to explicitly send the two characters
-<literal>\.</literal> as a final line to indicate to the server that it had
-finished sending <command>COPY</> data.  While this still works, it is deprecated and the
-special meaning of <literal>\.</literal> can be expected to be removed in a
-future release.  It is sufficient to call <function>PQendcopy</function> after
-having sent the actual data.
-</para>
-</note>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQputnbytes</function><indexterm><primary>PQputnbytes</></></term>
-<listitem>
-<para>
-Sends  a  non-null-terminated  string  to  the server.
-Returns 0 if OK and <symbol>EOF</symbol> if unable to send the string.
-<synopsis>
-int PQputnbytes(PGconn *conn,
-                const char *buffer,
-                int nbytes);
-</synopsis>
-</para>
-
-<para>
-This is exactly like <function>PQputline</function>, except that the data
-buffer need not be null-terminated since the number of bytes to send is
-specified directly.  Use this procedure when sending binary data.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQendcopy</function><indexterm><primary>PQendcopy</></></term>
-<listitem>
-<para>
- Synchronizes with the server.
-<synopsis>
-int PQendcopy(PGconn *conn);
-</synopsis>
- This function waits until
- the  server  has  finished  the copying.  It should
- either be issued when the  last  string  has  been
- sent  to  the  server using <function>PQputline</function> or when the
- last string has been  received  from  the  server
- using <function>PGgetline</function>.  It must be issued or the server
- will get <quote>out of sync</quote> with  the client.   Upon
- return from this function, the server is ready to
- receive the next SQL command.
- The return value is 0  on  successful  completion,
- nonzero otherwise.  (Use <function>PQerrorMessage</function> to retrieve
- details if the return value is nonzero.)
-</para>
-
-<para>
-When using <function>PQgetResult</function>, the application should respond to
-a <literal>PGRES_COPY_OUT</literal> result by executing <function>PQgetline</function>
-repeatedly, followed by <function>PQendcopy</function> after the terminator line is seen.
-It should then return to the <function>PQgetResult</function> loop until
-<function>PQgetResult</function> returns a null pointer. Similarly a <literal>PGRES_COPY_IN</literal>
-result is processed by a series of <function>PQputline</function> calls followed by
-<function>PQendcopy</function>, then return to the <function>PQgetResult</function> loop.
-This arrangement will ensure that
-a <command>COPY</command> command embedded in a series of <acronym>SQL</acronym> commands
-will be executed correctly.
-</para>
-
-<para>
-Older applications are likely to submit a <command>COPY</command>
-via <function>PQexec</function> and assume that the transaction is done after
-<function>PQendcopy</function>.
-This will work correctly only if the <command>COPY</command> is the only
-<acronym>SQL</acronym> command in the command string.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-</sect2>
-
-</sect1>
-
-<sect1 id="libpq-control">
-<title>Control Functions</title>
-
-<para>
-These functions control miscellaneous details of
-<application>libpq</>'s behavior.
-</para>
-
-<variablelist>
-<varlistentry>
-<term><function>PQsetErrorVerbosity</function><indexterm><primary>PQsetErrorVerbosity</></></term>
-<listitem>
-<para>
-Determines the verbosity of messages returned by
-<function>PQerrorMessage</> and <function>PQresultErrorMessage</>.
-<synopsis>
-typedef enum {
-    PQERRORS_TERSE,
-    PQERRORS_DEFAULT,
-    PQERRORS_VERBOSE
-} PGVerbosity;
+      <para>
+       The data returned will not extend beyond a data-row boundary.  If possible
+       a whole row will be returned at one time.  But if the buffer offered by
+       the caller is too small to hold a row sent by the server, then a partial
+       data row will be returned.  With textual data this can be detected by testing
+       whether the last returned byte is <literal>\n</literal> or not.  (In a binary
+       <command>COPY</>, actual parsing of the <command>COPY</> data format will be needed to make the
+       equivalent determination.)
+       The returned string is not null-terminated.  (If you want to add a
+       terminating null, be sure to pass a <parameter>bufsize</parameter> one smaller
+       than the room actually available.)
+      </para>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQputline</function>
+      <indexterm>
+       <primary>PQputline</primary>
+      </indexterm>
+     </term>
 
-PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
-</synopsis>
-<function>PQsetErrorVerbosity</> sets the verbosity mode, returning
-the connection's previous setting.  In <firstterm>TERSE</> mode,
-returned messages include severity, primary text, and position only;
-this will normally fit on a single line.  The default mode produces
-messages that include the above plus any detail, hint, or context
-fields (these might span multiple lines).  The <firstterm>VERBOSE</>
-mode includes all available fields.  Changing the verbosity does not
-affect the messages available from already-existing
-<structname>PGresult</> objects, only subsequently-created ones.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQtrace</function><indexterm><primary>PQtrace</></></term>
-<listitem>
-<para>
-          Enables  tracing of the client/server communication to a debugging file stream.
-<synopsis>
-void PQtrace(PGconn *conn, FILE *stream);
-</synopsis>
-</para>
-<note>
-<para>
-On Windows, if the <application>libpq</> library and an application are
-compiled with different flags, this function call will crash the 
-application because the internal representation of the <literal>FILE</> 
-pointers differ.  Specifically, multithreaded/single-threaded,
-release/debug, and static/dynamic flags should be the same for the
-library and all applications using that library.
-</para>
-</note>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQuntrace</function><indexterm><primary>PQuntrace</></></term>
-<listitem>
-<para>
-          Disables tracing started by <function>PQtrace</function>.
-<synopsis>
-void PQuntrace(PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-</sect1>
-
-<sect1 id="libpq-misc">
-<title>Miscellaneous Functions</title>
-
-<para>
-As always, there are some functions that just don't fit anywhere.
-</para>
-
-<variablelist>
-<varlistentry>
-<term><function>PQencryptPassword</function><indexterm><primary>PQencryptPassword</></></term>
-<listitem>
-<para>
-Prepares the encrypted form of a <productname>PostgreSQL</> password.
-<synopsis>
-char * PQencryptPassword(const char *passwd, const char *user);
-</synopsis>
-This function is intended to be used by client
-applications that wish to send commands like
-<literal>ALTER USER joe PASSWORD 'pwd'</>.
-It is good practice not to send the original cleartext password in such a
-command, because it might be exposed in command logs, activity displays,
-and so on.  Instead, use this function to convert the password to encrypted
-form before it is sent.  The arguments are the cleartext password, and the SQL
-name of the user it is for.  The return value is a string allocated by
-<function>malloc</function>, or <symbol>NULL</symbol> if out of memory.
-The caller can assume the string doesn't contain any special
-characters that would require escaping.  Use <function>PQfreemem</> to free
-the result when done with it.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-</sect1>
-
-<sect1 id="libpq-notice-processing">
-<title>Notice Processing</title>
-
-<indexterm zone="libpq-notice-processing">
- <primary>notice processing</primary>
- <secondary>in libpq</secondary>
-</indexterm>
-
-<para>
-Notice and warning messages generated by the server are not returned by the
-query execution functions, since they do not imply failure of the query.
-Instead they are passed to a notice handling function, and execution continues
-normally after the handler returns.  The default notice handling function
-prints the message on <filename>stderr</filename>, but the application can
-override this behavior by supplying its own handling function.
-</para>
-
-<para>
-For historical reasons, there are two levels of notice handling, called the
-notice receiver and notice processor.  The default behavior is for the notice
-receiver to format the notice and pass a string to the notice processor
-for printing.  However, an application that chooses to provide its own notice
-receiver will typically ignore the notice processor layer and just do all the
-work in the notice receiver.
-</para>
-
-<para>
-The function <function>PQsetNoticeReceiver</function>
-<indexterm><primary>notice receiver</></><indexterm><primary>PQsetNoticeReceiver</></>
-sets or examines the current notice receiver for a connection object.
-Similarly, <function>PQsetNoticeProcessor</function>
-<indexterm><primary>notice processor</></><indexterm><primary>PQsetNoticeProcessor</></>
-sets or examines the current notice processor.
+     <listitem>
+      <para>
+       Sends  a  null-terminated  string  to  the server.  Returns 0 if
+       OK and <symbol>EOF</symbol> if unable to send the string.
+       <synopsis>
+        int PQputline(PGconn *conn,
+                      const char *string);
+       </synopsis>
+      </para>
+        
+      <para>
+       The <command>COPY</command> data stream sent by a series of calls
+       to <function>PQputline</function> has the same format as that
+       returned by <function>PQgetlineAsync</function>, except that
+       applications are not obliged to send exactly one data row per
+       <function>PQputline</function> call; it is okay to send a partial
+       line or multiple lines per call.
+      </para>
+        
+      <note>
+       <para>
+        Before <productname>PostgreSQL</productname> protocol 3.0, it was necessary
+        for the application to explicitly send the two characters
+        <literal>\.</literal> as a final line to indicate to the server that it had
+        finished sending <command>COPY</> data.  While this still works, it is deprecated and the
+        special meaning of <literal>\.</literal> can be expected to be removed in a
+        future release.  It is sufficient to call <function>PQendcopy</function> after
+        having sent the actual data.
+       </para>
+      </note>
+     </listitem>
+    </varlistentry>
+        
+    <varlistentry>
+     <term>
+      <function>PQputnbytes</function>
+      <indexterm>
+       <primary>PQputnbytes</primary>
+      </indexterm>
+     </term>
 
-<synopsis>
-typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
+     <listitem>
+      <para>
+       Sends  a  non-null-terminated  string  to  the server.  Returns
+       0 if OK and <symbol>EOF</symbol> if unable to send the string.
+       <synopsis>
+        int PQputnbytes(PGconn *conn,
+                        const char *buffer,
+                        int nbytes);
+       </synopsis>
+      </para>
+       
+      <para>
+       This is exactly like <function>PQputline</function>, except that the data
+       buffer need not be null-terminated since the number of bytes to send is
+       specified directly.  Use this procedure when sending binary data.
+      </para>
+     </listitem>
+    </varlistentry>
+       
+    <varlistentry>
+     <term>
+      <function>PQendcopy</function>
+      <indexterm>
+       <primary>PQendcopy</primary>
+      </indexterm>
+     </term>
 
-PQnoticeReceiver
-PQsetNoticeReceiver(PGconn *conn,
-                    PQnoticeReceiver proc,
-                    void *arg);
+     <listitem>
+      <para>
+       Synchronizes with the server.
+       <synopsis>
+        int PQendcopy(PGconn *conn);
+       </synopsis>
+       This function waits until the  server  has  finished  the copying.
+       It should either be issued when the  last  string  has  been sent
+       to  the  server using <function>PQputline</function> or when the
+       last string has been  received  from  the  server using
+       <function>PGgetline</function>.  It must be issued or the server
+       will get <quote>out of sync</quote> with  the client.   Upon return
+       from this function, the server is ready to receive the next SQL
+       command.  The return value is 0  on  successful  completion,
+       nonzero otherwise.  (Use <function>PQerrorMessage</function> to
+       retrieve details if the return value is nonzero.)
+      </para>
+       
+      <para>
+       When using <function>PQgetResult</function>, the application should
+       respond to a <literal>PGRES_COPY_OUT</literal> result by executing
+       <function>PQgetline</function> repeatedly, followed by
+       <function>PQendcopy</function> after the terminator line is seen.
+       It should then return to the <function>PQgetResult</function> loop
+       until <function>PQgetResult</function> returns a null pointer.
+       Similarly a <literal>PGRES_COPY_IN</literal> result is processed
+       by a series of <function>PQputline</function> calls followed by
+       <function>PQendcopy</function>, then return to the
+       <function>PQgetResult</function> loop.  This arrangement will
+       ensure that a <command>COPY</command> command embedded in a series
+       of <acronym>SQL</acronym> commands will be executed correctly.
+      </para>
+       
+      <para>
+       Older applications are likely to submit a <command>COPY</command>
+       via <function>PQexec</function> and assume that the transaction
+       is done after <function>PQendcopy</function>.  This will work
+       correctly only if the <command>COPY</command> is the only
+       <acronym>SQL</acronym> command in the command string.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+       
+  </sect2>
+        
+ </sect1>
+        
+ <sect1 id="libpq-control">
+  <title>Control Functions</title>
+        
+  <para>
+   These functions control miscellaneous details of <application>libpq</>'s
+   behavior.
+  </para>
+        
+  <variablelist>
+   <varlistentry>
+    <term>
+     <function>PQsetErrorVerbosity</function>
+     <indexterm>
+      <primary>PQsetErrorVerbosity</primary>
+     </indexterm>
+    </term>
+
+   <listitem>
+    <para>
+     Determines the verbosity of messages returned by
+     <function>PQerrorMessage</> and <function>PQresultErrorMessage</>.
+     <synopsis>
+      typedef enum {
+          PQERRORS_TERSE,
+          PQERRORS_DEFAULT,
+          PQERRORS_VERBOSE
+      } PGVerbosity;
+        
+      PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
+     </synopsis>
+
+     <function>PQsetErrorVerbosity</> sets the verbosity mode, returning
+     the connection's previous setting.  In <firstterm>TERSE</> mode,
+     returned messages include severity, primary text, and position only;
+     this will normally fit on a single line.  The default mode produces
+     messages that include the above plus any detail, hint, or context
+     fields (these might span multiple lines).  The <firstterm>VERBOSE</>
+     mode includes all available fields.  Changing the verbosity does not
+     affect the messages available from already-existing
+     <structname>PGresult</> objects, only subsequently-created ones.
+    </para>
+   </listitem>
+  </varlistentry>
+        
+  <varlistentry>
+   <term>
+    <function>PQtrace</function>
+    <indexterm>
+     <primary>PQtrace</primary>
+    </indexterm>
+   </term>
+
+   <listitem>
+    <para>
+     Enables  tracing of the client/server communication to a debugging file stream.
+     <synopsis>
+      void PQtrace(PGconn *conn, FILE *stream);
+     </synopsis>
+    </para>
 
-typedef void (*PQnoticeProcessor) (void *arg, const char *message);
+    <note>
+     <para>
+      On Windows, if the <application>libpq</> library and an application are
+      compiled with different flags, this function call will crash the 
+      application because the internal representation of the <literal>FILE</> 
+      pointers differ.  Specifically, multithreaded/single-threaded,
+      release/debug, and static/dynamic flags should be the same for the
+      library and all applications using that library.
+     </para>
+    </note>
 
-PQnoticeProcessor
-PQsetNoticeProcessor(PGconn *conn,
-                     PQnoticeProcessor proc,
-                     void *arg);
-</synopsis>
+   </listitem>
+  </varlistentry>
+        
+  <varlistentry>
+   <term>
+    <function>PQuntrace</function>
+    <indexterm>
+     <primary>PQuntrace</primary>
+    </indexterm>
+   </term>
+
+   <listitem>
+    <para>
+     Disables tracing started by <function>PQtrace</function>.
+     <synopsis>
+      void PQuntrace(PGconn *conn);
+     </synopsis>
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+        
+ </sect1>
+        
+ <sect1 id="libpq-misc">
+  <title>Miscellaneous Functions</title>
+        
+  <para>
+   As always, there are some functions that just don't fit anywhere.
+  </para>
+        
+  <variablelist>
+   <varlistentry>
+    <term>
+     <function>PQencryptPassword</function>
+     <indexterm>
+      <primary>PQencryptPassword</primary>
+     </indexterm>
+    </term>
 
-Each of these functions returns the previous notice receiver or processor
-function pointer, and sets the new value.
-If you supply a null function pointer, no action is taken,
-but the current pointer is returned.
-</para>
-
-<para>
-When a notice or warning message is received from the server, or generated
-internally by <application>libpq</application>, the notice receiver function
-is called.  It is passed the message in the form of a
-<symbol>PGRES_NONFATAL_ERROR</symbol> <structname>PGresult</structname>.
-(This allows the receiver to extract individual fields using
-<function>PQresultErrorField</>, or the complete preformatted message using
-<function>PQresultErrorMessage</>.)
-The same void pointer passed to 
-<function>PQsetNoticeReceiver</function> is also passed.
-(This pointer can be used to access application-specific state if needed.)
-</para>
-
-<para>
-The default notice receiver simply extracts the message (using
-<function>PQresultErrorMessage</>) and passes it to the notice processor.
-</para>
-
-<para>
-The notice processor is responsible for handling a notice or warning message
-given in text form.  It is passed the string text of the message
-(including a trailing newline), plus
-a void pointer that is the same one passed to
-<function>PQsetNoticeProcessor</function>.
-(This pointer can be used to access application-specific state if needed.)
-</para>
-
-<para>
-The default notice processor is simply:
-<programlisting>
+    <listitem>
+     <para>
+      Prepares the encrypted form of a <productname>PostgreSQL</> password.
+      <synopsis>
+       char * PQencryptPassword(const char *passwd, const char *user);
+      </synopsis>
+      This function is intended to be used by client applications that
+      wish to send commands like <literal>ALTER USER joe PASSWORD
+      'pwd'</>.  It is good practice not to send the original cleartext
+      password in such a command, because it might be exposed in command
+      logs, activity displays, and so on.  Instead, use this function to
+      convert the password to encrypted form before it is sent.  The
+      arguments are the cleartext password, and the SQL name of the user
+      it is for.  The return value is a string allocated by
+      <function>malloc</function>, or <symbol>NULL</symbol> if out of
+      memory.  The caller can assume the string doesn't contain any
+      special characters that would require escaping.  Use
+      <function>PQfreemem</> to free the result when done with it.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+       
+ </sect1>
+        
+ <sect1 id="libpq-notice-processing">
+  <title>Notice Processing</title>
+        
+  <indexterm zone="libpq-notice-processing">
+   <primary>notice processing</primary>
+   <secondary>in libpq</secondary>
+  </indexterm>
+        
+  <para>
+   Notice and warning messages generated by the server are not returned
+   by the query execution functions, since they do not imply failure of
+   the query.  Instead they are passed to a notice handling function, and
+   execution continues normally after the handler returns.  The default
+   notice handling function prints the message on
+   <filename>stderr</filename>, but the application can override this
+   behavior by supplying its own handling function.
+  </para>
+   
+  <para>
+   For historical reasons, there are two levels of notice handling, called
+   the notice receiver and notice processor.  The default behavior is for
+   the notice receiver to format the notice and pass a string to the notice
+   processor for printing.  However, an application that chooses to provide
+   its own notice receiver will typically ignore the notice processor
+   layer and just do all the work in the notice receiver.
+  </para>
+        
+  <para>
+   The function <function>PQsetNoticeReceiver</function>
+   <indexterm><primary>notice
+   receiver</></><indexterm><primary>PQsetNoticeReceiver</></> sets or
+   examines the current notice receiver for a connection object.
+   Similarly, <function>PQsetNoticeProcessor</function>
+   <indexterm><primary>notice
+   processor</></><indexterm><primary>PQsetNoticeProcessor</></> sets or
+   examines the current notice processor.
+   
+   <synopsis>
+    typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
+   
+    PQnoticeReceiver
+    PQsetNoticeReceiver(PGconn *conn,
+                        PQnoticeReceiver proc,
+                        void *arg);
+   
+    typedef void (*PQnoticeProcessor) (void *arg, const char *message);
+   
+    PQnoticeProcessor
+    PQsetNoticeProcessor(PGconn *conn,
+                         PQnoticeProcessor proc,
+                         void *arg);
+   </synopsis>
+   
+   Each of these functions returns the previous notice receiver or
+   processor function pointer, and sets the new value.  If you supply a
+   null function pointer, no action is taken, but the current pointer is
+   returned.
+  </para>
+   
+  <para>
+   When a notice or warning message is received from the server, or
+   generated internally by <application>libpq</application>, the notice
+   receiver function is called.  It is passed the message in the form of
+   a <symbol>PGRES_NONFATAL_ERROR</symbol>
+   <structname>PGresult</structname>.  (This allows the receiver to extract
+   individual fields using <function>PQresultErrorField</>, or the complete
+   preformatted message using <function>PQresultErrorMessage</>.) The same
+   void pointer passed to <function>PQsetNoticeReceiver</function> is also
+   passed.  (This pointer can be used to access application-specific state
+   if needed.)
+  </para>
+   
+  <para>
+   The default notice receiver simply extracts the message (using
+   <function>PQresultErrorMessage</>) and passes it to the notice
+   processor.
+  </para>
+   
+  <para>
+   The notice processor is responsible for handling a notice or warning
+   message given in text form.  It is passed the string text of the message
+   (including a trailing newline), plus a void pointer that is the same
+   one passed to <function>PQsetNoticeProcessor</function>.  (This pointer
+   can be used to access application-specific state if needed.)
+  </para>
+   
+  <para>
+   The default notice processor is simply:
+   <programlisting>
 static void
 defaultNoticeProcessor(void *arg, const char *message)
 {
     fprintf(stderr, "%s", message);
 }
 </programlisting>
-</para>
-
-<para>
-Once you have set a notice receiver or processor, you should expect that that
-function could be called as long as either the <structname>PGconn</> object or
-<structname>PGresult</> objects made from it exist.  At creation of a
-<structname>PGresult</>, the <structname>PGconn</>'s current notice handling
-pointers are copied into the <structname>PGresult</> for possible use by
-functions like <function>PQgetvalue</function>.
-</para>
-
-</sect1>
-
-<sect1 id="libpq-envars">
-<title>Environment Variables</title>
-
-<indexterm zone="libpq-envars">
- <primary>environment variable</primary>
-</indexterm>
-
-<para>
-The following environment variables can be used to select default
-connection parameter values, which will be used by
-<function>PQconnectdb</>, <function>PQsetdbLogin</> and
-<function>PQsetdb</> if no value is directly specified by the calling
-code.  These are useful to avoid hard-coding database connection
-information into simple client applications, for example.
-
-<itemizedlist>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGHOST</envar></primary>
-</indexterm>
-<envar>PGHOST</envar> sets the database server name.
-If this begins with a slash, it specifies Unix-domain communication
-rather than TCP/IP communication; the value is then the name of the
-directory in which the socket file is stored (in a default installation
-setup this would be <filename>/tmp</filename>).
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGHOSTADDR</envar></primary>
-</indexterm>
-<envar>PGHOSTADDR</envar> specifies the numeric IP address of the database
-server.  This can be set instead of or in addition to <envar>PGHOST</envar>
-to avoid DNS lookup overhead. See the documentation of
-these parameters, under <function>PQconnectdb</function> above, for details
-on their interaction.
-</para>
-<para>
-When neither <envar>PGHOST</envar> nor <envar>PGHOSTADDR</envar> is set,
-the default behavior is to connect using a local Unix-domain socket; or on
-machines without Unix-domain sockets, <application>libpq</application> will
-attempt to connect to <literal>localhost</>.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGPORT</envar></primary>
-</indexterm>
-<envar>PGPORT</envar> sets the TCP port number or Unix-domain
-socket file extension for communicating with the
-<productname>PostgreSQL</productname> server.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGDATABASE</envar></primary>
-</indexterm>
-<envar>PGDATABASE</envar>  sets the 
-<productname>PostgreSQL</productname> database name.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGUSER</envar></primary>
-</indexterm>
-<envar>PGUSER</envar>
-sets the user name used to connect to the database.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGPASSWORD</envar></primary>
-</indexterm>
-<envar>PGPASSWORD</envar>
-sets the password used if the server demands password
-authentication.  Use of this environment variable is not 
-recommended for security reasons (some operating systems
-allow non-root users to see process environment variables via
-<application>ps</>); instead consider using  the 
-<filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">).
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGPASSFILE</envar></primary>
-</indexterm>
-<envar>PGPASSFILE</envar>
-specifies the name of the password file to use for lookups.
-If not set, it defaults to <filename>~/.pgpass</>
-(see <xref linkend="libpq-pgpass">).
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGSERVICE</envar></primary>
-</indexterm>
-<envar>PGSERVICE</envar>
-sets the service name to be looked up in <filename>pg_service.conf</filename>.
-This offers a shorthand way of setting all the parameters.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGREALM</envar></primary>
-</indexterm>
-<envar>PGREALM</envar> sets the Kerberos realm to  use  with  
-<productname>PostgreSQL</productname>, if  it is different from the local realm.
-If <envar>PGREALM</envar> is set, <application>libpq</application>
-applications  will  attempt authentication  with  servers for this realm and use
-separate ticket files to avoid conflicts with  local
-ticket  files.   This  environment  variable is only
-used if Kerberos authentication is selected by the server.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGOPTIONS</envar></primary>
-</indexterm>
-<envar>PGOPTIONS</envar> sets additional run-time  options  for  
-the <productname>PostgreSQL</productname> server.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGSSLMODE</envar></primary>
-</indexterm>
-<envar>PGSSLMODE</envar> determines whether and with what priority an
-<acronym>SSL</> connection will be negotiated with the server. There are
-four modes: <literal>disable</> will attempt only an unencrypted
-<acronym>SSL</> connection; <literal>allow</> will negotiate,
-trying first a non-<acronym>SSL</> connection, then if that fails,
-trying an <acronym>SSL</> connection; <literal>prefer</>
-(the default) will negotiate, trying first an <acronym>SSL</>
-connection, then if that fails, trying a regular non-<acronym>SSL</>
-connection; <literal>require</> will try only an <acronym>SSL</>
-connection. If <productname>PostgreSQL</> is compiled without SSL support,
-using option <literal>require</> will cause an error, while options
-<literal>allow</> and <literal>prefer</> will be accepted but
-<application>libpq</> will not in fact attempt an <acronym>SSL</>
-connection.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGREQUIRESSL</envar></primary>
-</indexterm>
-<envar>PGREQUIRESSL</envar> sets whether or not the connection must be
-made over <acronym>SSL</acronym>. If set to
-<quote>1</quote>, <application>libpq</>
-will refuse to connect if the server does not accept
-an <acronym>SSL</acronym> connection (equivalent to <literal>sslmode</>
-<literal>prefer</>).
-This option is deprecated in favor of the <literal>sslmode</>
-setting, and is only available if
-<productname>PostgreSQL</> is compiled with SSL support.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
-<primary><envar>PGSSLKEY</envar></primary>
-</indexterm>
-<envar>PGSSLKEY</envar>
-specifies the hardware token that stores the secret key for the client
-certificate. The value of this variable should consist
-of a colon-separated engine name (engines are <productname>OpenSSL</>
-loadable modules) and an engine-specific key identifier.  If this is not
-set, the secret key must be kept in a file.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGKRBSRVNAME</envar></primary>
-</indexterm>
-<envar>PGKRBSRVNAME</envar> sets the Kerberos service name to use when
-authenticating with Kerberos 5 or GSSAPI.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGGSSLIB</envar></primary>
-</indexterm>
-<envar>PGGSSLIB</envar> sets the GSS library to use for GSSAPI 
-authentication. 
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGCONNECT_TIMEOUT</envar></primary>
-</indexterm>
-<envar>PGCONNECT_TIMEOUT</envar> sets the maximum number of seconds
-that <application>libpq</application> will wait when attempting to
-connect to the <productname>PostgreSQL</productname> server.  If unset
-or set to zero, <application>libpq</application> will wait indefinitely.
-It is not recommended to set the timeout to less than 2 seconds.
-</para>
-</listitem>
-</itemizedlist>
-</para>
-
-<para>
-The following environment variables can be used to specify default
-behavior for each <productname>PostgreSQL</productname> session.
-(See also the
-<xref linkend="sql-alteruser" endterm="sql-alteruser-title"> and
-<xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">
-commands for ways to set default behavior on a per-user or per-database
-basis.)
-
-<itemizedlist>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGDATESTYLE</envar></primary>
-</indexterm>
-<envar>PGDATESTYLE</envar>
-sets the default style of date/time representation.
-(Equivalent to <literal>SET datestyle TO ...</literal>.)
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGTZ</envar></primary>
-</indexterm>
-<envar>PGTZ</envar>
-sets the default time zone.
-(Equivalent to <literal>SET timezone TO ...</literal>.)
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGCLIENTENCODING</envar></primary>
-</indexterm>
-<envar>PGCLIENTENCODING</envar>
-sets the default client character set encoding.
-(Equivalent to <literal>SET client_encoding TO ...</literal>.)
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGGEQO</envar></primary>
-</indexterm>
-<envar>PGGEQO</envar>
-sets the default mode for the genetic query optimizer.
-(Equivalent to <literal>SET geqo TO ...</literal>.)
-</para>
-</listitem>
-</itemizedlist>
-
-Refer to the <acronym>SQL</acronym> command 
-<xref linkend="sql-set" endterm="sql-set-title">
-for information on correct values for these environment variables.
-</para>
-
-<para>
-The following environment variables determine internal behavior of
-<application>libpq</application>; they override compiled-in defaults.
-
-<itemizedlist>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGSYSCONFDIR</envar></primary>
-</indexterm>
-<envar>PGSYSCONFDIR</envar>
-sets the directory containing the <filename>pg_service.conf</> file.
-</para>
-</listitem>
-<listitem>
-<para>
-<indexterm>
- <primary><envar>PGLOCALEDIR</envar></primary>
-</indexterm>
-<envar>PGLOCALEDIR</envar>
-sets the directory containing the <literal>locale</> files for message
-internationalization.
-</para>
-</listitem>
-</itemizedlist>
-</para>
-
-</sect1>
-
-
-<sect1 id="libpq-pgpass">
-<title>The Password File</title>
-
-<indexterm zone="libpq-pgpass">
- <primary>password file</primary>
-</indexterm>
-<indexterm zone="libpq-pgpass">
- <primary>.pgpass</primary>
-</indexterm>
-
-<para>
-The file <filename>.pgpass</filename> in a user's home directory or the
-file referenced by <envar>PGPASSFILE</envar> can contain passwords to
-be used if the connection requires a password (and no password has been
-specified  otherwise). On Microsoft Windows the file is named
-<filename>%APPDATA%\postgresql\pgpass.conf</> (where
-<filename>%APPDATA%</> refers to the Application Data subdirectory in
-the user's profile).
-</para>
-
-<para>
-This file should contain lines of the following format:
-<synopsis>
-<replaceable>hostname</replaceable>:<replaceable>port</replaceable>:<replaceable>database</replaceable>:<replaceable>username</replaceable>:<replaceable>password</replaceable>
-</synopsis>
-Each of the first four fields can be a literal value, or <literal>*</literal>,
-which matches anything.  The password field from the first line that matches the
-current connection parameters will be used.  (Therefore, put more-specific
-entries first when you are using wildcards.)
-If an entry needs to contain <literal>:</literal> or
-<literal>\</literal>, escape this character with <literal>\</literal>.
-A host name of <literal>localhost</> matches both TCP (hostname
-<literal>localhost</>) and Unix domain socket (<literal>pghost</> empty or the
-default socket directory) connections coming from the local machine.
-</para>
-
-<para>
-On Unix systems, the permissions on <filename>.pgpass</filename> must disallow
-any access to world or group; achieve this by the command
-<command>chmod 0600 ~/.pgpass</command>.
-If the permissions are less strict than this, the file will be ignored.
-On Microsoft Windows, it is assumed that the file is stored in a directory
-that is secure, so no special permissions check is made.
-</para>
-</sect1>
-
-
-<sect1 id="libpq-pgservice">
-<title>The Connection Service File</title>
-
-<indexterm zone="libpq-pgservice">
- <primary>connection service file</primary>
-</indexterm>
-<indexterm zone="libpq-pgservice">
- <primary>pg_service.conf</primary>
-</indexterm>
-
-<para>
-The connection service file allows libpq connection parameters to be
-associated with a single service name. That service name can then be
-specified by a libpq connection, and the associated settings will be
-used. This allows connection parameters to be modified without requiring
-a recompile of the libpq application. The service name can also be
-specified using the <envar>PGSERVICE</envar> environment variable.
-</para>
-<para>
-To use this feature, copy
-<filename>share/pg_service.conf.sample</filename> to
-<filename>etc/pg_service.conf</filename> and edit the file to add
-service names and parameters. This file can be used for client-only
-installs too. The file's location can also be specified by the
-<envar>PGSYSCONFDIR</envar> environment variable.
-</para>
-</sect1>
-
-
-<sect1 id="libpq-ldap">
- <title>LDAP Lookup of Connection Parameters</title>
-
-<indexterm zone="libpq-ldap">
- <primary>LDAP connection parameter lookup</primary>
-</indexterm>
-
-<para>
-If <application>libpq</application> has been compiled with LDAP support (option
-<literal><option>--with-ldap</option></literal> for <command>configure</command>)
-it is possible to retrieve connection options like <literal>host</literal>
-or <literal>dbname</literal> via LDAP from a central server.
-The advantage is that if the connection parameters for a database change,
-the connection information doesn't have to be updated on all client machines.
-</para>
-
-<para>
-LDAP connection parameter lookup uses the connection service file
-<filename>pg_service.conf</filename> (see <xref linkend="libpq-pgservice">).
-A line in a <filename>pg_service.conf</filename> stanza that starts with
-<literal>ldap://</literal> will be recognized as an LDAP URL and an LDAP
-query will be performed. The result must be a list of <literal>keyword =
-value</literal> pairs which will be used to set connection options.
-The URL must conform to RFC 1959 and be of the form
-<synopsis>
-ldap://[<replaceable>hostname</replaceable>[:<replaceable>port</replaceable>]]/<replaceable>search_base</replaceable>?<replaceable>attribute</replaceable>?<replaceable>search_scope</replaceable>?<replaceable>filter</replaceable>
-</synopsis>
-where <replaceable>hostname</replaceable>
-defaults to <literal>localhost</literal> and
-<replaceable>port</replaceable> defaults to 389.
-</para>
-
-<para>
-Processing of <filename>pg_service.conf</filename> is terminated after
-a successful LDAP lookup, but is continued if the LDAP server cannot be
-contacted.  This is to provide a fallback with
-further LDAP URL lines that point to different LDAP
-servers, classical <literal>keyword = value</literal> pairs, or
-default connection options.
-If you would rather get an error message in this case, add a
-syntactically incorrect line after the LDAP URL.
-</para>
-
-<para>
-A sample LDAP entry that has been created with the LDIF file
-<synopsis>
-version:1
-dn:cn=mydatabase,dc=mycompany,dc=com
-changetype:add
-objectclass:top
-objectclass:groupOfUniqueNames
-cn:mydatabase
-uniqueMember:host=dbserver.mycompany.com
-uniqueMember:port=5439
-uniqueMember:dbname=mydb
-uniqueMember:user=mydb_user
-uniqueMember:sslmode=require
-</synopsis>
-might be queried with the following LDAP URL:
-<synopsis>
-ldap://ldap.mycompany.com/dc=mycompany,dc=com?uniqueMember?one?(cn=mydatabase)
-</synopsis>
-</para>
-</sect1>
+  </para>
+   
+  <para>
+   Once you have set a notice receiver or processor, you should expect
+   that that function could be called as long as either the
+   <structname>PGconn</> object or <structname>PGresult</> objects made
+   from it exist.  At creation of a <structname>PGresult</>, the
+   <structname>PGconn</>'s current notice handling pointers are copied
+   into the <structname>PGresult</> for possible use by functions like
+   <function>PQgetvalue</function>.
+  </para>
+   
+ </sect1>
+        
+ <sect1 id="libpq-envars">
+  <title>Environment Variables</title>
+        
+  <indexterm zone="libpq-envars">
+   <primary>environment variable</primary>
+  </indexterm>
+        
+  <para>
+   The following environment variables can be used to select default
+   connection parameter values, which will be used by
+   <function>PQconnectdb</>, <function>PQsetdbLogin</> and
+   <function>PQsetdb</> if no value is directly specified by the calling
+   code.  These are useful to avoid hard-coding database connection
+   information into simple client applications, for example.
+   
+   <itemizedlist>
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGHOST</envar></primary>
+      </indexterm>
+      <envar>PGHOST</envar> sets the database server name.
+      If this begins with a slash, it specifies Unix-domain communication
+      rather than TCP/IP communication; the value is then the name of the
+      directory in which the socket file is stored (in a default installation
+      setup this would be <filename>/tmp</filename>).
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGHOSTADDR</envar></primary>
+      </indexterm>
+      <envar>PGHOSTADDR</envar> specifies the numeric IP address of the database
+      server.  This can be set instead of or in addition to <envar>PGHOST</envar>
+      to avoid DNS lookup overhead. See the documentation of
+      these parameters, under <function>PQconnectdb</function> above, for details
+      on their interaction.
+     </para>
+     <para>
+      When neither <envar>PGHOST</envar> nor <envar>PGHOSTADDR</envar> is set,
+      the default behavior is to connect using a local Unix-domain socket; or on
+      machines without Unix-domain sockets, <application>libpq</application> will
+      attempt to connect to <literal>localhost</>.
+     </para>
+    </listitem>
 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGPORT</envar></primary>
+      </indexterm>
+      <envar>PGPORT</envar> sets the TCP port number or Unix-domain socket
+      file extension for communicating with the
+      <productname>PostgreSQL</productname> server.
+     </para>
+    </listitem>
 
-<sect1 id="libpq-ssl">
-<title>SSL Support</title>
+    <listitem>
+     <para>
+      <indexterm>  
+       <primary><envar>PGDATABASE</envar></primary>
+      </indexterm>
+      <envar>PGDATABASE</envar>  sets the
+      <productname>PostgreSQL</productname> database name.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGUSER</envar></primary>
+      </indexterm>
+      <envar>PGUSER</envar> sets the user name used to connect to the
+      database.
+     </para>
+    </listitem>
 
-<indexterm zone="libpq-ssl">
- <primary>SSL</primary>
-</indexterm>
+    <listitem>
+     <para> 
+      <indexterm>
+       <primary><envar>PGPASSWORD</envar></primary>
+      </indexterm>
+      <envar>PGPASSWORD</envar> sets the password used if the server
+      demands password authentication.  Use of this environment variable
+      is not recommended for security reasons (some operating systems
+      allow non-root users to see process environment variables via
+      <application>ps</>); instead consider using  the
+      <filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">).
+     </para>
+    </listitem>
 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGPASSFILE</envar></primary>
+      </indexterm>
+      <envar>PGPASSFILE</envar> specifies the name of the password file to
+      use for lookups.  If not set, it defaults to <filename>~/.pgpass</>
+      (see <xref linkend="libpq-pgpass">).
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGSERVICE</envar></primary>
+      </indexterm>
+      <envar>PGSERVICE</envar>
+      sets the service name to be looked up in
+      <filename>pg_service.conf</filename>.  This offers a shorthand way
+      of setting all the parameters.
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGREALM</envar></primary>
+      </indexterm>
+      <envar>PGREALM</envar> sets the Kerberos realm to  use  with
+      <productname>PostgreSQL</productname>, if  it is different from the
+      local realm.  If <envar>PGREALM</envar> is set,
+      <application>libpq</application> applications  will  attempt
+      authentication  with  servers for this realm and use separate ticket
+      files to avoid conflicts with  local ticket  files.   This
+      environment  variable is only used if Kerberos authentication is
+      selected by the server.
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGOPTIONS</envar></primary>
+      </indexterm>
+      <envar>PGOPTIONS</envar> sets additional run-time  options  for the
+      <productname>PostgreSQL</productname> server.
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGSSLMODE</envar></primary>
+      </indexterm>
+      <envar>PGSSLMODE</envar> determines whether and with what priority
+      an <acronym>SSL</> connection will be negotiated with the server.
+      There are four modes: <literal>disable</> will attempt only an
+      unencrypted <acronym>SSL</> connection; <literal>allow</> will
+      negotiate, trying first a non-<acronym>SSL</> connection, then if
+      that fails, trying an <acronym>SSL</> connection; <literal>prefer</>
+      (the default) will negotiate, trying first an <acronym>SSL</>
+      connection, then if that fails, trying a regular non-<acronym>SSL</>
+      connection; <literal>require</> will try only an <acronym>SSL</>
+      connection. If <productname>PostgreSQL</> is compiled without SSL
+      support, using option <literal>require</> will cause an error, while
+      options <literal>allow</> and <literal>prefer</> will be accepted
+      but <application>libpq</> will not in fact attempt an <acronym>SSL</>
+      connection.
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGREQUIRESSL</envar></primary>
+      </indexterm>
+      <envar>PGREQUIRESSL</envar> sets whether or not the connection must
+      be made over <acronym>SSL</acronym>. If set to <quote>1</quote>,
+      <application>libpq</> will refuse to connect if the server does not
+      accept an <acronym>SSL</acronym> connection (equivalent to
+      <literal>sslmode</> <literal>prefer</>).  This option is deprecated
+      in favor of the <literal>sslmode</> setting, and is only available
+      if <productname>PostgreSQL</> is compiled with SSL support.
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGSSLKEY</envar></primary>
+      </indexterm>
+      <envar>PGSSLKEY</envar> specifies the hardware token that stores the
+      secret key for the client certificate. The value of this variable
+      should consist of a colon-separated engine name (engines are
+      <productname>OpenSSL</> loadable modules) and an engine-specific key
+      identifier.  If this is not set, the secret key must be kept in a
+      file.
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGKRBSRVNAME</envar></primary>
+      </indexterm>
+      <envar>PGKRBSRVNAME</envar> sets the Kerberos service name to use
+      when authenticating with Kerberos 5 or GSSAPI.
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGGSSLIB</envar></primary>
+      </indexterm>
+      <envar>PGGSSLIB</envar> sets the GSS library to use for GSSAPI
+      authentication.
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGCONNECT_TIMEOUT</envar></primary>
+      </indexterm>
+      <envar>PGCONNECT_TIMEOUT</envar> sets the maximum number of seconds
+      that <application>libpq</application> will wait when attempting to
+      connect to the <productname>PostgreSQL</productname> server.  If
+      unset or set to zero, <application>libpq</application> will wait
+      indefinitely.  It is not recommended to set the timeout to less than
+      2 seconds.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+      
   <para>
-   <productname>PostgreSQL</> has native support for using
-   <acronym>SSL</> connections to encrypt client/server communications
-   for increased security. See <xref linkend="ssl-tcp"> for details
-   about the server-side <acronym>SSL</> functionality.
+   The following environment variables can be used to specify default
+   behavior for each <productname>PostgreSQL</productname> session.  (See
+   also the <xref linkend="sql-alteruser" endterm="sql-alteruser-title">
+   and <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">
+   commands for ways to set default behavior on a per-user or per-database
+   basis.)
+   
+   <itemizedlist>
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGDATESTYLE</envar></primary>
+      </indexterm>
+      <envar>PGDATESTYLE</envar> sets the default style of date/time
+      representation.  (Equivalent to <literal>SET datestyle TO
+      ...</literal>.)
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGTZ</envar></primary>
+      </indexterm>
+      <envar>PGTZ</envar> sets the default time zone.  (Equivalent to
+      <literal>SET timezone TO ...</literal>.)
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGCLIENTENCODING</envar></primary>
+      </indexterm>
+      <envar>PGCLIENTENCODING</envar> sets the default client character
+      set encoding.  (Equivalent to <literal>SET client_encoding TO
+      ...</literal>.)
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGGEQO</envar></primary>
+      </indexterm>
+      <envar>PGGEQO</envar> sets the default mode for the genetic query
+      optimizer.  (Equivalent to <literal>SET geqo TO ...</literal>.)
+     </para>
+    </listitem>
+   </itemizedlist>
+         
+   Refer to the <acronym>SQL</acronym> command <xref linkend="sql-set"
+   endterm="sql-set-title"> for information on correct values for these
+   environment variables.
+  </para>
+         
+  <para>
+   The following environment variables determine internal behavior of
+   <application>libpq</application>; they override compiled-in defaults.
+   
+   <itemizedlist>
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGSYSCONFDIR</envar></primary>
+      </indexterm>
+      <envar>PGSYSCONFDIR</envar> sets the directory containing the
+      <filename>pg_service.conf</> file.
+     </para>
+    </listitem>
+ 
+    <listitem>
+     <para>
+      <indexterm>
+       <primary><envar>PGLOCALEDIR</envar></primary>
+      </indexterm>
+      <envar>PGLOCALEDIR</envar> sets the directory containing the
+      <literal>locale</> files for message internationalization.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+   
+ </sect1>
+         
+        
+ <sect1 id="libpq-pgpass">
+  <title>The Password File</title>
+        
+  <indexterm zone="libpq-pgpass">
+   <primary>password file</primary>
+  </indexterm>
+  <indexterm zone="libpq-pgpass">
+   <primary>.pgpass</primary>
+  </indexterm>
+        
+  <para>
+   The file <filename>.pgpass</filename> in a user's home directory or the
+   file referenced by <envar>PGPASSFILE</envar> can contain passwords to
+   be used if the connection requires a password (and no password has been
+   specified  otherwise). On Microsoft Windows the file is named
+   <filename>%APPDATA%\postgresql\pgpass.conf</> (where
+   <filename>%APPDATA%</> refers to the Application Data subdirectory in
+   the user's profile).
+  </para>
+        
+  <para>
+   This file should contain lines of the following format:
+   <synopsis>
+    <replaceable>hostname</replaceable>:<replaceable>port</replaceable>:<replaceable>database</replaceable>:<replaceable>username</replaceable>:<replaceable>password</replaceable>
+   </synopsis>
+   Each of the first four fields can be a literal value, or
+   <literal>*</literal>, which matches anything.  The password field from
+   the first line that matches the current connection parameters will be
+   used.  (Therefore, put more-specific entries first when you are using
+   wildcards.) If an entry needs to contain <literal>:</literal> or
+   <literal>\</literal>, escape this character with <literal>\</literal>.
+   A host name of <literal>localhost</> matches both TCP (hostname
+   <literal>localhost</>) and Unix domain socket (<literal>pghost</> empty
+   or the default socket directory) connections coming from the local
+   machine.
+  </para>
+   
+  <para>
+   On Unix systems, the permissions on <filename>.pgpass</filename> must
+   disallow any access to world or group; achieve this by the command
+   <command>chmod 0600 ~/.pgpass</command>.  If the permissions are less
+   strict than this, the file will be ignored.  On Microsoft Windows, it
+   is assumed that the file is stored in a directory that is secure, so
+   no special permissions check is made.
+  </para>
+ </sect1>
+        
+        
+ <sect1 id="libpq-pgservice">
+  <title>The Connection Service File</title>
+     
+  <indexterm zone="libpq-pgservice">
+   <primary>connection service file</primary>
+  </indexterm>
+  <indexterm zone="libpq-pgservice">
+   <primary>pg_service.conf</primary>
+  </indexterm>
+        
+  <para>
+   The connection service file allows libpq connection parameters to be
+   associated with a single service name. That service name can then be
+   specified by a libpq connection, and the associated settings will be
+   used. This allows connection parameters to be modified without requiring
+   a recompile of the libpq application. The service name can also be
+   specified using the <envar>PGSERVICE</envar> environment variable.
   </para>
 
   <para>
+   To use this feature, copy
+   <filename>share/pg_service.conf.sample</filename> to
+   <filename>etc/pg_service.conf</filename> and edit the file to add
+   service names and parameters. This file can be used for client-only
+   installs too. The file's location can also be specified by the
+   <envar>PGSYSCONFDIR</envar> environment variable.
+  </para>
+ </sect1>
+        
+        
+ <sect1 id="libpq-ldap">
+  <title>LDAP Lookup of Connection Parameters</title>
+        
+  <indexterm zone="libpq-ldap">
+   <primary>LDAP connection parameter lookup</primary>
+  </indexterm>
+        
+  <para>
+   If <application>libpq</application> has been compiled with LDAP support (option
+   <literal><option>--with-ldap</option></literal> for <command>configure</command>)
+   it is possible to retrieve connection options like <literal>host</literal>
+   or <literal>dbname</literal> via LDAP from a central server.
+   The advantage is that if the connection parameters for a database change,
+   the connection information doesn't have to be updated on all client machines.
+  </para>
+   
+  <para>
+   LDAP connection parameter lookup uses the connection service file
+   <filename>pg_service.conf</filename> (see <xref
+   linkend="libpq-pgservice">).  A line in a
+   <filename>pg_service.conf</filename> stanza that starts with
+   <literal>ldap://</literal> will be recognized as an LDAP URL and an
+   LDAP query will be performed. The result must be a list of
+   <literal>keyword = value</literal> pairs which will be used to set
+   connection options.  The URL must conform to RFC 1959 and be of the
+   form
+   <synopsis>
+    ldap://[<replaceable>hostname</replaceable>[:<replaceable>port</replaceable>]]/<replaceable>search_base</replaceable>?<replaceable>attribute</replaceable>?<replaceable>search_scope</replaceable>?<replaceable>filter</replaceable>
+   </synopsis>
+   where <replaceable>hostname</replaceable> defaults to
+   <literal>localhost</literal> and <replaceable>port</replaceable>
+   defaults to 389.
+  </para>
+   
+  <para>
+   Processing of <filename>pg_service.conf</filename> is terminated after
+   a successful LDAP lookup, but is continued if the LDAP server cannot
+   be contacted.  This is to provide a fallback with further LDAP URL
+   lines that point to different LDAP servers, classical <literal>keyword
+   = value</literal> pairs, or default connection options.  If you would
+   rather get an error message in this case, add a syntactically incorrect
+   line after the LDAP URL.
+  </para>
+   
+  <para>
+   A sample LDAP entry that has been created with the LDIF file
+   <synopsis>
+    version:1
+    dn:cn=mydatabase,dc=mycompany,dc=com
+    changetype:add
+    objectclass:top
+    objectclass:groupOfUniqueNames
+    cn:mydatabase
+    uniqueMember:host=dbserver.mycompany.com
+    uniqueMember:port=5439
+    uniqueMember:dbname=mydb
+    uniqueMember:user=mydb_user
+    uniqueMember:sslmode=require
+   </synopsis>
+   might be queried with the following LDAP URL:
+   <synopsis>
+    ldap://ldap.mycompany.com/dc=mycompany,dc=com?uniqueMember?one?(cn=mydatabase)
+   </synopsis>
+  </para>
+ </sect1>
+        
+        
+ <sect1 id="libpq-ssl">
+  <title>SSL Support</title>
+        
+  <indexterm zone="libpq-ssl">
+   <primary>SSL</primary>
+  </indexterm>
+        
+  <para>
+   <productname>PostgreSQL</> has native support for using <acronym>SSL</>
+   connections to encrypt client/server communications for increased
+   security. See <xref linkend="ssl-tcp"> for details about the server-side
+   <acronym>SSL</> functionality.
+  </para>
+        
+  <para>
    <application>libpq</application> reads the system-wide
    <productname>OpenSSL</productname> configuration file. By default, this
    file is named <filename>openssl.cnf</filename> and is located in the
-   directory reported by <literal>openssl version -d</>.
-   This default can be overridden by setting environment variable
+   directory reported by <literal>openssl version -d</>.  This default
+   can be overridden by setting environment variable
    <envar>OPENSSL_CONF</envar> to the name of the desired configuration
    file.
   </para>
-
+        
   <para>
-   If the server demands a client certificate, 
-   <application>libpq</application>
-   will send the certificate stored in file
-   <filename>~/.postgresql/postgresql.crt</> within the user's home directory.
-   A matching private key file <filename>~/.postgresql/postgresql.key</>
-   must also be present, unless the secret key for the certificate is stored
-   in a hardware token, as specified by <envar>PGSSLKEY</envar>.
-   (On Microsoft Windows these files are named
-   <filename>%APPDATA%\postgresql\postgresql.crt</filename> and
-   <filename>%APPDATA%\postgresql\postgresql.key</filename>.)
-   The private key file must not be world-readable.
+   If the server demands a client certificate,
+   <application>libpq</application> will send the certificate stored in
+   file <filename>~/.postgresql/postgresql.crt</> within the user's home
+   directory.  A matching private key file
+   <filename>~/.postgresql/postgresql.key</> must also be present, unless
+   the secret key for the certificate is stored in a hardware token, as
+   specified by <envar>PGSSLKEY</envar>.  (On Microsoft Windows these
+   files are named <filename>%APPDATA%\postgresql\postgresql.crt</filename>
+   and <filename>%APPDATA%\postgresql\postgresql.key</filename>.) The
+   private key file must not be world-readable.
   </para>
 
   <para>
@@ -4545,128 +5136,132 @@ ldap://ldap.mycompany.com/dc=mycompany,dc=com?uniqueMember?one?(cn=mydatabase)
 
   <para>
    If the file <filename>~/.postgresql/root.crt</> is present in the user's
-   home directory,
-   <application>libpq</application> will use the certificate list stored
-   therein to verify the server's certificate.
+   home directory, <application>libpq</application> will use the
+   certificate list stored therein to verify the server's certificate.
    (On Microsoft Windows the file is named
-   <filename>%APPDATA%\postgresql\root.crt</filename>.)
-   The SSL connection will
-   fail if the server does not present a certificate; therefore, to
+   <filename>%APPDATA%\postgresql\root.crt</filename>.) The SSL connection
+   will fail if the server does not present a certificate; therefore, to
    use this feature the server must have a <filename>server.crt</> file.
    Certificate Revocation List (CRL) entries are also checked if the file
-   <filename>~/.postgresql/root.crl</filename> exists (<filename>%APPDATA%\postgresql\root.crl</filename>
-   on Microsoft Windows).
+   <filename>~/.postgresql/root.crl</filename> exists
+   (<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
+   Windows).
   </para>
 
   <para>
-   If you are using <acronym>SSL</> inside your application (in addition to
-   inside <application>libpq</application>), you can use <function>PQinitSSL(int)</>
-   to tell <application>libpq</application> that the <acronym>SSL</> library
-   has already been initialized by your application.
+   If you are using <acronym>SSL</> inside your application (in addition
+   to inside <application>libpq</application>), you can use
+   <function>PQinitSSL(int)</> to tell <application>libpq</application>
+   that the <acronym>SSL</> library has already been initialized by your
+   application.
   </para>
 
 
-</sect1>
-
-
-<sect1 id="libpq-threading">
-<title>Behavior in Threaded Programs</title>
-
-<indexterm zone="libpq-threading">
- <primary>threads</primary>
- <secondary>with libpq</secondary>
-</indexterm>
-
-<para>
-<application>libpq</application> is reentrant and thread-safe if the
-<filename>configure</filename> command-line option
-<literal>--enable-thread-safety</> was used when the
-<productname>PostgreSQL</productname> distribution was built.  In
-addition, you might need to use additional compiler command-line
-options when you compile your application code.  Refer to your
-system's documentation for information about how to build
-thread-enabled applications, or look in 
-<filename>src/Makefile.global</filename> for <literal>PTHREAD_CFLAGS</>
-and <literal>PTHREAD_LIBS</>.  This function allows the querying of
-<application>libpq</application>'s thread-safe status:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><function>PQisthreadsafe</function><indexterm><primary>PQisthreadsafe</></></term>
-<listitem>
-<para>
-       Returns the thread safety status of the <application>libpq</application>
-       library.
-<synopsis>
-int PQisthreadsafe();
-</synopsis>
-</para>
-
-<para>
-       Returns 1 if the <application>libpq</application> is thread-safe and
-       0 if it is not.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-One thread restriction is that no two threads attempt to manipulate the same
-<structname>PGconn</> object at the same time. In particular, you cannot
-issue concurrent commands from different threads through the same
-connection object. (If you need to run concurrent commands, use
-multiple connections.)
-</para>
-
-<para>
-<structname>PGresult</> objects are read-only after creation, and so can be 
-passed around freely between threads.
-</para>
-
-<para>
-The deprecated functions
-<function>PQrequestCancel</function> and
-<function>PQoidStatus</function>
-are not thread-safe and should not be used in multithread programs.
-<function>PQrequestCancel</function> can be replaced by
-<function>PQcancel</function>.
-<function>PQoidStatus</function> can be replaced by
-<function>PQoidValue</function>.
-</para>
-
-<para>
-If you are using Kerberos inside your application (in addition to inside 
-<application>libpq</application>), you will need to do locking around 
-Kerberos calls because Kerberos functions are not thread-safe.  See 
-function <function>PQregisterThreadLock</> in the 
-<application>libpq</application> source code for a way to do cooperative 
-locking between <application>libpq</application> and your application.
-</para>
-
-<para>
-If you experience problems with threaded applications, run
-the program in <filename>src/tools/thread</> to see if your
-platform has thread-unsafe functions.  This program is run 
-by <filename>configure</filename>, but for binary distributions
-your library might not match the library used to build the binaries.
-</para>
-</sect1>
-
+ </sect1>
+        
+        
+ <sect1 id="libpq-threading">
+  <title>Behavior in Threaded Programs</title>
+        
+  <indexterm zone="libpq-threading">
+   <primary>threads</primary>
+   <secondary>with libpq</secondary>
+  </indexterm>
+        
+  <para>
+   <application>libpq</application> is reentrant and thread-safe if the
+   <filename>configure</filename> command-line option
+   <literal>--enable-thread-safety</> was used when the
+   <productname>PostgreSQL</productname> distribution was built.  In
+   addition, you might need to use additional compiler command-line
+   options when you compile your application code.  Refer to your
+   system's documentation for information about how to build
+   thread-enabled applications, or look in 
+   <filename>src/Makefile.global</filename> for <literal>PTHREAD_CFLAGS</>
+   and <literal>PTHREAD_LIBS</>.  This function allows the querying of
+   <application>libpq</application>'s thread-safe status:
+  </para>
+        
+  <variablelist>
+   <varlistentry>
+    <term>
+     <function>PQisthreadsafe</function>
+     <indexterm>
+      <primary>PQisthreadsafe</primary>
+     </indexterm>
+    </term>
 
+    <listitem>
+     <para>
+      Returns the thread safety status of the
+      <application>libpq</application> library.
+      <synopsis>
+       int PQisthreadsafe();
+      </synopsis>
+     </para>
+        
+     <para>
+      Returns 1 if the <application>libpq</application> is thread-safe
+      and 0 if it is not.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+        
+  <para>
+   One thread restriction is that no two threads attempt to manipulate
+   the same <structname>PGconn</> object at the same time. In particular,
+   you cannot issue concurrent commands from different threads through
+   the same connection object. (If you need to run concurrent commands,
+   use multiple connections.)
+  </para>
+        
+  <para>
+   <structname>PGresult</> objects are read-only after creation, and so
+   can be passed around freely between threads.
+  </para>
+        
+  <para>
+   The deprecated functions <function>PQrequestCancel</function> and
+   <function>PQoidStatus</function> are not thread-safe and should not be
+   used in multithread programs.  <function>PQrequestCancel</function>
+   can be replaced by <function>PQcancel</function>.
+   <function>PQoidStatus</function> can be replaced by
+   <function>PQoidValue</function>.
+  </para>
+   
+  <para>
+   If you are using Kerberos inside your application (in addition to inside
+   <application>libpq</application>), you will need to do locking around
+   Kerberos calls because Kerberos functions are not thread-safe.  See
+   function <function>PQregisterThreadLock</> in the
+   <application>libpq</application> source code for a way to do cooperative
+   locking between <application>libpq</application> and your application.
+  </para>
+   
+  <para>
+   If you experience problems with threaded applications, run the program
+   in <filename>src/tools/thread</> to see if your platform has
+   thread-unsafe functions.  This program is run by
+   <filename>configure</filename>, but for binary distributions your
+   library might not match the library used to build the binaries.
+  </para>
+ </sect1>
+        
+        
  <sect1 id="libpq-build">
   <title>Building <application>libpq</application> Programs</title>
-
+        
   <indexterm zone="libpq-build">
    <primary>compiling</primary>
    <secondary>libpq applications</secondary>
   </indexterm>
-
+        
   <para>
    To build (i.e., compile and link) a program using
-   <application>libpq</application> you need to 
-   do all of the following things:
-
+   <application>libpq</application> you need to do all of the following
+   things:
+        
    <itemizedlist>
     <listitem>
      <para>
@@ -4674,8 +5269,8 @@ your library might not match the library used to build the binaries.
 <programlisting>
 #include &lt;libpq-fe.h&gt;
 </programlisting>
-      If you failed to do that then you will normally get error
-      messages from your compiler similar to
+      If you failed to do that then you will normally get error messages
+      from your compiler similar to
 <screen>
 foo.c: In function `main':
 foo.c:34: `PGconn' undeclared (first use in this function)
@@ -4686,7 +5281,7 @@ foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function)
 </screen>
      </para>
     </listitem>
-
+        
     <listitem>
      <para>
       Point your compiler to the directory where the <productname>PostgreSQL</> header
@@ -4705,7 +5300,7 @@ cc -c -I/usr/local/pgsql/include testprog.c
 CPPFLAGS += -I/usr/local/pgsql/include
 </programlisting>
      </para>
-
+        
      <para>
       If there is any chance that your program might be compiled by
       other users then you should not hardcode the directory location
@@ -4718,7 +5313,7 @@ CPPFLAGS += -I/usr/local/pgsql/include
 <computeroutput>/usr/local/include</computeroutput>
 </screen>
      </para>
-
+        
      <para>
       Failure to specify the correct option to the compiler will
       result in an error message such as
@@ -4727,14 +5322,15 @@ testlibpq.c:8:22: libpq-fe.h: No such file or directory
 </screen>
      </para>
     </listitem>
-
+      
     <listitem>
      <para>
       When linking the final program, specify the option
-      <literal>-lpq</literal> so that the <application>libpq</application> library gets pulled
-      in, as well as the option
-      <literal>-L<replaceable>directory</replaceable></literal> to
-      point the compiler to the directory where the <application>libpq</application> library resides.  (Again, the
+      <literal>-lpq</literal> so that the <application>libpq</application>
+      library gets pulled in, as well as the option
+      <literal>-L<replaceable>directory</replaceable></literal> to point
+      the compiler to the directory where the
+      <application>libpq</application> library resides.  (Again, the
       compiler will search some directories by default.)  For maximum
       portability, put the <option>-L</option> option before the
       <option>-lpq</option> option.  For example:
@@ -4742,7 +5338,7 @@ testlibpq.c:8:22: libpq-fe.h: No such file or directory
 cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq
 </programlisting>
      </para>
-
+        
      <para>
       You can find out the library directory using
       <command>pg_config</command> as well:
@@ -4751,10 +5347,10 @@ cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq
 <computeroutput>/usr/local/pgsql/lib</computeroutput>
 </screen>
      </para>
-
+        
      <para>
-      Error messages that point to problems in this area could look
-      like the following.
+      Error messages that point to problems in this area could look like
+      the following.
 <screen>
 testlibpq.o: In function `main':
 testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin'
@@ -4765,19 +5361,19 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
 <screen>
 /usr/bin/ld: cannot find -lpq
 </screen>
-      This means you forgot the <option>-L</option> option or did not specify
-      the right directory.
+      This means you forgot the <option>-L</option> option or did not
+      specify the right directory.
      </para>
     </listitem>
    </itemizedlist>
   </para>
-
+        
  </sect1>
-
-
+       
+        
  <sect1 id="libpq-example">
   <title>Example Programs</title>
-
+        
   <para>
    These examples and others can be found in the
    directory <filename>src/test/examples</filename> in the source code