-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.228 2007/02/06 03:03:11 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.314 2010/07/14 17:09:45 tgl 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>
one time. (One reason to do that is to access more than one
database.) Each connection is represented by a
<structname>PGconn</><indexterm><primary>PGconn</></> object, which
- is obtained from the function <function>PQconnectdb</> or
+ is obtained from the function <function>PQconnectdb</>,
+ <function>PQconnectdbParams</>, or
<function>PQsetdbLogin</>. Note that these functions will always
return a non-null object pointer, unless perhaps there is too
little memory even to allocate the <structname>PGconn</> object.
whether a connection was successfully made before queries are sent
via the connection object.
- <variablelist>
- <varlistentry>
- <term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></term>
- <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>
+ <warning>
+ <para>
+ On Unix, forking a process with open libpq connections can lead to
+ unpredictable results because the parent and child processes share
+ the same sockets and operating system resources. For this reason,
+ such usage is not recommended, though doing an <function>exec</> from
+ the child process to load a new executable is safe.
+ </para>
+ </warning>
- <para>
- The currently recognized parameter key words are:
+ <note>
+ <para>
+ On Windows, there is a way to improve performance if a single
+ database connection is repeatedly started and shutdown. Internally,
+ libpq calls WSAStartup() and WSACleanup() for connection startup
+ and shutdown, respectively. WSAStartup() increments an internal
+ Windows library reference count which is decremented by WSACleanup().
+ When the reference count is just one, calling WSACleanup() frees
+ all resources and all DLLs are unloaded. This is an expensive
+ operation. To avoid this, an application can manually call
+ WSAStartup() so resources will not be freed when the last database
+ connection is closed.
+ </para>
+ </note>
<variablelist>
<varlistentry>
- <term><literal>host</literal></term>
+ <term><function>PQconnectdbParams</function><indexterm><primary>PQconnectdbParams</></></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>
+ <para>
+ Makes a new connection to the database server.
- <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 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>
+ <synopsis>
+ PGconn *PQconnectdbParams(const char **keywords, const char **values, int expand_dbname);
+ </synopsis>
+ </para>
- <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>
+ <para>
+ This function opens a new database connection using the parameters taken
+ from two <symbol>NULL</symbol>-terminated arrays. The first,
+ <literal>keywords</literal>, is defined as an array of strings, each one
+ being a key word. The second, <literal>values</literal>, gives the value
+ for each key word. Unlike <function>PQsetdbLogin</> below, the parameter
+ set can be extended without changing the function signature, so use of
+ this function (or its nonblocking analogs <function>PQconnectStartParams</>
+ and <function>PQconnectPoll</function>) is preferred for new application
+ programming.
+ </para>
- <varlistentry>
- <term><literal>dbname</literal></term>
- <listitem>
- <para>
- The database name. Defaults to be the same as the user name.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ When <literal>expand_dbname</literal> is non-zero, the
+ <parameter>dbname</parameter> key word value is allowed to be recognized
+ as a <parameter>conninfo</parameter> string. See below for details.
+ </para>
- <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>
+ <para>
+ The passed arrays can be empty to use all default parameters, or can
+ contain one or more parameter settings. They should be matched in length.
+ Processing will stop with the last non-<symbol>NULL</symbol> element
+ of the <literal>keywords</literal> array.
+ </para>
- <varlistentry>
- <term><literal>password</literal></term>
- <listitem>
- <para>
- Password to be used if the server demands password authentication.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ The currently recognized parameter key words are:
+
+ <variablelist>
+ <varlistentry id="libpq-connect-host" xreflabel="host">
+ <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 id="libpq-connect-hostaddr" xreflabel="hostaddr">
+ <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, a host name is
+ required for Kerberos, GSSAPI, or SSPI authentication, as well as
+ for full SSL certificate verification. The following rules are
+ used:
+ 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 server address.
+ The connection attempt will fail in any of the cases where a
+ host name is required.
+ If both <literal>host</> and <literal>hostaddr</> are specified,
+ the value for <literal>hostaddr</> gives the server address.
+ The value for <literal>host</> is ignored unless needed for
+ authentication or verification purposes, in which case it will be
+ used as the host name. Note that authentication is likely to fail
+ if <literal>host</> is not the name of the machine at
+ <literal>hostaddr</>.
+ Also, note that <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 id="libpq-connect-port" xreflabel="port">
+ <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 id="libpq-connect-dbname" xreflabel="dbname">
+ <term><literal>dbname</literal></term>
+ <listitem>
+ <para>
+ The database name. Defaults to be the same as the user name.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-user" xreflabel="user">
+ <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 id="libpq-connect-password" xreflabel="password">
+ <term><literal>password</literal></term>
+ <listitem>
+ <para>
+ Password to be used if the server demands password authentication.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-connect-timeout" xreflabel="connect_timeout">
+ <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 id="libpq-connect-options" xreflabel="options">
+ <term><literal>options</literal></term>
+ <listitem>
+ <para>
+ Adds command-line options to send to the server at run-time.
+ For example, setting this to <literal>-c geqo=off</> sets the
+ session's value of the <varname>geqo</> parameter to
+ <literal>off</>. For a detailed discussion of the available
+ options, consult <xref linkend="runtime-config">.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-application-name" xreflabel="application_name">
+ <term><literal>application_name</literal></term>
+ <listitem>
+ <para>
+ Specifies a value for the <xref linkend="guc-application-name">
+ configuration parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-fallback-application-name" xreflabel="fallback_application_name">
+ <term><literal>fallback_application_name</literal></term>
+ <listitem>
+ <para>
+ Specifies a fallback value for the <xref
+ linkend="guc-application-name"> configuration parameter.
+ This value will be used if no value has been given for
+ <literal>application_name</> via a connection parameter or the
+ <envar>PGAPPNAME</envar> environment variable. Specifying
+ a fallback name is useful in generic utility programs that
+ wish to set a default application name but allow it to be
+ overridden by the user.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-keepalives" xreflabel="keepalives">
+ <term><literal>keepalives</literal></term>
+ <listitem>
+ <para>
+ Controls whether client-side TCP keepalives are used. The default
+ value is 1, meaning on, but you can change this to 0, meaning off,
+ if keepalives are not wanted. This parameter is ignored for
+ connections made via a Unix-domain socket.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-keepalives-idle" xreflabel="keepalives_idle">
+ <term><literal>keepalives_idle</literal></term>
+ <listitem>
+ <para>
+ Controls the number of seconds of inactivity after which TCP should
+ send a keepalive message to the server. A value of zero uses the
+ system default. This parameter is ignored for connections made via a
+ Unix-domain socket, or if keepalives are disabled. It is only supported
+ on systems where the <symbol>TCP_KEEPIDLE</> or <symbol>TCP_KEEPALIVE</>
+ socket option is available, and on Windows; on other systems, it has no
+ effect.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-keepalives-interval" xreflabel="keepalives_interval">
+ <term><literal>keepalives_interval</literal></term>
+ <listitem>
+ <para>
+ Controls the number of seconds after which a TCP keepalive message
+ that is not acknowledged by the server should be retransmitted. A
+ value of zero uses the system default. This parameter is ignored for
+ connections made via a Unix-domain socket, or if keepalives are disabled.
+ It is only supported on systems where the <symbol>TCP_KEEPINTVL</>
+ socket option is available, and on Windows; on other systems, it has no
+ effect.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-keepalives-count" xreflabel="keepalives_count">
+ <term><literal>keepalives_count</literal></term>
+ <listitem>
+ <para>
+ Controls the number of TCP keepalives that can be lost before the
+ client's connection to the server is considered dead. A value of
+ zero uses the system default. This parameter is ignored for
+ connections made via a Unix-domain socket, or if keepalives are disabled.
+ It is only supported on systems where the <symbol>TCP_KEEPINTVL</>
+ socket option is available; on other systems, it has no effect.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-tty" xreflabel="tty">
+ <term><literal>tty</literal></term>
+ <listitem>
+ <para>
+ Ignored (formerly, this specified where to send server debug output).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-sslmode" xreflabel="sslmode">
+ <term><literal>sslmode</literal></term>
+ <listitem>
+ <para>
+ This option determines whether or with what priority a secure
+ <acronym>SSL</> TCP/IP connection will be negotiated with the
+ server. There are six modes:
+ </para>
+
+ <table id="libpq-connect-sslmode-options">
+ <title><literal>sslmode</literal> options</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+
+ <row>
+ <entry><literal>disable</></entry>
+ <entry>only try a non-<acronym>SSL</> connection</entry>
+ </row>
+
+ <row>
+ <entry><literal>allow</></entry>
+ <entry>first try a non-<acronym>SSL</>
+ connection; if that fails, try an <acronym>SSL</>
+ connection</entry>
+ </row>
+
+ <row>
+ <entry><literal>prefer</> (default)</entry>
+ <entry>first try an <acronym>SSL</> connection; if
+ that fails, try a non-<acronym>SSL</>
+ connection</entry>
+ </row>
+
+ <row>
+ <entry><literal>require</></entry>
+ <entry>only try an <acronym>SSL</> connection</entry>
+ </row>
+
+ <row>
+ <entry><literal>verify-ca</></entry>
+ <entry>only try an <acronym>SSL</> connection, and verify that
+ the server certificate is issued by a trusted <acronym>CA</>
+ </entry>
+ </row>
+
+ <row>
+ <entry><literal>verify-full</></entry>
+ <entry>only try an <acronym>SSL</> connection, verify that
+ the server certificate is issued by a trusted <acronym>CA</> and
+ that the server hostname matches that in the certificate</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ See <xref linkend="libpq-ssl"> for a detailed description of how
+ these options work.
+ </para>
+
+ <para>
+ <literal>sslmode</> is ignored for Unix domain socket
+ communication.
+ If <productname>PostgreSQL</> is compiled without SSL support,
+ using options <literal>require</>, <literal>verify-ca</>, or
+ <literal>verify-full</> will cause an error, while
+ options <literal>allow</> and <literal>prefer</> will be
+ accepted but <application>libpq</> will not actually attempt
+ an <acronym>SSL</>
+ connection.<indexterm><primary>SSL</><secondary
+ sortas="libpq">with libpq</></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-requiressl" xreflabel="requiressl">
+ <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 id="libpq-connect-sslcert" xreflabel="sslcert">
+ <term><literal>sslcert</literal></term>
+ <listitem>
+ <para>
+ This parameter specifies the file name of the client SSL
+ certificate, replacing the default
+ <filename>~/.postgresql/postgresql.crt</>.
+ This parameter is ignored if an SSL connection is not made.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-sslkey" xreflabel="sslkey">
+ <term><literal>sslkey</literal></term>
+ <listitem>
+ <para>
+ This parameter specifies the location for the secret key used for
+ the client certificate. It can either specify a filename that will
+ be used instead of the default
+ <filename>~/.postgresql/postgresql.key</>, or it can specify a key
+ obtained from an external <quote>engine</> (engines are
+ <productname>OpenSSL</> loadable modules). An external engine
+ specification should consist of a colon-separated engine name and
+ an engine-specific key identifier. This parameter is ignored if an
+ SSL connection is not made.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-sslrootcert" xreflabel="sslrootcert">
+ <term><literal>sslrootcert</literal></term>
+ <listitem>
+ <para>
+ This parameter specifies the name of a file containing SSL
+ certificate authority (<acronym>CA</>) certificate(s).
+ If the file exists, the server's certificate will be verified
+ to be signed by one of these authorities. The default is
+ <filename>~/.postgresql/root.crt</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-sslcrl" xreflabel="sslcrl">
+ <term><literal>sslcrl</literal></term>
+ <listitem>
+ <para>
+ This parameter specifies the file name of the SSL certificate
+ revocation list (CRL). Certificates listed in this file, if it
+ exists, will be rejected while attempting to authenticate the
+ server's certificate. The default is
+ <filename>~/.postgresql/root.crl</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="libpq-connect-krbsrvname" xreflabel="krbsrvname">
+ <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 id="libpq-connect-gsslib" xreflabel="gsslib">
+ <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 id="libpq-connect-service" xreflabel="service">
+ <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>
- <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>
+ <para>
+ If <literal>expand_dbname</literal> is non-zero and
+ <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>(see below). Previously
+ processed key words will be overridden by key words in the
+ <parameter>conninfo</parameter> string.
+ </para>
- <varlistentry>
- <term><literal>options</literal></term>
- <listitem>
<para>
- Command-line options to be sent to the server.
+ In general key words are processed from the beginning of these arrays in index
+ order. The effect of this is that when key words are repeated, the last processed
+ value is retained. Therefore, through careful placement of the
+ <parameter>dbname</parameter> key word, it is possible to determine what may
+ be overridden by a <parameter>conninfo</parameter> string, and what may not.
</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>
+ <term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></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>
+ Makes a new connection to the database server.
- <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>
+ <synopsis>
+ PGconn *PQconnectdb(const char *conninfo);
+ </synopsis>
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>requiressl</literal></term>
- <listitem>
<para>
- This option is deprecated in favor of the <literal>sslmode</>
- setting.
+ This function opens a new database connection using the parameters taken
+ from the string <literal>conninfo</literal>.
</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.
+ 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>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>krbsrvname</literal></term>
- <listitem>
<para>
- Kerberos service name to use when authenticating with Kerberos 5.
- This must match the service name specified in the server
- configuration for Kerberos authentication to succeed. (See also
- <xref linkend="kerberos-auth">.)
+ The currently recognized parameter key words are the same as above.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>service</literal></term>
+ <term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></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>
+ <para>
Makes a new connection to the database server.
<synopsis>
PGconn *PQsetdbLogin(const char *pghost,
const char *login,
const char *pwd);
</synopsis>
- </para>
+ </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>
- 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>
+ <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>
- <varlistentry>
- <term><function>PQsetdb</function><indexterm><primary>PQsetdb</></></term>
- <listitem>
- <para>
+ <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>
+
+ <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 *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.
+ 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>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>
- You ensure that the socket is in the appropriate state
- before calling <function>PQconnectPoll</function>, as described below.
- </para>
- </listitem>
- </itemizedlist>
- </para>
+ <varlistentry>
+ <term><function>PQconnectStartParams</function><indexterm><primary>PQconnectStartParams</></></term>
+ <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.
- <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>
+ <synopsis>
+ PGconn *PQconnectStartParams(const char **keywords, const char **values, int expand_dbname);
+ </synopsis>
- <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:
+ <synopsis>
+ PGconn *PQconnectStart(const char *conninfo);
+ </synopsis>
- <variablelist>
- <varlistentry>
- <term><symbol>CONNECTION_STARTED</symbol></term>
- <listitem>
- <para>
- Waiting for connection to be made.
- </para>
- </listitem>
- </varlistentry>
+ <synopsis>
+ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
+ </synopsis>
+ </para>
- <varlistentry>
- <term><symbol>CONNECTION_MADE</symbol></term>
- <listitem>
- <para>
- Connection OK; waiting to send.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ These three 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>PQconnectdbParams</> or <function>PQconnectdb</>, and so the
+ application can manage this operation in parallel with other activities.
+ </para>
- <varlistentry>
- <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
- <listitem>
- <para>
- Waiting for a response from the server.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ With <function>PQconnectStartParams</function>, the database connection is made
+ using the parameters taken from the <literal>keywords</literal> and
+ <literal>values</literal> arrays, and controlled by <literal>expand_dbname</literal>,
+ as described above for <function>PQconnectdbParams</function>.
+ </para>
- <varlistentry>
- <term><symbol>CONNECTION_AUTH_OK</symbol></term>
- <listitem>
- <para>
- Received authentication; waiting for backend start-up to finish.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ With <function>PQconnectStart</function>, the database connection is made
+ using the parameters taken from the string <literal>conninfo</literal> as
+ described above for <function>PQconnectdb</function>.
+ </para>
- <varlistentry>
- <term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
- <listitem>
- <para>
- Negotiating SSL encryption.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ Neither <function>PQconnectStartParams</function> nor <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>PQconnectdbParams</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>
- <varlistentry>
- <term><symbol>CONNECTION_SETENV</symbol></term>
- <listitem>
- <para>
- Negotiating environment-driven parameter settings.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>
+ Note: use of <function>PQconnectStartParams</> is analogous to
+ <function>PQconnectStart</> shown below.
+ </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>
- 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:
+ <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:
+
+ <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_STARTED:
+ feedback = "Connecting...";
+ break;
- case CONNECTION_MADE:
- feedback = "Connected to server...";
- break;
+ case CONNECTION_MADE:
+ feedback = "Connected to server...";
+ break;
.
.
.
- default:
- feedback = "Connecting...";
+ default:
+ feedback = "Connecting...";
}
</programlisting>
- </para>
+ </para>
- <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>.
- </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>.
+ </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>
+ 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><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></term>
- <listitem>
- <para>
- Returns the default connection options.
+ <varlistentry>
+
<term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></term>
+ <listitem>
+ Returns the default connection options.
<synopsis>
PQconninfoOption *PQconndefaults(void);
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
+ char *dispchar; /* Indicates how to display this field
in a connect dialog. Values are:
"" Display entered value as is
"*" Password field - hide value
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>
- <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>
+ 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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>PQconninfoParse</function><indexterm><primary>PQconninfoParse</></></term>
+ <listitem>
+ <para>
+ Returns parsed connection options from the provided connection string.
- <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);
+PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
</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>
+ </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>
- 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>
+ <para>
+ Parses a connection string and returns the resulting options as an
+ array; or returns NULL if there is a problem with the connection
+ string. This can be used to determine
+ the <function>PQconnectdb</function> options in the provided
+ connection string. The return value points to an array of
+ <structname>PQconninfoOption</structname> structures, which ends
+ with an entry having a null <structfield>keyword</> pointer.
+ </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>
+ <para>
+ Note that only options explicitly specified in the string will have
+ values set in the result array; no defaults are inserted.
+ </para>
+
+ <para>
+ If <literal>errmsg</> is not NULL, then <literal>*errmsg</> is set
+ to NULL on success, else to a malloc'd error string explaining
+ the problem. (It is also possible for <literal>*errmsg</> to be
+ set to NULL even when NULL is returned; this indicates an out-of-memory
+ situation.)
+ </para>
+
+ <para>
+ After processing the options array, free it by passing it to
+ <function>PQconninfoFree</function>. If this is not done, some memory
+ is leaked for each call to <function>PQconninfoParse</function>.
+ Conversely, if an error occurs and <literal>errmsg</> is not NULL,
+ be sure to free the error string using <function>PQfreemem</>.
+ </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>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>
+
+ <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>PQconnectStartParams</>, <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>
- </variablelist>
-</para>
-</sect1>
+ </variablelist>
+ </para>
+ </sect1>
-<sect1 id="libpq-status">
-<title>Connection Status Functions</title>
+ <sect1 id="libpq-status">
+ <title>Connection Status Functions</title>
<para>
These functions can be used to interrogate the status
of an existing database connection object.
</para>
-<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>
+ <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</primary>
+ </indexterm>
+ </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</primary>
+ </indexterm>
+ </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</primary>
+ </indexterm>
+ </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</primary>
+ </indexterm>
+ </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</primary>
+ </indexterm>
+ </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</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>
-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>
+ <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</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
<para>
- The status can be one of a number of values.
- However, only two of these are
- seen outside of an asynchronous connection procedure:
+ Returns the status of the connection.
+ <synopsis>
+ ConnStatusType PQstatus(const PGconn *conn);
+ </synopsis>
+ </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>.
+ <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>
<para>
- See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
- to other status codes
- that might be seen.
+ See the entry for <function>PQconnectStartParams</>, <function>PQconnectStart</>
+ and <function>PQconnectPoll</> with regards to other status codes that
+ might be seen.
</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>PQtransactionStatus</function>
+ <indexterm>
+ <primary>PQtransactionStatus</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>
+ 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>
-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>
+ <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>PQerrorMessage</function><indexterm><primary>PQerrorMessage</></></term>
+ <term>
+ <function>PQparameterStatus</function>
+ <indexterm>
+ <primary>PQparameterStatus</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>
+ Looks up a current parameter setting of the server.
+
+ <synopsis>
+ const char *PQparameterStatus(const PGconn *conn, const char *paramName);
+ </synopsis>
+
+ 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>application_name</>,
+ <literal>is_superuser</>,
+ <literal>session_authorization</>,
+ <literal>DateStyle</>,
+ <literal>IntervalStyle</>,
+ <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;
+ <literal>IntervalStyle</> was not reported by releases before 8.4;
+ <literal>application_name</> was not reported by releases before 9.0.)
+ 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</primary>
+ </indexterm>
+ </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</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</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>
+
</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 can be multiple lines,
+ and 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>
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>
(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
</varlistentry>
<varlistentry>
- <term><function>PQgetssl</function><indexterm><primary>PQgetssl</></></term>
+ <term><function>PQconnectionNeedsPassword</function><indexterm><primary>PQconnectionNeedsPassword</></></term>
<listitem>
<para>
- <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>
+ Returns true (1) if the connection authentication method
+ required a password, but none was available.
+ Returns false (0) if not.
-<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>
+ int PQconnectionNeedsPassword(const PGconn *conn);
+ </synopsis>
</para>
+
<para>
- You must define <symbol>USE_SSL</symbol> in order to get the
- correct prototype for this function. Doing this will also
- automatically include <filename>ssl.h</filename> from <productname>OpenSSL</productname>.
+ This function can be applied after a failed connection attempt
+ to decide whether to prompt the user for a password.
</para>
</listitem>
</varlistentry>
-</variablelist>
-</para>
+ <varlistentry>
+ <term><function>PQconnectionUsedPassword</function><indexterm><primary>PQconnectionUsedPassword</></></term>
+ <listitem>
+ <para>
+ Returns true (1) if the connection authentication method
+ used a password. Returns false (0) if not.
-</sect1>
+ <synopsis>
+ int PQconnectionUsedPassword(const PGconn *conn);
+ </synopsis>
+ </para>
-<sect1 id="libpq-exec">
-<title>Command Execution Functions</title>
+ <para>
+ This function can be applied after either a failed or successful
+ connection attempt to detect whether the server demanded a password.
+ </para>
+ </listitem>
+ </varlistentry>
-<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>
+ <varlistentry>
+ <term><function>PQgetssl</function><indexterm><primary>PQgetssl</></></term>
+ <listitem>
+ <para>
+ <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.
-<sect2 id="libpq-exec-main">
- <title>Main Functions</title>
+ <synopsis>
+ SSL *PQgetssl(const PGconn *conn);
+ </synopsis>
+ </para>
-<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,
- int nParams,
- const Oid *paramTypes,
- const char * const *paramValues,
- const int *paramLengths,
- 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.
+ 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>
- </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.
+ You must define <symbol>USE_SSL</symbol> in order to get the
+ correct prototype for this function. Doing so will also
+ automatically include <filename>ssl.h</filename> from
+ <productname>OpenSSL</productname>.
</para>
- </listitem>
- </varlistentry>
+ </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>
+ </variablelist>
+ </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>
+ </sect1>
- <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>
+ <sect1 id="libpq-exec">
+ <title>Command Execution Functions</title>
- <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>
+ Once a connection to a database server has been successfully
+ established, the functions described here are used to perform
+ SQL queries and commands.
+ </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>
+ <sect2 id="libpq-exec-main">
+ <title>Main Functions</title>
- <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:
+ <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.
+
+<synopsis>
+PGresult *PQexecParams(PGconn *conn,
+ const char *command,
+ int nParams,
+ const Oid *paramTypes,
+ const char * const *paramValues,
+ const int *paramLengths,
+ 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>
+
+ <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>
+ <para>
+ Values passed in binary format require knowlege of
+ the internal representation expected by the backend.
+ For example, integers must be passed in network byte
+ order. Passing <type>numeric</> values requires
+ knowledge of the server storage format, as implemented
+ in
+ <filename>src/backend/utils/adt/numeric.c::numeric_send()</> and
+ <filename>src/backend/utils/adt/numeric.c::numeric_recv()</>.
+ </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>
+
+ <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:
<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,
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">
+ 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"> 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,
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>
-
- <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</></></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>
+ </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</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>
+ </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>
+
+ <listitem>
+ <para>
+ Returns the number of rows (tuples) in the query result. Because
+ it returns an integer result, large result sets might overflow the
+ return value on 32-bit operating systems.
+
+ <synopsis>
+ int PQntuples(const PGresult *res);
+ </synopsis>
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQnfields</function>
+ <indexterm>
+ <primary>PQnfields</primary>
+ </indexterm>
+ </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</primary>
+ </indexterm>
+ </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</primary>
+ </indexterm>
+ </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>
+
+ <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";
+</programlisting>
+ we would have the results:
+<programlisting>
+PQfname(res, 0) <lineannotation>foo</lineannotation>
+PQfname(res, 1) <lineannotation>BAR</lineannotation>
+PQfnumber(res, "FOO") <lineannotation>0</lineannotation>
+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</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 */
+} 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 Other Result Information</title>
+
+ <para>
+ These functions are used to extract other information from
+ <structname>PGresult</structname> objects.
+ </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>
+ 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>
+
+ <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 a <command>SELECT</>, <command>CREATE TABLE AS</>,
+ <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>
+
+ <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>escaping strings</primary>
+ <secondary>in libpq</secondary>
+ </indexterm>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQescapeLiteral</function>
+ <indexterm>
+ <primary>PQescapeLiteral</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ <synopsis>
+ size_t PQescapeLiteral(PGconn *conn, char *str, size_t len)
+ </synopsis>
+ </para>
+
+ <para>
+ <function>PQescapeLiteral</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>PQescapeLiteral</> performs this operation.
+ </para>
+
+ <para>
+ <function>PQescapeLiteral</> returns an escaped version of the
+ <parameter>str</parameter> parameter in memory allocated with
+ <function>malloc()</>. This memory should be freed using
+ <function>PQfreemem()</> when the result is no longer needed.
+ 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>PQescapeLiteral</> stops at the zero; the behavior is
+ thus rather like <function>strncpy</>.) The
+ return string has all special characters replaced so that they can
+ be properly processed by the <productname>PostgreSQL</productname>
+ string literal parser. A terminating zero byte is also added. The
+ single quotes that must surround <productname>PostgreSQL</productname>
+ string literals are included in the result string.
+ </para>
+
+ <para>
+ On error, <function>PQescapeLiteral</> returns NULL and a suitable
+ message is stored in the <parameter>conn</> object.
+ </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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQescapeIdentifier</function>
+ <indexterm>
+ <primary>PQescapeIdentifier</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ <synopsis>
+ size_t PQescapeIdentifier(PGconn *conn, char *str, size_t len)
+ </synopsis>
+ </para>
+
+ <para>
+ <function>PQescapeIndentifier</function> escapes a string for
+ use as an SQL identifier, such as a table, column, or function name.
+ This is useful when a user-supplied identifier might contain
+ special characters that would otherwise not be interpreted as part
+ of the identifier by the SQL parser, or when the identifier might
+ contain upper case characters whose case should be preserved.
+ </para>
+
+ <para>
+ <function>PQescapeIdentifier</> returns a version of the
+ <parameter>str</parameter> parameter escaped as an SQL identifier
+ in memory allocated with <function>malloc()</>. This memory must be
+ freed using <function>PQfreemem()</> when the result is no longer
+ needed. 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>PQescapeIdentifier</> stops at the zero; the behavior is
+ thus rather like <function>strncpy</>.) The
+ return string has all special characters replaced so that it
+ will be properly processed as an SQL identifier. A terminating zero byte
+ is also added. The return string will also be surrounded by double
+ quotes.
+ </para>
+
+ <para>
+ On error, <function>PQescapeIdentifier</> returns NULL and a suitable
+ message is stored in the <parameter>conn</> object.
+ </para>
+
+ <tip>
+ <para>
+ As with string literals, to prevent SQL injection attacks,
+ SQL identifiers must be escaped when they are received from an
+ untrustworthy source.
+ </para>
+ </tip>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQescapeStringConn</function>
+ <indexterm>
+ <primary>PQescapeStringConn</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ <synopsis>
+ size_t PQescapeStringConn (PGconn *conn,
+ char *to, const char *from, size_t length,
+ int *error);
+ </synopsis>
+ </para>
+
+ <para>
+ <function>PQescapeStringConn</> escapes string literals, much like
+ <function>PQescapeLiteral</>. Unlike <function>PQescapeLiteral</>,
+ the caller is responsible for providing an appropriately sized buffer.
+ Furthermore, <function>PQescapeStringConn</> does not generate the
+ single quotes that must surround <productname>PostgreSQL</> string
+ literals; 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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQescapeString</function>
+ <indexterm>
+ <primary>PQescapeString</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <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>
+ </listitem>
+ </varlistentry>
+
+ <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 should 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
+ — 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>
+ </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>
+
+ <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</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>
+ 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</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>
+ 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</primary>
+ </indexterm>
+ </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</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>
+ <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);
+
+ 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>
+
+ <indexterm zone="libpq-notify">
+ <primary>NOTIFY</primary>
+ <secondary>in libpq</secondary>
+ </indexterm>
+
+ <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 channel with the <command>LISTEN</command> command (and
+ can stop listening with the <command>UNLISTEN</command> command). All
+ sessions listening on a particular channel will be notified
+ asynchronously when a <command>NOTIFY</command> command with that
+ channel name is executed by any session. A <quote>payload</> string can
+ be passed to communicate additional data to the listeners.
+ </para>
+
+ <para>
+ <application>libpq</application> applications submit
+ <command>LISTEN</command>, <command>UNLISTEN</command>,
+ and <command>NOTIFY</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);
+
+ typedef struct pgNotify {
+ char *relname; /* notification channel name */
+ int be_pid; /* process ID of notifying server process */
+ char *extra; /* notification payload string */
+ } 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. (The names of these fields
+ are historical; in particular, channel names need not have anything to
+ do with relation names.)
+ </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>
+
+ <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>
+
+ <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"> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQfformat</function>
+ <indexterm>
+ <primary>PQfformat</primary>
+ <secondary>with COPY</secondary>
+ </indexterm>
+ </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</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"> 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>
+ 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</primary>
+ </indexterm>
+ </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 should 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>
+
+ <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>
+
+ <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</primary>
+ </indexterm>
+ </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</primary>
+ </indexterm>
+ </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</primary>
+ </indexterm>
+ </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>PQclientEncoding</function>
+ <indexterm>
+ <primary>PQclientEncoding</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns the client encoding.
+ <synopsis>
+ int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
+ </synopsis>
+
+ Note that it returns the encoding ID, not a symbolic string
+ such as <literal>EUC_JP</literal>. To convert an encoding ID to an encoding name, you
+ can use:
+
+<synopsis>
+char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
+</synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQsetClientEncoding</function>
+ <indexterm>
+ <primary>PQsetClientEncoding</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Sets the client encoding.
+ <synopsis>
+ int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
+ </synopsis>
+
+ <replaceable>conn</replaceable> is a connection to the server,
+ and <replaceable>encoding</replaceable> is the encoding you want to
+ use. If the function successfully sets the encoding, it returns 0,
+ otherwise -1. The current encoding for this connection can be
+ determined by using <function>PQclientEncoding</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+ <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</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>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>
+
+ <varlistentry>
+ <term>
+ <function>PQconninfoFree</function>
+ <indexterm>
+ <primary>PQconninfoFree</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Frees the data structures allocated by
+ <function>PQconndefaults</> or <function>PQconninfoParse</>.
+ <synopsis>
+ void PQconninfoFree(PQconninfoOption *connOptions);
+ </synopsis>
+ </para>
+
+ <para>
+ A simple <function>PQfreemem</function> will not do for this, since
+ the array contains references to subsidiary strings.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQencryptPassword</function>
+ <indexterm>
+ <primary>PQencryptPassword</primary>
+ </indexterm>
+ </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>
+
+ <varlistentry>
+ <term>
+ <function>PQmakeEmptyPGresult</function>
+ <indexterm>
+ <primary>PQmakeEmptyPGresult</primary>
+ </indexterm>
+ </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>.
+ Also, if <parameter>conn</parameter> is not null, any event procedures
+ registered in the connection are copied into the
+ <structname>PGresult</structname>. (They do not get
+ <literal>PGEVT_RESULTCREATE</> calls, but see
+ <function>PQfireResultCreateEvents</function>.)
+ 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>
+
+ <varlistentry>
+ <term>
+ <function>PQfireResultCreateEvents</function>
+ <indexterm>
+ <primary>PQfireResultCreateEvents</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Fires a <literal>PGEVT_RESULTCREATE</literal> event (see <xref
+ linkend="libpq-events">) for each event procedure registered in the
+ <structname>PGresult</structname> object. Returns non-zero for success,
+ zero if any event procedure fails.
+
+ <synopsis>
+ int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
+ </synopsis>
+ </para>
+
+ <para>
+ The <literal>conn</> argument is passed through to event procedures
+ but not used directly. It can be <literal>NULL</> if the event
+ procedures won't use it.
+ </para>
+
+ <para>
+ Event procedures that have already received a
+ <literal>PGEVT_RESULTCREATE</> or <literal>PGEVT_RESULTCOPY</> event
+ for this object are not fired again.
+ </para>
+
+ <para>
+ The main reason that this function is separate from
+ <function>PQmakeEmptyPGResult</function> is that it is often appropriate
+ to create a <structname>PGresult</structname> and fill it with data
+ before invoking the event procedures.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQcopyResult</function>
+ <indexterm>
+ <primary>PQcopyResult</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Makes a copy of a <structname>PGresult</structname> object. The copy is
+ not linked to the source result in any way and
+ <function>PQclear</function> must be called when the copy is no longer
+ needed. If the function fails, NULL is returned.
+
+ <synopsis>
+ PGresult *PQcopyResult(const PGresult *src, int flags);
+ </synopsis>
+ </para>
+
+ <para>
+ This is not intended to make an exact copy. The returned result is
+ always put into <literal>PGRES_TUPLES_OK</literal> status, and does not
+ copy any error message in the source. (It does copy the command status
+ string, however.) The <parameter>flags</parameter> argument determines
+ what else is copied. It is a bitwise OR of several flags.
+ <literal>PG_COPYRES_ATTRS</literal> specifies copying the source
+ result's attributes (column definitions).
+ <literal>PG_COPYRES_TUPLES</literal> specifies copying the source
+ result's tuples. (This implies copying the attributes, too.)
+ <literal>PG_COPYRES_NOTICEHOOKS</literal> specifies
+ copying the source result's notify hooks.
+ <literal>PG_COPYRES_EVENTS</literal> specifies copying the source
+ result's events. (But any instance data associated with the source
+ is not copied.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQsetResultAttrs</function>
+ <indexterm>
+ <primary>PQsetResultAttrs</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Sets the attributes of a <structname>PGresult</structname> object.
+ <synopsis>
+ int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
+ </synopsis>
+ </para>
+
+ <para>
+ The provided <parameter>attDescs</parameter> are copied into the result.
+ If the <parameter>attDescs</parameter> pointer is NULL or
+ <parameter>numAttributes</parameter> is less than one, the request is
+ ignored and the function succeeds. If <parameter>res</parameter>
+ already contains attributes, the function will fail. If the function
+ fails, the return value is zero. If the function succeeds, the return
+ value is non-zero.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQsetvalue</function>
+ <indexterm>
+ <primary>PQsetvalue</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Sets a tuple field value of a <structname>PGresult</structname> object.
+ <synopsis>
+ int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
+ </synopsis>
+ </para>
+
+ <para>
+ The function will automatically grow the result's internal tuples array
+ as needed. However, the <parameter>tup_num</parameter> argument must be
+ less than or equal to <function>PQntuples</function>, meaning this
+ function can only grow the tuples array one tuple at a time. But any
+ field of any existing tuple can be modified in any order. If a value at
+ <parameter>field_num</parameter> already exists, it will be overwritten.
+ If <parameter>len</parameter> is <literal>-1</literal> or
+ <parameter>value</parameter> is <literal>NULL</literal>, the field value
+ will be set to an SQL <literal>NULL</literal>. The
+ <parameter>value</parameter> is copied into the result's private storage,
+ thus is no longer needed after the function
+ returns. If the function fails, the return value is zero. If the
+ function succeeds, the return value is non-zero.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQresultAlloc</function>
+ <indexterm>
+ <primary>PQresultAlloc</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Allocate subsidiary storage for a <structname>PGresult</structname> object.
+ <synopsis>
+ void *PQresultAlloc(PGresult *res, size_t nBytes);
+ </synopsis>
+ </para>
+
+ <para>
+ Any memory allocated with this function will be freed when
+ <parameter>res</parameter> is cleared. If the function fails,
+ the return value is <literal>NULL</literal>. The result is
+ guaranteed to be adequately aligned for any type of data,
+ just as for <function>malloc</>.
+ </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-events">
+ <title>Event System</title>
+
+ <para>
+ <application>libpq</application>'s event system is designed to notify
+ registered event handlers about interesting
+ <application>libpq</application> events, such as the creation or
+ destruction of <structname>PGconn</structname> and
+ <structname>PGresult</structname> objects. A principal use case is that
+ this allows applications to associate their own data with a
+ <structname>PGconn</structname> or <structname>PGresult</structname>
+ and ensure that that data is freed at an appropriate time.
+ </para>
+
+ <para>
+ Each registered event handler is associated with two pieces of data,
+ known to <application>libpq</application> only as opaque <literal>void *</>
+ pointers. There is a <firstterm>passthrough</> pointer that is provided
+ by the application when the event handler is registered with a
+ <structname>PGconn</>. The passthrough pointer never changes for the
+ life of the <structname>PGconn</> and all <structname>PGresult</>s
+ generated from it; so if used, it must point to long-lived data.
+ In addition there is an <firstterm>instance data</> pointer, which starts
+ out NULL in every <structname>PGconn</> and <structname>PGresult</>.
+ This pointer can be manipulated using the
+ <function>PQinstanceData</function>,
+ <function>PQsetInstanceData</function>,
+ <function>PQresultInstanceData</function> and
+ <function>PQsetResultInstanceData</function> functions. Note that
+ unlike the passthrough pointer, instance data of a <structname>PGconn</>
+ is not automatically inherited by <structname>PGresult</>s created from
+ it. <application>libpq</application> does not know what passthrough
+ and instance data pointers point to (if anything) and will never attempt
+ to free them — that is the responsibility of the event handler.
+ </para>
+
+ <sect2 id="libpq-events-types">
+ <title>Event Types</title>
+
+ <para>
+ The enum <literal>PGEventId</> names the types of events handled by
+ the event system. All its values have names beginning with
+ <literal>PGEVT</literal>. For each event type, there is a corresponding
+ event info structure that carries the parameters passed to the event
+ handlers. The event types are:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>PGEVT_REGISTER</literal></term>
+ <listitem>
+ <para>
+ The register event occurs when <function>PQregisterEventProc</function>
+ is called. It is the ideal time to initialize any
+ <literal>instanceData</literal> an event procedure may need. Only one
+ register event will be fired per event handler per connection. If the
+ event procedure fails, the registration is aborted.
+
+ <synopsis>
+typedef struct
+{
+ PGconn *conn;
+} PGEventRegister;
+ </synopsis>
+
+ When a <literal>PGEVT_REGISTER</literal> event is received, the
+ <parameter>evtInfo</parameter> pointer should be cast to a
+ <structname>PGEventRegister *</structname>. This structure contains a
+ <structname>PGconn</structname> that should be in the
+ <literal>CONNECTION_OK</literal> status; guaranteed if one calls
+ <function>PQregisterEventProc</function> right after obtaining a good
+ <structname>PGconn</structname>. When returning a failure code, all
+ cleanup must be performed as no <literal>PGEVT_CONNDESTROY</literal>
+ event will be sent.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGEVT_CONNRESET</literal></term>
+ <listitem>
+ <para>
+ The connection reset event is fired on completion of
+ <function>PQreset</function> or <function>PQresetPoll</function>. In
+ both cases, the event is only fired if the reset was successful. If
+ the event procedure fails, the entire connection reset will fail; the
+ <structname>PGconn</structname> is put into
+ <literal>CONNECTION_BAD</literal> status and
+ <function>PQresetPoll</function> will return
+ <literal>PGRES_POLLING_FAILED</literal>.
+
+ <synopsis>
+typedef struct
+{
+ PGconn *conn;
+} PGEventConnReset;
+ </synopsis>
+
+ When a <literal>PGEVT_CONNRESET</literal> event is received, the
+ <parameter>evtInfo</parameter> pointer should be cast to a
+ <structname>PGEventConnReset *</structname>. Although the contained
+ <structname>PGconn</structname> was just reset, all event data remains
+ unchanged. This event should be used to reset/reload/requery any
+ associated <literal>instanceData</literal>. Note that even if the
+ event procedure fails to process <literal>PGEVT_CONNRESET</>, it will
+ still receive a <literal>PGEVT_CONNDESTROY</> event when the connection
+ is closed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGEVT_CONNDESTROY</literal></term>
+ <listitem>
+ <para>
+ The connection destroy event is fired in response to
+ <function>PQfinish</function>. It is the event procedure's
+ responsibility to properly clean up its event data as libpq has no
+ ability to manage this memory. Failure to clean up will lead
+ to memory leaks.
+
+ <synopsis>
+typedef struct
+{
+ PGconn *conn;
+} PGEventConnDestroy;
+ </synopsis>
+
+ When a <literal>PGEVT_CONNDESTROY</literal> event is received, the
+ <parameter>evtInfo</parameter> pointer should be cast to a
+ <structname>PGEventConnDestroy *</structname>. This event is fired
+ prior to <function>PQfinish</function> performing any other cleanup.
+ The return value of the event procedure is ignored since there is no
+ way of indicating a failure from <function>PQfinish</function>. Also,
+ an event procedure failure should not abort the process of cleaning up
+ unwanted memory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGEVT_RESULTCREATE</literal></term>
+ <listitem>
+ <para>
+ The result creation event is fired in response to any query execution
+ function that generates a result, including
+ <function>PQgetResult</function>. This event will only be fired after
+ the result has been created successfully.
+
+ <synopsis>
+typedef struct
+{
+ PGconn *conn;
+ PGresult *result;
+} PGEventResultCreate;
+ </synopsis>
+
+ When a <literal>PGEVT_RESULTCREATE</literal> event is received, the
+ <parameter>evtInfo</parameter> pointer should be cast to a
+ <structname>PGEventResultCreate *</structname>. The
+ <parameter>conn</parameter> is the connection used to generate the
+ result. This is the ideal place to initialize any
+ <literal>instanceData</literal> that needs to be associated with the
+ result. If the event procedure fails, the result will be cleared and
+ the failure will be propagated. The event procedure must not try to
+ <function>PQclear</> the result object for itself. When returning a
+ failure code, all cleanup must be performed as no
+ <literal>PGEVT_RESULTDESTROY</literal> event will be sent.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGEVT_RESULTCOPY</literal></term>
+ <listitem>
+ <para>
+ The result copy event is fired in response to
+ <function>PQcopyResult</function>. This event will only be fired after
+ the copy is complete. Only event procedures that have
+ successfully handled the <literal>PGEVT_RESULTCREATE</literal>
+ or <literal>PGEVT_RESULTCOPY</literal> event for the source result
+ will receive <literal>PGEVT_RESULTCOPY</literal> events.
+
+ <synopsis>
+typedef struct
+{
+ const PGresult *src;
+ PGresult *dest;
+} PGEventResultCopy;
+ </synopsis>
+
+ When a <literal>PGEVT_RESULTCOPY</literal> event is received, the
+ <parameter>evtInfo</parameter> pointer should be cast to a
+ <structname>PGEventResultCopy *</structname>. The
+ <parameter>src</parameter> result is what was copied while the
+ <parameter>dest</parameter> result is the copy destination. This event
+ can be used to provide a deep copy of <literal>instanceData</literal>,
+ since <literal>PQcopyResult</literal> cannot do that. If the event
+ procedure fails, the entire copy operation will fail and the
+ <parameter>dest</parameter> result will be cleared. When returning a
+ failure code, all cleanup must be performed as no
+ <literal>PGEVT_RESULTDESTROY</literal> event will be sent for the
+ destination result.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PGEVT_RESULTDESTROY</literal></term>
+ <listitem>
+ <para>
+ The result destroy event is fired in response to a
+ <function>PQclear</function>. It is the event procedure's
+ responsibility to properly clean up its event data as libpq has no
+ ability to manage this memory. Failure to clean up will lead
+ to memory leaks.
+
+ <synopsis>
+typedef struct
+{
+ PGresult *result;
+} PGEventResultDestroy;
+ </synopsis>
+
+ When a <literal>PGEVT_RESULTDESTROY</literal> event is received, the
+ <parameter>evtInfo</parameter> pointer should be cast to a
+ <structname>PGEventResultDestroy *</structname>. This event is fired
+ prior to <function>PQclear</function> performing any other cleanup.
+ The return value of the event procedure is ignored since there is no
+ way of indicating a failure from <function>PQclear</function>. Also,
+ an event procedure failure should not abort the process of cleaning up
+ unwanted memory.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="libpq-events-proc">
+ <title>Event Callback Procedure</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>PGEventProc</literal>
+ <indexterm>
+ <primary>PGEventProc</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ <literal>PGEventProc</literal> is a typedef for a pointer to an
+ event procedure, that is, the user callback function that receives
+ events from libpq. The signature of an event procedure must be
+
+ <synopsis>
+int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)
+ </synopsis>
+
+ The <parameter>evtId</parameter> parameter indicates which
+ <literal>PGEVT</literal> event occurred. The
+ <parameter>evtInfo</parameter> pointer must be cast to the appropriate
+ structure type to obtain further information about the event.
+ The <parameter>passThrough</parameter> parameter is the pointer
+ provided to <function>PQregisterEventProc</function> when the event
+ procedure was registered. The function should return a non-zero value
+ if it succeeds and zero if it fails.
+ </para>
+
+ <para>
+ A particular event procedure can be registered only once in any
+ <structname>PGconn</>. This is because the address of the procedure
+ is used as a lookup key to identify the associated instance data.
+ </para>
+
+ <caution>
+ <para>
+ On Windows, functions can have two different addresses: one visible
+ from outside a DLL and another visible from inside the DLL. One
+ should be careful that only one of these addresses is used with
+ <application>libpq</>'s event-procedure functions, else confusion will
+ result. The simplest rule for writing code that will work is to
+ ensure that event procedures are declared <literal>static</>. If the
+ procedure's address must be available outside its own source file,
+ expose a separate function to return the address.
+ </para>
+ </caution>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="libpq-events-funcs">
+ <title>Event Support Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQregisterEventProc</function>
+ <indexterm>
+ <primary>PQregisterEventProc</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Registers an event callback procedure with libpq.
+
+ <synopsis>
+ int PQregisterEventProc(PGconn *conn, PGEventProc proc,
+ const char *name, void *passThrough);
+ </synopsis>
+ </para>
+
+ <para>
+ An event procedure must be registered once on each
+ <structname>PGconn</> you want to receive events about. There is no
+ limit, other than memory, on the number of event procedures that
+ can be registered with a connection. The function returns a non-zero
+ value if it succeeds and zero if it fails.
+ </para>
+
+ <para>
+ The <parameter>proc</parameter> argument will be called when a libpq
+ event is fired. Its memory address is also used to lookup
+ <literal>instanceData</literal>. The <parameter>name</parameter>
+ argument is used to refer to the event procedure in error messages.
+ This value cannot be NULL or a zero-length string. The name string is
+ copied into the <structname>PGconn</>, so what is passed need not be
+ long-lived. The <parameter>passThrough</parameter> pointer is passed
+ to the <parameter>proc</parameter> whenever an event occurs. This
+ argument can be NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQsetInstanceData</function>
+ <indexterm>
+ <primary>PQsetInstanceData</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Sets the conn's instanceData for proc to data. This returns non-zero
+ for success and zero for failure. (Failure is only possible if
+ the proc has not been properly registered in the conn.)
+
+ <synopsis>
+ int PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQinstanceData</function>
+ <indexterm>
+ <primary>PQinstanceData</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Returns the conn's instanceData associated with proc, or NULL
+ if there is none.
+
+ <synopsis>
+ void *PQinstanceData(const PGconn *conn, PGEventProc proc);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQresultSetInstanceData</function>
+ <indexterm>
+ <primary>PQresultSetInstanceData</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Sets the result's instanceData for proc to data. This returns non-zero
+ for success and zero for failure. (Failure is only possible if the
+ proc has not been properly registered in the result.)
+
+ <synopsis>
+ int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQresultInstanceData</function>
+ <indexterm>
+ <primary>PQresultInstanceData</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Returns the result's instanceData associated with proc, or NULL
+ if there is none.
+
+ <synopsis>
+ void *PQresultInstanceData(const PGresult *res, PGEventProc proc);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="libpq-events-example">
+ <title>Event Example</title>
+
+ <para>
+ Here is a skeleton example of managing private data associated with
+ libpq connections and results.
+ </para>
+
+ <programlisting>
+<![CDATA[
+/* required header for libpq events (note: includes libpq-fe.h) */
+#include <libpq-events.h>
+
+/* The instanceData */
+typedef struct
+{
+ int n;
+ char *str;
+} mydata;
+
+/* PGEventProc */
+static int myEventProc(PGEventId evtId, void *evtInfo, void *passThrough);
+
+int
+main(void)
+{
+ mydata *data;
+ PGresult *res;
+ PGconn *conn = PQconnectdb("dbname = postgres");
+
+ if (PQstatus(conn) != CONNECTION_OK)
+ {
+ fprintf(stderr, "Connection to database failed: %s",
+ PQerrorMessage(conn));
+ PQfinish(conn);
+ return 1;
+ }
+
+ /* called once on any connection that should receive events.
+ * Sends a PGEVT_REGISTER to myEventProc.
+ */
+ if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL))
+ {
+ fprintf(stderr, "Cannot register PGEventProc\n");
+ PQfinish(conn);
+ return 1;
+ }
+
+ /* conn instanceData is available */
+ data = PQinstanceData(conn, myEventProc);
+
+ /* Sends a PGEVT_RESULTCREATE to myEventProc */
+ res = PQexec(conn, "SELECT 1 + 1");
+
+ /* result instanceData is available */
+ data = PQresultInstanceData(res, myEventProc);
+
+ /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */
+ res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS);
+
+ /* result instanceData is available if PG_COPYRES_EVENTS was
+ * used during the PQcopyResult call.
+ */
+ data = PQresultInstanceData(res_copy, myEventProc);
+
+ /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */
+ PQclear(res);
+ PQclear(res_copy);
+
+ /* Sends a PGEVT_CONNDESTROY to myEventProc */
+ PQfinish(conn);
+
+ return 0;
+}
+
+static int
+myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
+{
+ switch (evtId)
+ {
+ case PGEVT_REGISTER:
+ {
+ PGEventRegister *e = (PGEventRegister *)evtInfo;
+ mydata *data = get_mydata(e->conn);
+
+ /* associate app specific data with connection */
+ PQsetInstanceData(e->conn, myEventProc, data);
+ break;
+ }
+
+ case PGEVT_CONNRESET:
+ {
+ PGEventConnReset *e = (PGEventConnReset *)evtInfo;
+ mydata *data = PQinstanceData(e->conn, myEventProc);
+
+ if (data)
+ memset(data, 0, sizeof(mydata));
+ break;
+ }
+
+ case PGEVT_CONNDESTROY:
+ {
+ PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo;
+ mydata *data = PQinstanceData(e->conn, myEventProc);
+
+ /* free instance data because the conn is being destroyed */
+ if (data)
+ free_mydata(data);
+ break;
+ }
+
+ case PGEVT_RESULTCREATE:
+ {
+ PGEventResultCreate *e = (PGEventResultCreate *)evtInfo;
+ mydata *conn_data = PQinstanceData(e->conn, myEventProc);
+ mydata *res_data = dup_mydata(conn_data);
+
+ /* associate app specific data with result (copy it from conn) */
+ PQsetResultInstanceData(e->result, myEventProc, res_data);
+ break;
+ }
+
+ case PGEVT_RESULTCOPY:
+ {
+ PGEventResultCopy *e = (PGEventResultCopy *)evtInfo;
+ mydata *src_data = PQresultInstanceData(e->src, myEventProc);
+ mydata *dest_data = dup_mydata(src_data);
+
+ /* associate app specific data with result (copy it from a result) */
+ PQsetResultInstanceData(e->dest, myEventProc, dest_data);
+ break;
+ }
+
+ case PGEVT_RESULTDESTROY:
+ {
+ PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo;
+ mydata *data = PQresultInstanceData(e->result, myEventProc);
+
+ /* free instance data because the result is being destroyed */
+ if (data)
+ free_mydata(data);
+ break;
+ }
+
+ /* unknown event id, just return TRUE. */
+ default:
+ break;
+ }
+
+ return TRUE; /* event processing succeeded */
+}
+]]>
+</programlisting>
+ </sect2>
+ </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> behaves the same as the <xref
+ linkend="libpq-connect-host"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGHOSTADDR</envar></primary>
+ </indexterm>
+ <envar>PGHOSTADDR</envar> behaves the same as the <xref
+ linkend="libpq-connect-hostaddr"> connection parameter.
+ This can be set instead of or in addition to <envar>PGHOST</envar>
+ to avoid DNS lookup overhead.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGPORT</envar></primary>
+ </indexterm>
+ <envar>PGPORT</envar> behaves the same as the <xref
+ linkend="libpq-connect-port"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGDATABASE</envar></primary>
+ </indexterm>
+ <envar>PGDATABASE</envar> behaves the same as the <xref
+ linkend="libpq-connect-dbname"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGUSER</envar></primary>
+ </indexterm>
+ <envar>PGUSER</envar> behaves the same as the <xref
+ linkend="libpq-connect-user"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGPASSWORD</envar></primary>
+ </indexterm>
+ <envar>PGPASSWORD</envar> behaves the same as the <xref
+ linkend="libpq-connect-password"> connection parameter.
+ Use of this environment variable
+ is not recommended for security reasons, as 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> behaves the same as the <xref
+ linkend="libpq-connect-service"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSERVICEFILE</envar></primary>
+ </indexterm>
+ <envar>PGSERVICEFILE</envar> specifies the name of the per-user
+ connection service file. If not set, it defaults
+ to <filename>~/.pg_service.conf</>
+ (see <xref linkend="libpq-pgservice">).
+ </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> behaves the same as the <xref
+ linkend="libpq-connect-options"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGAPPNAME</envar></primary>
+ </indexterm>
+ <envar>PGAPPNAME</envar> behaves the same as the <xref
+ linkend="libpq-connect-application-name"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSSLMODE</envar></primary>
+ </indexterm>
+ <envar>PGSSLMODE</envar> behaves the same as the <xref
+ linkend="libpq-connect-sslmode"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGREQUIRESSL</envar></primary>
+ </indexterm>
+ <envar>PGREQUIRESSL</envar> behaves the same as the <xref
+ linkend="libpq-connect-requiressl"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSSLCERT</envar></primary>
+ </indexterm>
+ <envar>PGSSLCERT</envar> behaves the same as the <xref
+ linkend="libpq-connect-sslcert"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSSLKEY</envar></primary>
+ </indexterm>
+ <envar>PGSSLKEY</envar> behaves the same as the <xref
+ linkend="libpq-connect-sslkey"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSSLROOTCERT</envar></primary>
+ </indexterm>
+ <envar>PGSSLROOTCERT</envar> behaves the same as the <xref
+ linkend="libpq-connect-sslrootcert"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSSLCRL</envar></primary>
+ </indexterm>
+ <envar>PGSSLCRL</envar> behaves the same as the <xref
+ linkend="libpq-connect-sslcrl"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGKRBSRVNAME</envar></primary>
+ </indexterm>
+ <envar>PGKRBSRVNAME</envar> behaves the same as the <xref
+ linkend="libpq-connect-krbsrvname"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGGSSLIB</envar></primary>
+ </indexterm>
+ <envar>PGGSSLIB</envar> behaves the same as the <xref
+ linkend="libpq-connect-gsslib"> connection parameter.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGCONNECT_TIMEOUT</envar></primary>
+ </indexterm>
+ <envar>PGCONNECT_TIMEOUT</envar> behaves the same as the <xref
+ linkend="libpq-connect-connect-timeout"> connection parameter.
+ </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">
+ and <xref linkend="sql-alterdatabase">
+ 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">
+ 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 and in a future version
+ possibly other system-wide configuration files.
+ </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 (host name
+ <literal>localhost</>) and Unix domain socket (<literal>pghost</> empty
+ or the default socket directory) connections coming from the local
+ machine. In a standby server, a database name of <literal>replication</>
+ matches streaming replication connections made to the master server.
+ </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>
+ <indexterm zone="libpq-pgservice">
+ <primary>.pg_service.conf</primary>
+ </indexterm>
-<para>
- -1 is returned if the given name does not match any column.
-</para>
+ <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>
- 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";
-</programlisting>
- we would have the results:
+ <para>
+ The connection service file can be a per-user service file
+ at <filename>~/.pg_service.conf</filename> or the location
+ specified by the environment variable <envar>PGSERVICEFILE</envar>,
+ or it can be a system-wide file
+ at <filename>etc/pg_service.conf</filename> or in the directory
+ specified by the environment variable
+ <envar>PGSYSCONFDIR</envar>. If service definitions with the same
+ name exist in the user and the system file, the user file takes
+ precedence.
+ </para>
+
+ <para>
+ The file uses an <quote>INI file</quote> format where the section
+ name is the service name and the parameters are connection
+ parameters; see <xref linkend="libpq-connect"> for a list. For
+ example:
<programlisting>
-PQfname(res, 0) <lineannotation>foo</lineannotation>
-PQfname(res, 1) <lineannotation>BAR</lineannotation>
-PQfnumber(res, "FOO") <lineannotation>0</lineannotation>
-PQfnumber(res, "foo") <lineannotation>0</lineannotation>
-PQfnumber(res, "BAR") <lineannotation>-1</lineannotation>
-PQfnumber(res, "\"BAR\"") <lineannotation>1</lineannotation>
+# comment
+[mydb]
+host=somehost
+port=5433
+user=admin
</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>
-void PQprint(FILE *fout, /* output stream */
- const PGresult *res,
- const PQprintOpt *po);
+ An example file is provided at
+ <filename>share/pg_service.conf.sample</filename>.
+ </para>
+ </sect1>
-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 */
-} 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>
-<para>
-This function is deprecated in favor of <function>PQoidValue</function>.
-It is not thread-safe.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
+ <sect1 id="libpq-ldap">
+ <title>LDAP Lookup of Connection Parameters</title>
-</sect2>
+ <indexterm zone="libpq-ldap">
+ <primary>LDAP connection parameter lookup</primary>
+ </indexterm>
-<sect2 id="libpq-exec-escape-string">
- <title>Escaping Strings for Inclusion in SQL Commands</title>
+ <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>
- <indexterm zone="libpq-exec-escape-string"><primary>PQescapeStringConn</></>
- <indexterm zone="libpq-exec-escape-string"><primary>PQescapeString</></>
- <indexterm zone="libpq-exec-escape-string">
- <primary>escaping strings</>
- <secondary>in libpq</secondary>
- </>
-
-<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>
+ 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>
-<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</>
- <secondary sortas="libpq">in libpq</>
+ <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>
+
+ <para>
+ You can also mix regular service file entries with LDAP lookups.
+ A complete example for a stanza in <filename>pg_service.conf</filename>
+ would be:
+ <synopsis>
+ # only host and port are stored in LDAP, specify dbname and user explicitly
+ [customerdb]
+ dbname=customer
+ user=appuser
+ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
+ </synopsis>
+ </para>
+
+ </sect1>
+
+
+ <sect1 id="libpq-ssl">
+ <title>SSL Support</title>
+
+ <indexterm zone="libpq-ssl">
+ <primary>SSL</primary>
</indexterm>
- <variablelist>
- <varlistentry>
- <term><function>PQescapeByteaConn</function><indexterm><primary>PQescapeByteaConn</></></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.
+ <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>
- 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.
+ <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
+ <envar>OPENSSL_CONF</envar> to the name of the desired configuration
+ file.
</para>
+ <sect2 id="libq-ssl-certificates">
+ <title>Certificate verification</title>
+
<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.
+ By default, <productname>PostgreSQL</> will not perform any verification of
+ the server certificate. This means that it is possible to spoof the server
+ identity (for example by modifying a DNS record or by taking over the server
+ IP address) without the client knowing. In order to prevent spoofing,
+ <acronym>SSL</> certificate verification must be used.
</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.
+ If the parameter <literal>sslmode</> is set to <literal>verify-ca</>,
+ libpq will verify that the server is trustworthy by checking the
+ certificate chain up to a trusted certificate authority
+ (<acronym>CA</>). If <literal>sslmode</> is set to <literal>verify-full</>,
+ libpq will <emphasis>also</> verify that the server hostname matches its
+ certificate. The SSL connection will fail if the server certificate cannot
+ be verified. <literal>verify-full</> is recommended in most
+ security-sensitive environments.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>PQescapeBytea</function><indexterm><primary>PQescapeBytea</></></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.
+ In <literal>verify-full</> mode, the <literal>cn</> (Common Name) attribute
+ of the certificate is matched against the hostname. If the <literal>cn</>
+ attribute starts with an asterisk (<literal>*</>), it will be treated as
+ a wildcard, and will match all characters <emphasis>except</> a dot
+ (<literal>.</>). This means the certificate will not match subdomains.
+ If the connection is made using an IP address instead of a hostname, the
+ IP address will be matched (without doing any DNS lookups).
+ </para>
+
+ <para>
+ To allow server certificate verification, the certificate(s) of one or more
+ trusted <acronym>CA</>s must be
+ placed in the file <filename>~/.postgresql/root.crt</> in the user's home
+ directory. (On Microsoft Windows the file is named
+ <filename>%APPDATA%\postgresql\root.crt</filename>.)
</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</>.
+ 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).
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>PQunescapeBytea</function><indexterm><primary>PQunescapeBytea</></></term>
- <listitem>
<para>
- Converts a string representation of binary data into binary
- data — 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.
+ The location of the root certificate file and the CRL can be changed by
+ setting
+ the connection parameters <literal>sslrootcert</> and <literal>sslcrl</>
+ or the environment variables <envar>PGSSLROOTCERT</> and <envar>PGSSLCRL</>.
+ </para>
+ </sect2>
-<synopsis>
-unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
-</synopsis>
-</para>
+ <sect2 id="libpq-ssl-clientcert">
+ <title>Client certificates</title>
<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.
+ If the server requests a trusted client certificate,
+ <application>libpq</application> will send the certificate stored in
+ file <filename>~/.postgresql/postgresql.crt</> in the user's home
+ directory. The certificate must be signed by one of the certificate
+ authorities (<acronym>CA</acronym>) trusted by the server. A matching
+ private key file <filename>~/.postgresql/postgresql.key</> must also
+ be present. The private
+ key file must not allow any access to world or group; achieve this by the
+ command <command>chmod 0600 ~/.postgresql/postgresql.key</command>.
+ On Microsoft Windows these files are named
+ <filename>%APPDATA%\postgresql\postgresql.crt</filename> and
+ <filename>%APPDATA%\postgresql\postgresql.key</filename>, and there
+ is no special permissions check since the directory is presumed secure.
+ The location of the certificate and key files can be overridden by the
+ connection parameters <literal>sslcert</> and <literal>sslkey</> or the
+ environment variables <envar>PGSSLCERT</> and <envar>PGSSLKEY</>.
</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.
+ In some cases, the client certificate might be signed by an
+ <quote>intermediate</> certificate authority, rather than one that is
+ directly trusted by the server. To use such a certificate, append the
+ certificate of the signing authority to the <filename>postgresql.crt</>
+ file, then its parent authority's certificate, and so on up to a
+ <quote>root</> authority that is trusted by the server. The root
+ certificate should be included in every case where
+ <filename>postgresql.crt</> contains more than one certificate.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>PQfreemem</function><indexterm><primary>PQfreemem</></></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 needed by Microsoft Windows, which cannot free memory across
- DLLs, unless multithreaded DLLs (<option>/MD</option> in VC6) are used.
- On other platforms, this function is the same as the standard library function <function>free()</>.
+ Note that <filename>root.crt</filename> lists the top-level CAs that are
+ considered trusted for signing server certificates. In principle it need
+ not list the CA that signed the client's certificate, though in most cases
+ that CA would also be trusted for server certificates.
</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
+
</sect2>
-</sect1>
-
-<sect1 id="libpq-async">
-<title>Asynchronous Command Processing</title>
-
- <indexterm zone="libpq-async"><primary>nonblocking connection</></>
-
-<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>
+ <sect2 id="libpq-ssl-protection">
+ <title>Protection provided in different modes</title>
- 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>
+ <para>
+ The different values for the <literal>sslmode</> parameter provide different
+ levels of protection. SSL can provide
+ protection against three types of attacks:
+ </para>
+ <table id="libpq-ssl-protect-attacks">
+ <title>SSL attacks</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Eavesdropping</entry>
+ <entry>If a third party can examine the network traffic between the
+ client and the server, it can read both connection information (including
+ the username and password) and the data that is passed. <acronym>SSL</>
+ uses encryption to prevent this.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Man in the middle (<acronym>MITM</>)</entry>
+ <entry>If a third party can modify the data while passing between the
+ client and server, it can pretend to be the server and therefore see and
+ modify data <emphasis>even if it is encrypted</>. The third party can then
+ forward the connection information and data to the original server,
+ making it impossible to detect this attack. Common vectors to do this
+ include DNS poisoning and address hijacking, whereby the client is directed
+ to a different server than intended. There are also several other
+ attack methods that can accomplish this. <acronym>SSL</> uses certificate
+ verification to prevent this, by authenticating the server to the client.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Impersonation</entry>
+ <entry>If a third party can pretend to be an authorized client, it can
+ simply access data it should not have access to. Typically this can
+ happen through insecure password management. <acronym>SSL</> uses
+ client certificates to prevent this, by making sure that only holders
+ of valid certificates can access the server.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- 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>
+ <para>
+ For a connection to be known secure, SSL usage must be configured
+ on <emphasis>both the client and the server</> before the connection
+ is made. If it is only configured on the server, the client may end up
+ sending sensitive information (e.g. passwords) before
+ it knows that the server requires high security. In libpq, secure
+ connections can be ensured
+ by setting the <literal>sslmode</> parameter to <literal>verify-full</> or
+ <literal>verify-ca</>, and providing the system with a root certificate to
+ verify against. This is analogous to using an <literal>https</>
+ <acronym>URL</> for encrypted web browsing.
+ </para>
- 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>
+ <para>
+ Once the server has been authenticated, the client can pass sensitive data.
+ This means that up until this point, the client does not need to know if
+ certificates will be used for authentication, making it safe to specify that
+ only in the server configuration.
+ </para>
- 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>
+ <para>
+ All <acronym>SSL</> options carry overhead in the form of encryption and
+ key-exchange, so there is a tradeoff that has to be made between performance
+ and security. The following table illustrates the risks the different
+ <literal>sslmode</> values protect against, and what statement they make
+ about security and overhead:
+ </para>
- 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>
- <para>
- Sets the nonblocking status of the connection.
-<synopsis>
-int PQsetnonblocking(PGconn *conn, int arg);
-</synopsis>
-</para>
+ <table id="libpq-ssl-sslmode-statements">
+ <title>SSL mode descriptions</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry><literal>sslmode</></entry>
+ <entry>Eavesdropping protection</entry>
+ <entry><acronym>MITM</> protection</entry>
+ <entry>Statement</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>disabled</></entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ <entry>I don't care about security, and I don't want to pay the overhead
+ of encryption.
+ </entry>
+ </row>
+
+ <row>
+ <entry><literal>allow</></entry>
+ <entry>Maybe</entry>
+ <entry>No</entry>
+ <entry>I don't care about security, but I will pay the overhead of
+ encryption if the server insists on it.
+ </entry>
+ </row>
+
+ <row>
+ <entry><literal>prefer</></entry>
+ <entry>Maybe</entry>
+ <entry>No</entry>
+ <entry>I don't care about encryption, but I wish to pay the overhead of
+ encryption if the server supports it.
+ </entry>
+ </row>
+
+ <row>
+ <entry><literal>require</></entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ <entry>I want my data to be encrypted, and I accept the overhead. I trust
+ that the network will make sure I always connect to the server I want.
+ </entry>
+ </row>
+
+ <row>
+ <entry><literal>verify-ca</></entry>
+ <entry>Yes</entry>
+ <entry><literal>Depends on CA</>-policy</entry>
+ <entry>I want my data encrypted, and I accept the overhead. I want to be
+ sure that I connect to a server that I trust.
+ </entry>
+ </row>
+
+ <row>
+ <entry><literal>verify-full</></entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ <entry>I want my data encrypted, and I accept the overhead. I want to be
+ sure that I connect to a server I trust, and that it's the one I
+ specify.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
-<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>
+ <para>
+ The difference between <literal>verify-ca</> and <literal>verify-full</>
+ depends on the policy of the root <acronym>CA</>. If a public
+ <acronym>CA</> is used, <literal>verify-ca</> allows connections to a server
+ that <emphasis>somebody else</> may have registered with the <acronym>CA</>.
+ In this case, <literal>verify-full</> should always be used. If
+ a local <acronym>CA</> is used, or even a self-signed certificate, using
+ <literal>verify-ca</> often provides enough protection.
+ </para>
-<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</><secondary>SQL command</></>
-
-<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</></>
-
-<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);
+ <para>
+ The default value for <literal>sslmode</> is <literal>prefer</>. As is shown
+ in the table, this makes no sense from a security point of view, and it only
+ promises performance overhead if possible. It is only provided as the default
+ for backwards compatibility, and is not recommended in secure deployments.
+ </para>
-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>
+ </sect2>
- <indexterm zone="libpq-notify">
- <primary>NOTIFY</primary>
- <secondary>in libpq</secondary>
- </indexterm>
+ <sect2 id="libpq-ssl-fileusage">
+ <title>SSL File Usage</title>
+ <table id="libpq-ssl-file-usage">
+ <title>Libpq/Client SSL File Usage</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>File</entry>
+ <entry>Contents</entry>
+ <entry>Effect</entry>
+ </row>
+ </thead>
+
+ <tbody>
+
+ <row>
+ <entry><filename>~/.postgresql/postgresql.crt</></entry>
+ <entry>client certificate</entry>
+ <entry>requested by server</entry>
+ </row>
+
+ <row>
+ <entry><filename>~/.postgresql/postgresql.key</></entry>
+ <entry>client private key</entry>
+ <entry>proves client certificate sent by owner; does not indicate
+ certificate owner is trustworthy</entry>
+ </row>
+
+ <row>
+ <entry><filename>~/.postgresql/root.crt</></entry>
+ <entry>trusted certificate authorities</entry>
+ <entry>checks that server certificate is signed by a trusted certificate
+ authority</entry>
+ </row>
+
+ <row>
+ <entry><filename>~/.postgresql/root.crl</></entry>
+ <entry>certificates revoked by certificate authorities</entry>
+ <entry>server certificate must not be on this list</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
-<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);
+ <sect2 id="libpq-ssl-initialize">
+ <title>SSL library initialization</title>
-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>
+ If your application initializes <literal>libssl</> and/or
+ <literal>libcrypto</> libraries and <application>libpq</application>
+ is built with <acronym>SSL</> support, you should call
+ <function>PQinitOpenSSL</> to tell <application>libpq</application>
+ that the <literal>libssl</> and/or <literal>libcrypto</> libraries
+ have been initialized by your application, so that
+ <application>libpq</application> will not also initialize those libraries.
+ <!-- If this URL changes replace it with a URL to www.archive.org. -->
+ See <ulink
+ url="http://h71000.www7.hp.com/doc/83final/BA554_90007/ch04.html"></ulink>
+ for details on the SSL API.
+ </para>
-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.
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQinitOpenSSL</function>
+ <indexterm>
+ <primary>PQinitOpenSSL</primary>
+ </indexterm>
+ </term>
-<synopsis>
-typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
+ <listitem>
+ <para>
+ Allows applications to select which security libraries to initialize.
+ <synopsis>
+ void PQinitOpenSSL(int do_ssl, int do_crypto);
+ </synopsis>
+ </para>
-PQnoticeReceiver
-PQsetNoticeReceiver(PGconn *conn,
- PQnoticeReceiver proc,
- void *arg);
+ <para>
+ When <parameter>do_ssl</> is non-zero, <application>libpq</application>
+ will initialize the <application>OpenSSL</> library before first
+ opening a database connection. When <parameter>do_crypto</> is
+ non-zero, the <literal>libcrypto</> library will be initialized. By
+ default (if <function>PQinitOpenSSL</> is not called), both libraries
+ are initialized. When SSL support is not compiled in, this function is
+ present but does nothing.
+ </para>
-typedef void (*PQnoticeProcessor) (void *arg, const char *message);
+ <para>
+ If your application uses and initializes either <application>OpenSSL</>
+ or its underlying <literal>libcrypto</> library, you <emphasis>must</>
+ call this function with zeroes for the appropriate parameter(s)
+ before first opening a database connection. Also be sure that you
+ have done that initialization before opening a database connection.
+ </para>
+ </listitem>
+ </varlistentry>
-PQnoticeProcessor
-PQsetNoticeProcessor(PGconn *conn,
- PQnoticeProcessor proc,
- void *arg);
-</synopsis>
+ <varlistentry>
+ <term>
+ <function>PQinitSSL</function>
+ <indexterm>
+ <primary>PQinitSSL</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>
-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>PGKRBSRVNAME</envar></primary>
-</indexterm>
-<envar>PGKRBSRVNAME</envar> sets the Kerberos service name to use when
-authenticating with Kerberos 5.
-</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>
-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.
-(The file permissions are not currently checked on Microsoft Windows,
-however.)
-</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>
+ <listitem>
+ <para>
+ Allows applications to select which security libraries to initialize.
+ <synopsis>
+ void PQinitSSL(int do_ssl);
+ </synopsis>
+ </para>
+
+ <para>
+ This function is equivalent to
+ <literal>PQinitOpenSSL(do_ssl, do_ssl)</>.
+ It is sufficient for applications that initialize both or neither
+ of <application>OpenSSL</> and <literal>libcrypto</>.
+ </para>
+
+ <para>
+ <function>PQinitSSL</> has been present since
+ <productname>PostgreSQL</> 8.0, while <function>PQinitOpenSSL</>
+ was added in <productname>PostgreSQL</> 8.4, so <function>PQinitSSL</>
+ might be preferable for applications that need to work with older
+ versions of <application>libpq</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+
+ </sect1>
-<sect1 id="libpq-ssl">
-<title>SSL Support</title>
+ <sect1 id="libpq-threading">
+ <title>Behavior in Threaded Programs</title>
-<indexterm zone="libpq-ssl">
- <primary>SSL</primary>
-</indexterm>
+ <indexterm zone="libpq-threading">
+ <primary>threads</primary>
+ <secondary>with libpq</secondary>
+ </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.
+ <application>libpq</application> is reentrant and thread-safe by default.
+ You might need to use special 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>
- 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, and must not be world-readable.
- (On Microsoft Windows these files are named
- <filename>%APPDATA%\postgresql\postgresql.crt</filename> and
- <filename>%APPDATA%\postgresql\postgresql.key</filename>.)
+ 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>
- 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.
- (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
- use this feature the server must also have a <filename>root.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).
+ <structname>PGresult</> objects are read-only after creation, and so
+ can be passed around freely between threads.
</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.
+ 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>
-</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>
+ <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">
<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>
<programlisting>
#include <libpq-fe.h>
</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)
<para>
Failure to specify the correct option to the compiler will
- result in an error message such as
+ result in an error message such as:
<screen>
testlibpq.c:8:22: libpq-fe.h: No such file or directory
</screen>
<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:
</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'
<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>
<title><application>libpq</application> Example Program 1</title>
<programlisting>
+<![CDATA[
/*
* testlibpq.c
*
* Test the C version of libpq, the PostgreSQL frontend library.
*/
-#include <stdio.h>
-#include <stdlib.h>
-#include "libpq-fe.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <libpq-fe.h>
static void
exit_nicely(PGconn *conn)
* conninfo string; otherwise default to setting dbname=postgres and using
* environment variables or defaults for all other connection parameters.
*/
- if (argc > 1)
+ if (argc > 1)
conninfo = argv[1];
else
conninfo = "dbname = postgres";
/* first, print out the attribute names */
nFields = PQnfields(res);
- for (i = 0; i < nFields; i++)
+ for (i = 0; i < nFields; i++)
printf("%-15s", PQfname(res, i));
printf("\n\n");
/* next, print out the rows */
- for (i = 0; i < PQntuples(res); i++)
+ for (i = 0; i < PQntuples(res); i++)
{
- for (j = 0; j < nFields; j++)
+ for (j = 0; j < nFields; j++)
printf("%-15s", PQgetvalue(res, i, j));
printf("\n");
}
return 0;
}
+]]>
</programlisting>
</example>
<title><application>libpq</application> Example Program 2</title>
<programlisting>
+<![CDATA[
/*
* testlibpq2.c
* Test of the asynchronous notification interface
*
* INSERT INTO TBL1 VALUES (10);
*/
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include <errno.h>
-#include <sys/time.h>
-#include "libpq-fe.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <errno.h>
+#include <sys/time.h>
+#include <libpq-fe.h>
static void
exit_nicely(PGconn *conn)
* conninfo string; otherwise default to setting dbname=postgres and using
* environment variables or defaults for all other connection parameters.
*/
- if (argc > 1)
+ if (argc > 1)
conninfo = argv[1];
else
conninfo = "dbname = postgres";
/* Quit after four notifies are received. */
nnotifies = 0;
- while (nnotifies < 4)
+ while (nnotifies < 4)
{
/*
* Sleep until something happens on the connection. We use select(2)
sock = PQsocket(conn);
- if (sock < 0)
+ if (sock < 0)
break; /* shouldn't happen */
- FD_ZERO(&input_mask);
- FD_SET(sock, &input_mask);
+ FD_ZERO(&input_mask);
+ FD_SET(sock, &input_mask);
- if (select(sock + 1, &input_mask, NULL, NULL, NULL) < 0)
+ if (select(sock + 1, &input_mask, NULL, NULL, NULL) < 0)
{
fprintf(stderr, "select() failed: %s\n", strerror(errno));
exit_nicely(conn);
{
fprintf(stderr,
"ASYNC NOTIFY of '%s' received from backend pid %d\n",
- notify->relname, notify->be_pid);
+ notify->relname, notify->be_pid);
PQfreemem(notify);
nnotifies++;
}
return 0;
}
+]]>
</programlisting>
</example>
<title><application>libpq</application> Example Program 3</>
<programlisting>
+<![CDATA[
/*
* testlibpq3.c
* Test out-of-line parameters and binary I/O.
* t = (8 bytes) 'ho there'
* b = (5 bytes) \004\003\002\001\000
*/
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include <sys/types.h>
-#include "libpq-fe.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <libpq-fe.h>
/* for ntohl/htonl */
-#include <netinet/in.h>
-#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <arpa/inet.h>
static void
t_fnum = PQfnumber(res, "t");
b_fnum = PQfnumber(res, "b");
- for (i = 0; i < PQntuples(res); i++)
+ for (i = 0; i < PQntuples(res); i++)
{
char *iptr;
char *tptr;
printf(" t = (%d bytes) '%s'\n",
PQgetlength(res, i, t_fnum), tptr);
printf(" b = (%d bytes) ", blen);
- for (j = 0; j < blen; j++)
+ for (j = 0; j < blen; j++)
printf("\\%03o", bptr[j]);
printf("\n\n");
}
* conninfo string; otherwise default to setting dbname=postgres and using
* environment variables or defaults for all other connection parameters.
*/
- if (argc > 1)
+ if (argc > 1)
conninfo = argv[1];
else
conninfo = "dbname = postgres";
binaryIntVal = htonl((uint32_t) 2);
/* Set up parameter arrays for PQexecParams */
- paramValues[0] = (char *) &binaryIntVal;
+ paramValues[0] = (char *) &binaryIntVal;
paramLengths[0] = sizeof(binaryIntVal);
paramFormats[0] = 1; /* binary */
return 0;
}
+]]>
</programlisting>
</example>
projects / postgresql / blobdiff