-<!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.167 2004/10/30 23:09:59 tgl Exp $
--->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.257 2008/03/31 02:43:14 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.
- <application>libpq</> is also the underlying engine for several
- other <productname>PostgreSQL</> application interfaces, including
- those written for C++, TCL, Perl, Python and <application>ECPG</>.
- So some aspects of <application>libpq</>'s behavior will be
- important to you if you use one of those packages.
- </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>
application program can have several backend connections open at
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
+ <structname>PGconn</><indexterm><primary>PGconn</></> object, which
is obtained from the function <function>PQconnectdb</> or
<function>PQsetdbLogin</>. Note that these functions will always
return a non-null object pointer, unless perhaps there is too
<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>.
- (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>.)
- Spaces around the equal sign are optional.
- </para>
+ <synopsis>
+ PGconn *PQconnectdb(const char *conninfo);
+ </synopsis>
+ </para>
- <para>
- The currently recognized parameter key words are:
+ <para>
+ This function opens a new database connection using the parameters taken
+ from the string <literal>conninfo</literal>. Unlike <function>PQsetdbLogin</> below,
+ the parameter set can be extended without changing the function signature,
+ so use of this function (or its nonblocking analogues <function>PQconnectStart</>
+ and <function>PQconnectPoll</function>) is preferred for new application programming.
+ </para>
+
+ <para>
+ The passed string
+ can be empty to use all default parameters, or it can contain one or more
+ parameter settings separated by whitespace.
+ Each parameter setting is in the form <literal>keyword = value</literal>.
+ Spaces around the equal sign are optional.
+ To write an empty value or a value containing
+ spaces, surround it with single quotes, e.g.,
+ <literal>keyword = 'a value'</literal>.
+ Single quotes and backslashes within the value must be escaped with a
+ backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
+ </para>
+
+ <para>
+ The currently recognized parameter key words are:
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>host</literal></term>
+ <listitem>
+ <para>
+ Name of host to connect to.<indexterm><primary>host name</></>
+ If this begins with a slash, it specifies Unix-domain
+ communication rather than TCP/IP communication; the value is the
+ name of the directory in which the socket file is stored. The
+ default behavior when <literal>host</literal> is not specified
+ is to connect to a Unix-domain
+ socket<indexterm><primary>Unix domain socket</></> in
+ <filename>/tmp</filename> (or whatever socket directory was specified
+ when <productname>PostgreSQL</> was built). On machines without
+ Unix-domain sockets, the default is to connect to <literal>localhost</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>hostaddr</literal></term>
+ <listitem>
+ <para>
+ Numeric IP address of host to connect to. This should be in the
+ standard IPv4 address format, e.g., <literal>172.28.40.9</>. If
+ your machine supports IPv6, you can also use those addresses.
+ TCP/IP communication is
+ always used when a nonempty string is specified for this parameter.
+ </para>
+
+ <para>
+ Using <literal>hostaddr</> instead of <literal>host</> allows the
+ application to avoid a host name look-up, which might be important in
+ applications with time constraints. However, Kerberos and GSSAPI authentication
+ requires the host name. The following therefore applies: If
+ <literal>host</> is specified without <literal>hostaddr</>, a host name
+ lookup occurs. If <literal>hostaddr</> is specified without
+ <literal>host</>, the value for <literal>hostaddr</> gives the remote
+ address. When Kerberos is used, a reverse name query occurs to obtain
+ the host name for Kerberos. If both
+ <literal>host</> and <literal>hostaddr</> are specified, the value for
+ <literal>hostaddr</> gives the remote address; the value for
+ <literal>host</> is ignored, unless Kerberos is used, in which case that
+ value is used for Kerberos authentication. (Note that authentication is
+ likely to fail if <application>libpq</application> is passed a host name
+ that is not the name of the machine at <literal>hostaddr</>.) Also,
+ <literal>host</> rather than <literal>hostaddr</> is used to identify
+ the connection in <filename>~/.pgpass</> (see
+ <xref linkend="libpq-pgpass">).
+ </para>
+
+ <para>
+ Without either a host name or host address,
+ <application>libpq</application> will connect using a
+ local Unix-domain socket; or on machines without Unix-domain
+ sockets, it will attempt to connect to <literal>localhost</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>port</literal></term>
+ <listitem>
+ <para>
+ Port number to connect to at the server host, or socket file
+ name extension for Unix-domain
+ connections.<indexterm><primary>port</></>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>dbname</literal></term>
+ <listitem>
+ <para>
+ The database name. Defaults to be the same as the user name.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>user</literal></term>
+ <listitem>
+ <para>
+ <productname>PostgreSQL</productname> user name to connect as.
+ Defaults to be the same as the operating system name of the user
+ running the application.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>password</literal></term>
+ <listitem>
+ <para>
+ Password to be used if the server demands password authentication.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>connect_timeout</literal></term>
+ <listitem>
+ <para>
+ Maximum wait for connection, in seconds (write as a decimal integer
+ string). Zero or not specified means wait indefinitely. It is not
+ recommended to use a timeout of less than 2 seconds.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>options</literal></term>
+ <listitem>
+ <para>
+ Command-line options to be sent to the server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>tty</literal></term>
+ <listitem>
+ <para>
+ Ignored (formerly, this specified where to send server debug output).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>sslmode</literal></term>
+ <listitem>
+ <para>
+ This option determines whether or with what priority an
+ <acronym>SSL</> connection will be negotiated with the
+ server. There are four modes: <literal>disable</> will attempt
+ only an unencrypted <acronym>SSL</> connection;
+ <literal>allow</> will negotiate, trying first a
+ non-<acronym>SSL</> connection, then if that fails, trying an
+ <acronym>SSL</> connection; <literal>prefer</> (the default)
+ will negotiate, trying first an <acronym>SSL</> connection,
+ then if that fails, trying a regular non-<acronym>SSL</>
+ connection; <literal>require</> will try only an
+ <acronym>SSL</> connection.
+ </para>
+
+ <para>
+ If <productname>PostgreSQL</> is compiled without SSL support,
+ using option <literal>require</> will cause an error, while
+ options <literal>allow</> and <literal>prefer</> will be
+ accepted but <application>libpq</> will not in fact attempt
+ an <acronym>SSL</>
+ connection.<indexterm><primary>SSL</><secondary
+ sortas="libpq">with libpq</></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>requiressl</literal></term>
+ <listitem>
+ <para>
+ This option is deprecated in favor of the <literal>sslmode</>
+ setting.
+ </para>
+
+ <para>
+ If set to 1, an <acronym>SSL</acronym> connection to the server
+ is required (this is equivalent to <literal>sslmode</>
+ <literal>require</>). <application>libpq</> will then refuse
+ to connect if the server does not accept an
+ <acronym>SSL</acronym> connection. If set to 0 (default),
+ <application>libpq</> will negotiate the connection type with
+ the server (equivalent to <literal>sslmode</>
+ <literal>prefer</>). This option is only available if
+ <productname>PostgreSQL</> is compiled with SSL support.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>krbsrvname</literal></term>
+ <listitem>
+ <para>
+ Kerberos service name to use when authenticating with Kerberos 5
+ or GSSAPI.
+ This must match the service name specified in the server
+ configuration for Kerberos authentication to succeed. (See also
+ <xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>gsslib</literal></term>
+ <listitem>
+ <para>
+ GSS library to use for GSSAPI authentication. Only used on Windows.
+ Set to <literal>gssapi</literal> to force libpq to use the GSSAPI
+ library for authentication instead of the default SSPI.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>service</literal></term>
+ <listitem>
+ <para>
+ Service name to use for additional parameters. It specifies a service
+ name in <filename>pg_service.conf</filename> that holds additional connection parameters.
+ This allows applications to specify only a service name so connection parameters
+ can be centrally maintained. See <xref linkend="libpq-pgservice">.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ If any parameter is unspecified, then the corresponding
+ environment variable (see <xref linkend="libpq-envars">)
+ is checked. If the environment variable is not set either,
+ then the indicated built-in defaults are used.
+ </para>
+ </listitem>
+ </varlistentry>
- <variablelist>
<varlistentry>
- <term><literal>host</literal></term>
+ <term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></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 is to connect to a Unix-domain socket in
- <filename>/tmp</filename>.<indexterm><primary>Unix domain
- socket</></>
- </para>
+ <para>
+ Makes a new connection to the database server.
+<synopsis>
+PGconn *PQsetdbLogin(const char *pghost,
+ const char *pgport,
+ const char *pgoptions,
+ const char *pgtty,
+ const char *dbName,
+ const char *login,
+ const char *pwd);
+</synopsis>
+ </para>
+
+ <para>
+ 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>
<varlistentry>
- <term><literal>hostaddr</literal></term>
+ <term><function>PQsetdb</function><indexterm><primary>PQsetdb</></></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 may 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>$HOME/.pgpass</> (or
- <filename>%USERPROFILE%\.pgpass</> on Win32).
+ <para>
+ Makes a new connection to the database server.
+<synopsis>
+PGconn *PQsetdb(char *pghost,
+ char *pgport,
+ char *pgoptions,
+ char *pgtty,
+ char *dbName);
+</synopsis>
</para>
+
<para>
- Without either a host name or host address,
- <application>libpq</application> will connect using a
- local Unix domain socket.
+ This is a macro that calls <function>PQsetdbLogin</function> with null pointers
+ for the <parameter>login</> and <parameter>pwd</> parameters. It is provided
+ for backward compatibility with very old programs.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>port</literal></term>
+ <term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</></></term>
+ <term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</></></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>
+ <para>
+ <indexterm><primary>nonblocking connection</primary></indexterm>
+ Make a connection to the database server in a nonblocking manner.
+
+ <synopsis>
+ PGconn *PQconnectStart(const char *conninfo);
+ </synopsis>
+
+ <synopsis>
+ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
+ </synopsis>
+ </para>
+
+ <para>
+ These two functions are used to open a connection to a database server such
+ that your application's thread of execution is not blocked on remote I/O
+ whilst doing so.
+ The point of this approach is that the waits for I/O to complete can occur
+ in the application's main loop, rather than down inside
+ <function>PQconnectdb</>, and so the application can manage this
+ operation in parallel with other activities.
+ </para>
+
+ <para>
+ The database connection is made using the parameters taken from the string
+ <literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
+ the same format as described above for <function>PQconnectdb</function>.
+ </para>
+ <para>
+ Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
+ restrictions are met:
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
+ name and reverse name queries are not made. See the documentation of
+ these parameters under <function>PQconnectdb</function> above for details.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you call <function>PQtrace</function>, ensure that the stream object
+ into which you trace will not block.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You ensure that the socket is in the appropriate state
+ before calling <function>PQconnectPoll</function>, as described below.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
+ If <varname>conn</varname> is null, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
+ structure. Otherwise, a valid <structname>PGconn</> pointer is returned (though not yet
+ representing a valid connection to the database). On return from
+ <function>PQconnectStart</function>, call <literal>status = PQstatus(conn)</literal>. If <varname>status</varname> equals
+ <symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
+ </para>
+
+ <para>
+ If <function>PQconnectStart</> succeeds, the next stage is to poll
+ <application>libpq</> so that it can proceed with the connection sequence.
+ Use <function>PQsocket(conn)</function> to obtain the descriptor of the
+ socket underlying the database connection.
+ Loop thus: If <function>PQconnectPoll(conn)</function> last returned
+ <symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to
+ read (as indicated by <function>select()</>, <function>poll()</>, or
+ similar system function).
+ Then call <function>PQconnectPoll(conn)</function> again.
+ Conversely, if <function>PQconnectPoll(conn)</function> last returned
+ <symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready
+ to write, then call <function>PQconnectPoll(conn)</function> again.
+ If you have yet to call
+ <function>PQconnectPoll</function>, i.e., just after the call to
+ <function>PQconnectStart</function>, behave as if it last returned
+ <symbol>PGRES_POLLING_WRITING</symbol>. Continue this loop until
+ <function>PQconnectPoll(conn)</function> returns
+ <symbol>PGRES_POLLING_FAILED</symbol>, indicating the connection procedure
+ has failed, or <symbol>PGRES_POLLING_OK</symbol>, indicating the connection
+ has been successfully made.
+ </para>
+
+ <para>
+ At any time during connection, the status of the connection can be
+ checked by calling <function>PQstatus</>. If this gives <symbol>CONNECTION_BAD</>, then the
+ connection procedure has failed; if it gives <function>CONNECTION_OK</>, then the
+ connection is ready. Both of these states are equally detectable
+ from the return value of <function>PQconnectPoll</>, described above. Other states might also occur
+ during (and only during) an asynchronous connection procedure. These
+ indicate the current stage of the connection procedure and might be useful
+ to provide feedback to the user for example. These statuses are:
+
+ <variablelist>
+ <varlistentry>
+ <term><symbol>CONNECTION_STARTED</symbol></term>
+ <listitem>
+ <para>
+ Waiting for connection to be made.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_MADE</symbol></term>
+ <listitem>
+ <para>
+ Connection OK; waiting to send.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
+ <listitem>
+ <para>
+ Waiting for a response from the server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_AUTH_OK</symbol></term>
+ <listitem>
+ <para>
+ Received authentication; waiting for backend start-up to finish.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
+ <listitem>
+ <para>
+ Negotiating SSL encryption.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><symbol>CONNECTION_SETENV</symbol></term>
+ <listitem>
+ <para>
+ Negotiating environment-driven parameter settings.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ Note that, although these constants will remain (in order to maintain
+ compatibility), an application should never rely upon these occurring in a
+ particular order, or at all, or on the status always being one of these
+ documented values. An application might do something like this:
+<programlisting>
+switch(PQstatus(conn))
+{
+ case CONNECTION_STARTED:
+ feedback = "Connecting...";
+ break;
+
+ case CONNECTION_MADE:
+ feedback = "Connected to server...";
+ break;
+.
+.
+.
+ default:
+ feedback = "Connecting...";
+}
+</programlisting>
+ </para>
+
+ <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>
<varlistentry>
- <term><literal>dbname</literal></term>
+ <term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></term>
<listitem>
- <para>
- The database name. Defaults to be the same as the user name.
- </para>
+ <para>
+ Returns the default connection options.
+<synopsis>
+PQconninfoOption *PQconndefaults(void);
+
+typedef struct
+{
+ char *keyword; /* The keyword of the option */
+ char *envvar; /* Fallback environment variable name */
+ char *compiled; /* Fallback compiled in default value */
+ char *val; /* Option's current value, or NULL */
+ char *label; /* Label for field in connect dialog */
+ char *dispchar; /* Character to display for this field
+ in a connect dialog. Values are:
+ "" Display entered value as is
+ "*" Password field - hide value
+ "D" Debug option - don't show by default */
+ int dispsize; /* Field size in characters for dialog */
+} PQconninfoOption;
+</synopsis>
+ </para>
+
+ <para>
+ Returns a connection options array. This can be used to determine
+ all possible <function>PQconnectdb</function> options and their
+ current default values. The return value points to an array of
+ <structname>PQconninfoOption</structname> structures, which ends
+ with an entry having a null <structfield>keyword</> pointer. The
+ null pointer is returned if memory could not be allocated. Note that
+ the current default values (<structfield>val</structfield> fields)
+ will depend on environment variables and other context. Callers
+ must treat the connection options data as read-only.
+ </para>
+
+ <para>
+ After processing the options array, free it by passing it to
+ <function>PQconninfoFree</function>. If this is not done, a small amount of memory
+ is leaked for each call to <function>PQconndefaults</function>.
+ </para>
+
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>user</literal></term>
+ <term><function>PQfinish</function><indexterm><primary>PQfinish</></></term>
<listitem>
- <para>
- <productname>PostgreSQL</productname> user name to connect as.
- </para>
+ <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><literal>password</literal></term>
+ <term><function>PQreset</function><indexterm><primary>PQreset</></></term>
<listitem>
- <para>
- Password to be used if the server demands password authentication.
- </para>
+ <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><literal>connect_timeout</literal></term>
+ <term><function>PQresetStart</function><indexterm><primary>PQresetStart</></></term>
+ <term><function>PQresetPoll</function><indexterm><primary>PQresetPoll</></></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>
+ <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>
+ </variablelist>
+ </para>
+ </sect1>
+
+ <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><literal>options</literal></term>
+ <term>
+ <function>PQdb</function>
+ <indexterm>
+ <primary>PQdb</primary>
+ </indexterm>
+ </term>
+
<listitem>
<para>
- Command-line options to be sent to the server.
+ Returns the database name of the connection.
+ <synopsis>
+ char *PQdb(const PGconn *conn);
+ </synopsis>
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>tty</literal></term>
+ <term>
+ <function>PQuser</function>
+ <indexterm>
+ <primary>PQuser</primary>
+ </indexterm>
+ </term>
+
<listitem>
- <para>
- Ignored (formerly, this specified where to send server debug output).
- </para>
+ <para>
+ Returns the user name of the connection.
+ <synopsis>
+ char *PQuser(const PGconn *conn);
+ </synopsis>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>sslmode</literal></term>
+ <term>
+ <function>PQpass</function>
+ <indexterm>
+ <primary>PQpass</primary>
+ </indexterm>
+ </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.
+ 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>
- 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
- tolerated but <application>libpq</> will be unable to negotiate
- an <acronym>SSL</>
- connection.<indexterm><primary>SSL</><secondary
- sortas="libpq">with libpq</></indexterm>
+ Returns the server host name of the connection.
+ <synopsis>
+ char *PQhost(const PGconn *conn);
+ </synopsis>
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>requiressl</literal></term>
+ <term>
+ <function>PQport</function>
+ <indexterm>
+ <primary>PQport</primary>
+ </indexterm>
+ </term>
+
<listitem>
<para>
- This option is deprecated in favor of the <literal>sslmode</>
- setting.
+ 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>
- 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.
+ 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><literal>service</literal></term>
+ <term>
+ <function>PQoptions</function>
+ <indexterm>
+ <primary>PQoptions</primary>
+ </indexterm>
+ </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
- <filename><replaceable>PREFIX</>/share/pg_service.conf.sample</> for
- information on how to set up the file.
- </para>
+ <para>
+ Returns the command-line options passed in the connection request.
+ <synopsis>
+ char *PQoptions(const PGconn *conn);
+ </synopsis>
+ </para>
</listitem>
</varlistentry>
</variablelist>
+ </para>
- 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 built-in defaults are used.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ The following functions return status data that can change as operations
+ are executed on the <structname>PGconn</> object.
- <varlistentry>
- <term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></term>
- <listitem>
- <para>
- Makes a new connection to the database server.
-<synopsis>
-PGconn *PQsetdbLogin(const char *pghost,
- const char *pgport,
- const char *pgoptions,
- const char *pgtty,
- const char *dbName,
- const char *login,
- const char *pwd);
-</synopsis>
-</para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQstatus</function>
+ <indexterm>
+ <primary>PQstatus</primary>
+ </indexterm>
+ </term>
-<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>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ Returns the status of the connection.
+ <synopsis>
+ ConnStatusType PQstatus(const PGconn *conn);
+ </synopsis>
+ </para>
- <varlistentry>
- <term><function>PQsetdb</function><indexterm><primary>PQsetdb</></></term>
- <listitem>
- <para>
- Makes a new connection to the database server.
-<synopsis>
-PGconn *PQsetdb(char *pghost,
- char *pgport,
- char *pgoptions,
- char *pgtty,
- char *dbName);
-</synopsis>
-</para>
+ <para>
+ The status can be one of a number of values. However, only two of
+ these are seen outside of an asynchronous connection procedure:
+ <literal>CONNECTION_OK</literal> and
+ <literal>CONNECTION_BAD</literal>. A good connection to the database
+ has the status <literal>CONNECTION_OK</literal>. A failed
+ connection attempt is signaled by status
+ <literal>CONNECTION_BAD</literal>. Ordinarily, an OK status will
+ remain so until <function>PQfinish</function>, but a communications
+ failure might result in the status changing to
+ <literal>CONNECTION_BAD</literal> prematurely. In that case the
+ application could try to recover by calling
+ <function>PQreset</function>.
+ </para>
-<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>
+ See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
+ to other status codes
+ that might be seen.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term><function>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>
+ <varlistentry>
+ <term>
+ <function>PQtransactionStatus</function>
+ <indexterm>
+ <primary>PQtransactionStatus</primary>
+ </indexterm>
+ </term>
- <listitem>
- <para>
- If you call <function>PQtrace</function>, ensure that the stream object
- into which you trace will not block.
- </para>
- </listitem>
+ <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>
- <listitem>
- <para>
- You ensure that the socket is in the appropriate state
- before calling <function>PQconnectPoll</function>, as described below.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
- If <varname>conn</varname> is null, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
- structure. Otherwise, a valid <structname>PGconn</> pointer is returned (though not yet
- representing a valid connection to the database). On return from
- <function>PQconnectStart</function>, call <literal>status = PQstatus(conn)</literal>. If <varname>status</varname> equals
- <symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
- </para>
- <para>
- If <function>PQconnectStart</> succeeds, the next stage is to poll
- <application>libpq</> so that it may 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 may 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 may also occur
- during (and only during) an asynchronous connection procedure. These
- indicate the current stage of the connection procedure and may 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>
+ <caution>
<para>
- Negotiating environment-driven parameter settings.
+ <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>
- </listitem>
- </varlistentry>
- </variablelist>
-
- Note that, although these constants will remain (in order to maintain
- compatibility), an application should never rely upon these appearing in a
- particular order, or at all, or on the status always being one of these
- documented values. An application might do something like this:
-<programlisting>
-switch(PQstatus(conn))
-{
- case CONNECTION_STARTED:
- feedback = "Connecting...";
- break;
-
- case CONNECTION_MADE:
- feedback = "Connected to server...";
- break;
-.
-.
-.
- default:
- feedback = "Connecting...";
-}
-</programlisting>
- </para>
-
- <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>
-
- <varlistentry>
- <term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></term>
- <listitem>
- <para>
- Returns the default connection options.
-<synopsis>
-PQconninfoOption *PQconndefaults(void);
-
-typedef struct
-{
- char *keyword; /* The keyword of the option */
- char *envvar; /* Fallback environment variable name */
- char *compiled; /* Fallback compiled in default value */
- char *val; /* Option's current value, or NULL */
- char *label; /* Label for field in connect dialog */
- char *dispchar; /* Character to display for this field
- in a connect dialog. Values are:
- "" Display entered value as is
- "*" Password field - hide value
- "D" Debug option - don't show by default */
- int dispsize; /* Field size in characters for dialog */
-} PQconninfoOption;
-</synopsis>
-</para>
-
-<para>
- Returns a connection options array. This may
- 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. Note that the current default values
- (<structfield>val</structfield> fields)
- will depend on environment variables and other context.
- Callers must treat the connection options data as read-only.
- </para>
-
- <para>
- After processing the options array, free it by passing it to
- <function>PQconninfoFree</function>. If this is not done, a small amount of memory
- is leaked for each call to <function>PQconndefaults</function>.
- </para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><function>PQfinish</function><indexterm><primary>PQfinish</></></term>
- <listitem>
- <para>
- Closes the connection to the server. Also frees
- memory used by the <structname>PGconn</structname> object.
-<synopsis>
-void PQfinish(PGconn *conn);
-</synopsis>
-</para>
-
-<para>
- Note that even if the server connection attempt fails (as
- indicated by <function>PQstatus</function>), the application should call <function>PQfinish</function>
- to free the memory used by the <structname>PGconn</structname> object.
- The <structname>PGconn</> pointer must not be used again after
- <function>PQfinish</function> has been called.
- </para>
- </listitem>
- </varlistentry>
+ </caution>
+ </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 may be useful for
- error recovery if a working connection is lost.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>
+ <function>PQparameterStatus</function>
+ <indexterm>
+ <primary>PQparameterStatus</primary>
+ </indexterm>
+ </term>
- <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 may 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>
+ <listitem>
+ <para>
+ Looks up a current parameter setting of the server.
- </variablelist>
-</para>
-</sect1>
+ <synopsis>
+ const char *PQparameterStatus(const PGconn *conn, const char *paramName);
+ </synopsis>
-<sect1 id="libpq-status">
-<title>Connection Status Functions</title>
+ 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>
- These functions may be used to interrogate the status
- of an existing database connection object.
- </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>
-<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>. Avoid directly referencing the fields of the
-<structname>PGconn</> structure because they are subject to change in the future.
-(Beginning in <productname>PostgreSQL</productname> release 6.4, the
-definition of the <type>struct</type> behind <structname>PGconn</> is not even provided in <filename>libpq-fe.h</filename>.
-If you have old code that accesses <structname>PGconn</structname> fields directly, you can keep using it
-by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code
-soon.)
-</para>
-</tip>
-
-<para>
-The following functions return parameter values established at connection.
-These values are fixed for the life of the <structname>PGconn</> object.
-
-<variablelist>
-<varlistentry>
-<term><function>PQdb</function><indexterm><primary>PQdb</></></term>
-<listitem>
-<para>
- Returns the database name of the connection.
-<synopsis>
-char *PQdb(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQuser</function><indexterm><primary>PQuser</></></term>
-<listitem>
-<para>
- Returns the user name of the connection.
-<synopsis>
-char *PQuser(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQpass</function><indexterm><primary>PQpass</></></term>
-<listitem>
-<para>
- Returns the password of the connection.
-<synopsis>
-char *PQpass(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQhost</function><indexterm><primary>PQhost</></></term>
-<listitem>
-<para>
- Returns the server host name of the connection.
-<synopsis>
-char *PQhost(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQport</function><indexterm><primary>PQport</></></term>
-<listitem>
-<para>
- Returns the port of the connection.
-<synopsis>
-char *PQport(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQtty</function><indexterm><primary>PQtty</></></term>
-<listitem>
-<para>
- Returns the debug <acronym>TTY</acronym> of the connection.
- (This is obsolete, since the server no longer pays attention
- to the <acronym>TTY</acronym> setting, but the function remains
- for backwards compatibility.)
-<synopsis>
-char *PQtty(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQoptions</function><indexterm><primary>PQoptions</></></term>
-<listitem>
-<para>
- Returns the command-line options passed in the connection request.
-<synopsis>
-char *PQoptions(const PGconn *conn);
-</synopsis>
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-The following functions return status data that can change as operations
-are executed on the <structname>PGconn</> object.
-
-<variablelist>
-<varlistentry>
-<term><function>PQstatus</function><indexterm><primary>PQstatus</></></term>
-<listitem>
-<para>
- Returns the status of the connection.
-<synopsis>
-ConnStatusType PQstatus(const PGconn *conn);
-</synopsis>
-</para>
+ <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>
- 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>.
+ 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>
- See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
- to other status codes
- that might be seen.
+ Although the returned pointer is declared <literal>const</>, it in fact
+ points to mutable storage associated with the <literal>PGconn</> structure.
+ It is unwise to assume the pointer will remain valid across queries.
</para>
</listitem>
</varlistentry>
-<varlistentry>
-<term><function>PQtransactionStatus</function><indexterm><primary>PQtransactionStatus</></></term>
-<listitem>
-<para>
- Returns the current in-transaction status of the server.
-<synopsis>
-PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
-</synopsis>
+ <varlistentry>
+ <term>
+ <function>PQprotocolVersion</function>
+ <indexterm>
+ <primary>PQprotocolVersion</primary>
+ </indexterm>
+ </term>
-The status can be <literal>PQTRANS_IDLE</literal> (currently idle),
-<literal>PQTRANS_ACTIVE</literal> (a command is in progress),
-<literal>PQTRANS_INTRANS</literal> (idle, in a valid transaction block),
-or <literal>PQTRANS_INERROR</literal> (idle, in a failed transaction block).
-<literal>PQTRANS_UNKNOWN</literal> is reported if the connection is bad.
-<literal>PQTRANS_ACTIVE</literal> is reported only when a query
-has been sent to the server and not yet completed.
-</para>
-<caution>
-<para>
-<function>PQtransactionStatus</> will give incorrect results when using
-a <productname>PostgreSQL</> 7.3 server that has the parameter <literal>autocommit</>
-set to off. The server-side autocommit feature has been
-deprecated and does not exist in later server versions.
-</para>
-</caution>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQparameterStatus</function><indexterm><primary>PQparameterStatus</></></term>
-<listitem>
-<para>
- Looks up a current parameter setting of the server.
-<synopsis>
-const char *PQparameterStatus(const PGconn *conn, const char *paramName);
-</synopsis>
+ <listitem>
+ <para>
+ Interrogates the frontend/backend protocol being used.
+ <synopsis>
+ int PQprotocolVersion(const PGconn *conn);
+ </synopsis>
+ Applications might wish to use this to determine whether certain
+ features are supported. Currently, the possible values are 2 (2.0
+ protocol), 3 (3.0 protocol), or zero (connection bad). This will
+ not change after connection startup is complete, but it could
+ theoretically change during a connection reset. The 3.0 protocol
+ will normally be used when communicating with
+ <productname>PostgreSQL</> 7.4 or later servers; pre-7.4 servers
+ support only protocol 2.0. (Protocol 1.0 is obsolete and not
+ supported by <application>libpq</application>.)
+ </para>
+ </listitem>
+ </varlistentry>
-Certain parameter values are reported by the server automatically at
-connection startup or whenever their values change.
-<function>PQparameterStatus</> can be used to interrogate these settings.
-It returns the current value of a parameter if known, or <symbol>NULL</symbol>
-if the parameter is not known.
-</para>
-
-<para>
-Parameters reported as of the current release include
-<literal>server_version</>,
-<literal>server_encoding</>,
-<literal>client_encoding</>,
-<literal>is_superuser</>,
-<literal>session_authorization</>,
-<literal>DateStyle</>, and
-<literal>integer_datetimes</>.
-(<literal>server_encoding</> and <literal>integer_datetimes</> were not
-reported by releases before 8.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 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>
-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 may 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 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 may 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 7.4.2 will be returned as 70402, and version
-8.1 will be returned as 80100 (leading zeroes are not shown). Zero is
-returned if the connection is bad.
-</para>
-</listitem>
-</varlistentry>
+ <varlistentry>
+ <term>
+ <function>PQserverVersion</function>
+ <indexterm>
+ <primary>PQserverVersion</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns an integer representing the backend version.
+ <synopsis>
+ int PQserverVersion(const PGconn *conn);
+ </synopsis>
+ Applications might use this to determine the version of the database
+ server they are connected to. The number is formed by converting
+ the major, minor, and revision numbers into two-decimal-digit
+ numbers and appending them together. For example, version 8.1.5
+ will be returned as 80105, and version 8.2 will be returned as
+ 80200 (leading zeroes are not shown). Zero is returned if the
+ connection is bad.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
- <term><function>PQerrorMessage</function><indexterm><primary>PQerrorMessage</></></term>
+ <term>
+ <function>PQerrorMessage</function>
+ <indexterm>
+ <primary>PQerrorMessage</primary>
+ </indexterm>
+ </term>
+
<listitem>
<para>
- <indexterm><primary>error message</></>
- Returns the error message most recently generated by
- an operation on the connection.
-<synopsis>
-char *PQerrorMessage(const PGconn *conn);
-</synopsis>
+ <indexterm><primary>error message</></> Returns the error message
+ most recently generated by an operation on the connection.
+
+ <synopsis>
+ char *PQerrorMessage(const PGconn *conn);
+ </synopsis>
+
</para>
<para>
Nearly all <application>libpq</> functions will set a message for
- <function>PQerrorMessage</function> if they fail.
- Note that by <application>libpq</application> convention, a nonempty
- <function>PQerrorMessage</function> result will
- include a trailing newline. The caller should not free the result
- directly. It will be freed when the associated <structname>PGconn</>
- handle is passed to <function>PQfinish</function>.
+ <function>PQerrorMessage</function> if they fail. Note that by
+ <application>libpq</application> convention, a nonempty
+ <function>PQerrorMessage</function> result will include a trailing
+ newline. The caller should not free the result directly. It will
+ be freed when the associated <structname>PGconn</> handle is passed
+ to <function>PQfinish</function>. The result string should not be
+ expected to remain the same across operations on the
+ <literal>PGconn</> structure.
</para>
</listitem>
</varlistentry>
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
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><function>PQconnectionNeedsPassword</function><indexterm><primary>PQconnectionNeedsPassword</></></term>
+ <listitem>
+ <para>
+ Returns true (1) if the connection authentication method
+ required a password, but none was available.
+ Returns false (0) if not.
+
+ <synopsis>
+ int PQconnectionNeedsPassword(const PGconn *conn);
+ </synopsis>
+
+ </para>
+
+ <para>
+ This function can be applied after a failed connection attempt
+ to decide whether to prompt the user for a password.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><function>PQconnectionUsedPassword</function><indexterm><primary>PQconnectionUsedPassword</></></term>
+ <listitem>
+ <para>
+ Returns true (1) if the connection authentication method
+ used a caller-supplied password. Returns false (0) if not.
+
+ <synopsis>
+ int PQconnectionUsedPassword(const PGconn *conn);
+ </synopsis>
+
+ </para>
+
+ <para>
+ This function detects whether a password supplied to the connection
+ function was actually used. Passwords obtained from other
+ sources (such as the <filename>.pgpass</> file) are not considered
+ caller-supplied.
+ </para>
+ </listitem>
+ </varlistentry>
+
<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.
-<synopsis>
-SSL *PQgetssl(const PGconn *conn);
-</synopsis>
-</para>
+ if SSL is not in use.
+
+ <synopsis>
+ SSL *PQgetssl(const PGconn *conn);
+ </synopsis>
+ </para>
-<para>
- This structure can be used to verify encryption levels, check
- server certificates, and more. Refer to the <productname>OpenSSL</> documentation
- for information about this structure.
+ This structure can be used to verify encryption levels, check server
+ certificates, and more. Refer to the <productname>OpenSSL</>
+ documentation for information about this structure.
</para>
+
<para>
You must define <symbol>USE_SSL</symbol> in order to get the
- prototype for this function. Doing this will also
+ correct prototype for this function. Doing this will also
automatically include <filename>ssl.h</filename> from <productname>OpenSSL</productname>.
</para>
</listitem>
</varlistentry>
-</variablelist>
-</para>
+ </variablelist>
+ </para>
+
+ </sect1>
-</sect1>
+ <sect1 id="libpq-exec">
+ <title>Command Execution Functions</title>
-<sect1 id="libpq-exec">
-<title>Command Execution Functions</title>
+ <para>
+ Once a connection to a database server has been successfully
+ established, the functions described here are used to perform
+ SQL queries and commands.
+ </para>
-<para>
-Once a connection to a database server has been successfully
-established, the functions described here are used to perform
-SQL queries and commands.
-</para>
+ <sect2 id="libpq-exec-main">
+ <title>Main Functions</title>
-<sect2 id="libpq-exec-main">
- <title>Main Functions</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQexec</function>
+ <indexterm>
+ <primary>PQexec</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Submits a command to the server and waits for the result.
+
+ <synopsis>
+ PGresult *PQexec(PGconn *conn, const char *command);
+ </synopsis>
+ </para>
+
+ <para>
+ Returns a <structname>PGresult</structname> pointer or possibly a null
+ pointer. A non-null pointer will generally be returned except in
+ out-of-memory conditions or serious errors such as inability to send
+ the command to the server. If a null pointer is returned, it should
+ be treated like a <symbol>PGRES_FATAL_ERROR</symbol> result. Use
+ <function>PQerrorMessage</function> to get more information about such
+ errors.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ It is allowed to include multiple SQL commands (separated by semicolons)
+ in the command string. Multiple queries sent in a single
+ <function>PQexec</> call are processed in a single transaction, unless
+ there are explicit <command>BEGIN</command>/<command>COMMIT</command>
+ commands included in the query string to divide it into multiple
+ transactions. Note however that the returned
+ <structname>PGresult</structname> structure describes only the result
+ of the last command executed from the string. Should one of the
+ commands fail, processing of the string stops with it and the returned
+ <structname>PGresult</structname> describes the error condition.
+ </para>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQexecParams</function>
+ <indexterm>
+ <primary>PQexecParams</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Submits a command to the server and waits for the result,
+ with the ability to pass parameters separately from the SQL
+ command text.
-<para>
-<variablelist>
-<varlistentry>
-<term><function>PQexec</function><indexterm><primary>PQexec</></></term>
-<listitem>
-<para>
- Submits a command to the server
- and waits for the result.
-<synopsis>
-PGresult *PQexec(PGconn *conn, const char *command);
-</synopsis>
-</para>
-
-<para>
- Returns a <structname>PGresult</structname> pointer or possibly a null pointer.
- A non-null pointer will generally be returned except in
- out-of-memory conditions or serious errors such as inability
- to send the command to the server.
- If a null pointer is returned, it
- should be treated like a <symbol>PGRES_FATAL_ERROR</symbol> result.
- Use <function>PQerrorMessage</function> to get more information
- about such errors.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-It is allowed to include multiple SQL commands (separated by semicolons) in
-the command string. Multiple queries sent in a single <function>PQexec</>
-call are processed in a single transaction, unless there are explicit
-<command>BEGIN</command>/<command>COMMIT</command> commands included in the query string to divide it into multiple
-transactions. Note however that the returned <structname>PGresult</structname>
-structure describes only the result of the last command executed from the
-string. Should one of the commands fail, processing of the string stops with
-it and the returned <structname>PGresult</structname> describes the error
-condition.
-</para>
-
-<para>
-<variablelist>
-<varlistentry>
-<term><function>PQexecParams</function><indexterm><primary>PQexecParams</></></term>
-<listitem>
-<para>
- Submits a command to the server and waits for the result,
- with the ability to pass parameters separately from the SQL
- command text.
<synopsis>
PGresult *PQexecParams(PGconn *conn,
const char *command,
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>
-If parameters are used, they are referred to in the command string
-as <literal>$1</>, <literal>$2</>, etc.
-<parameter>nParams</> is the number of parameters supplied; it is the length
-of the arrays <parameter>paramTypes[]</>, <parameter>paramValues[]</>,
-<parameter>paramLengths[]</>, and <parameter>paramFormats[]</>. (The
-array pointers may 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.
-<parameter>paramValues[]</> 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).
-<parameter>paramLengths[]</> specifies the actual data lengths of
-binary-format parameters. It is ignored for null parameters and text-format
-parameters. The array pointer may be null when there are no binary
-parameters.
-<parameter>paramFormats[]</> specifies whether parameters are text (put a zero
-in the array) or binary (put a one in the array). If the array pointer is
-null then all parameters are presumed to be text.
-<parameter>resultFormat</> is 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>
-
-The primary advantage of <function>PQexecParams</> over <function>PQexec</>
-is that parameter values may be separated from the command string, thus
-avoiding the need for tedious and error-prone quoting and escaping.
-
-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>
-
-<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.
-<synopsis>
-PGresult *PQprepare(PGconn *conn,
- const char *stmtName,
- const char *query,
- 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</> may 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
-may 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 may use parameter symbols with numbers higher than
-<parameter>nParams</>; data types will be inferred for these symbols as
-well.
-</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>
-
-<para>
-At present, there is no way to determine the actual datatype inferred for
-any parameters whose types are not specified in <parameter>paramTypes[]</>.
-This is a <application>libpq</> omission that will probably be rectified
-in a future release.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-Prepared statements for use with <function>PQexecPrepared</> can also be
-created by executing SQL <command>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 <command>DEALLOCATE</> 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.
-<synopsis>
-PGresult *PQexecPrepared(PGconn *conn,
- const char *stmtName,
- int nParams,
- const char * const *paramValues,
- const int *paramLengths,
- 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.
-<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>
-</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> may 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. May 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. May 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. 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>). For objects with other status
-values they 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.
+ </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>
+ </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;
+</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</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Submits a request to create a prepared statement with the
+ given parameters, and waits for completion.
<synopsis>
-int PQntuples(const PGresult *res);
+PGresult *PQprepare(PGconn *conn,
+ const char *stmtName,
+ const char *query,
+ int nParams,
+ const Oid *paramTypes);
</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.
+ </para>
+
+ <para>
+ <function>PQprepare</> creates a prepared statement for later
+ execution with <function>PQexecPrepared</>. This feature allows
+ commands that will be used repeatedly to be parsed and planned just
+ once, rather than each time they are executed.
+ <function>PQprepare</> is supported only in protocol 3.0 and later
+ connections; it will fail when using protocol 2.0.
+ </para>
+
+ <para>
+ The function creates a prepared statement named
+ <parameter>stmtName</> from the <parameter>query</> string, which
+ must contain a single SQL command. <parameter>stmtName</> can be
+ <literal>""</> to create an unnamed statement, in which case any
+ pre-existing unnamed statement is automatically replaced; otherwise
+ it is an error if the statement name is already defined in the
+ current session. If any parameters are used, they are referred
+ to in the query as <literal>$1</>, <literal>$2</>, etc.
+ <parameter>nParams</> is the number of parameters for which types
+ are pre-specified in the array <parameter>paramTypes[]</>. (The
+ array pointer can be <symbol>NULL</symbol> when
+ <parameter>nParams</> is zero.) <parameter>paramTypes[]</>
+ specifies, by OID, the data types to be assigned to the parameter
+ symbols. If <parameter>paramTypes</> is <symbol>NULL</symbol>,
+ or any particular element in the array is zero, the server assigns
+ a data type to the parameter symbol in the same way it would do
+ for an untyped literal string. Also, the query can use parameter
+ symbols with numbers higher than <parameter>nParams</>; data types
+ will be inferred for these symbols as well. (See
+ <function>PQdescribePrepared</function> for a means to find out
+ what data types were inferred.)
+ </para>
+
+ <para>
+ As with <function>PQexec</>, the result is normally a
+ <structname>PGresult</structname> object whose contents indicate
+ server-side success or failure. A null result indicates
+ out-of-memory or inability to send the command at all. Use
+ <function>PQerrorMessage</function> to get more information about
+ such errors.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ Prepared statements for use with <function>PQexecPrepared</> can also
+ be created by executing SQL <xref linkend="sql-prepare"
+ endterm="sql-prepare-title"> statements. (But <function>PQprepare</>
+ is more flexible since it does not require parameter types to be
+ pre-specified.) Also, although there is no <application>libpq</>
+ function for deleting a prepared statement, the SQL <xref
+ linkend="sql-deallocate" endterm="sql-deallocate-title"> statement
+ can be used for that purpose.
+ </para>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQexecPrepared</function>
+ <indexterm>
+ <primary>PQexecPrepared</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Sends a request to execute a prepared statement with given
+ parameters, and waits for the result.
<synopsis>
-int PQnfields(const PGresult *res);
+PGresult *PQexecPrepared(PGconn *conn,
+ const char *stmtName,
+ int nParams,
+ const char * const *paramValues,
+ const int *paramLengths,
+ const int *paramFormats,
+ int resultFormat);
</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>.
+ </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>
-char *PQfname(const PGresult *res,
- int column_number);
+PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
</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.
+ </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>
-int PQfnumber(const PGresult *res,
- const char *column_name);
+PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
</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>
+
+ <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>.
+ Note that <function>PQclear</function> should eventually be called
+ on the object, just as with a <structname>PGresult</structname>
+ returned by <application>libpq</application> itself.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2 id="libpq-exec-select-info">
+ <title>Retrieving Query Result Information</title>
+
+ <para>
+ These functions are used to extract information from a
+ <structname>PGresult</structname> object that represents a successful
+ query result (that is, one that has status
+ <literal>PGRES_TUPLES_OK</literal>). They can also be used to extract
+ information from a successful Describe operation: a Describe's result
+ has all the same column information that actual execution of the query
+ would provide, but it has zero rows. For objects with other status values,
+ these functions will act as though the result has zero rows and zero columns.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQntuples</function>
+ <indexterm>
+ <primary>PQntuples</primary>
+ </indexterm>
+ </term>
+
+ <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 Result Information for Other Commands</title>
+
+ <para>
+ These functions are used to extract information from
+ <structname>PGresult</structname> objects that are not
+ <command>SELECT</> results.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQcmdStatus</function>
+ <indexterm>
+ <primary>PQcmdStatus</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns the command status tag from the SQL command that generated
+ the <structname>PGresult</structname>.
+ <synopsis>
+ char *PQcmdStatus(PGresult *res);
+ </synopsis>
+ </para>
+
+ <para>
+ 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 an <command>INSERT</>, <command>UPDATE</>,
+ <command>DELETE</>, <command>MOVE</>, <command>FETCH</>, or
+ <command>COPY</> statement, or an <command>EXECUTE</> of a
+ prepared query that contains an <command>INSERT</>,
+ <command>UPDATE</>, or <command>DELETE</> statement. If the
+ command that generated the <structname>PGresult</> was anything
+ else, <function>PQcmdTuples</> returns an empty string. The caller
+ should not free the return value directly. It will be freed when
+ the associated <structname>PGresult</> handle is passed to
+ <function>PQclear</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQoidValue</function>
+ <indexterm>
+ <primary>PQoidValue</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns the OID<indexterm><primary>OID</><secondary>in libpq</></>
+ of the inserted row, if the <acronym>SQL</> command was an
+ <command>INSERT</> that inserted exactly one row into a table that
+ has OIDs, or a <command>EXECUTE</> of a prepared query containing
+ a suitable <command>INSERT</> statement. Otherwise, this function
+ returns <literal>InvalidOid</literal>. This function will also
+ return <literal>InvalidOid</literal> if the table affected by the
+ <command>INSERT</> statement does not contain OIDs.
+ <synopsis>
+ Oid PQoidValue(const PGresult *res);
+ </synopsis>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQoidStatus</function>
+ <indexterm>
+ <primary>PQoidStatus</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns a string with the OID of the inserted row, if the
+ <acronym>SQL</acronym> command was an <command>INSERT</command>
+ that inserted exactly one row, or a <command>EXECUTE</command> of
+ a prepared statement consisting of a suitable
+ <command>INSERT</command>. (The string will be <literal>0</> if
+ the <command>INSERT</command> did not insert exactly one row, or
+ if the target table does not have OIDs.) If the command was not
+ an <command>INSERT</command>, returns an empty string.
+ <synopsis>
+ char *PQoidStatus(const PGresult *res);
+ </synopsis>
+ </para>
+
+ <para>
+ This function is deprecated in favor of
+ <function>PQoidValue</function>. It is not thread-safe.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="libpq-exec-escape-string">
+ <title>Escaping Strings for Inclusion in SQL Commands</title>
+
+ <indexterm zone="libpq-exec-escape-string">
+ <primary>PQescapeStringConn</primary>
+ </indexterm>
+ <indexterm zone="libpq-exec-escape-string">
+ <primary>PQescapeString</primary>
+ </indexterm>
+ <indexterm zone="libpq-exec-escape-string">
+ <primary>escaping strings</primary>
+ <secondary>in libpq</secondary>
+ </indexterm>
+
+ <para>
+ <function>PQescapeStringConn</function> escapes a string for use within an SQL
+ command. This is useful when inserting data values as literal constants
+ in SQL commands. Certain characters (such as quotes and backslashes) must
+ be escaped to prevent them from being interpreted specially by the SQL parser.
+ <function>PQescapeStringConn</> performs this operation.
+ </para>
+
+ <tip>
+ <para>
+ It is especially important to do proper escaping when handling strings that
+ were received from an untrustworthy source. Otherwise there is a security
+ risk: you are vulnerable to <quote>SQL injection</> attacks wherein unwanted
+ SQL commands are fed to your database.
+ </para>
+ </tip>
+
+ <para>
+ Note that it is not necessary nor correct to do escaping when a data
+ value is passed as a separate parameter in <function>PQexecParams</> or
+ its sibling routines.
+
+ <synopsis>
+ size_t PQescapeStringConn (PGconn *conn,
+ char *to, const char *from, size_t length,
+ int *error);
+ </synopsis>
+ </para>
+
+ <para>
+ <function>PQescapeStringConn</> writes an escaped version of the
+ <parameter>from</> string to the <parameter>to</> buffer, escaping
+ special characters so that they cannot cause any harm, and adding a
+ terminating zero byte. The single quotes that must surround
+ <productname>PostgreSQL</> string literals are not included in the
+ result string; they should be provided in the SQL command that the
+ result is inserted into. The parameter <parameter>from</> points to
+ the first character of the string that is to be escaped, and the
+ <parameter>length</> parameter gives the number of bytes in this
+ string. A terminating zero byte is not required, and should not be
+ counted in <parameter>length</>. (If a terminating zero byte is found
+ before <parameter>length</> bytes are processed,
+ <function>PQescapeStringConn</> stops at the zero; the behavior is
+ thus rather like <function>strncpy</>.) <parameter>to</> shall point
+ to a buffer that is able to hold at least one more byte than twice
+ the value of <parameter>length</>, otherwise the behavior is undefined.
+ Behavior is likewise undefined if the <parameter>to</> and
+ <parameter>from</> strings overlap.
+ </para>
+
+ <para>
+ If the <parameter>error</> parameter is not NULL, then
+ <literal>*error</> is set to zero on success, nonzero on error.
+ Presently the only possible error conditions involve invalid multibyte
+ encoding in the source string. The output string is still generated
+ on error, but it can be expected that the server will reject it as
+ malformed. On error, a suitable message is stored in the
+ <parameter>conn</> object, whether or not <parameter>error</> is NULL.
+ </para>
+
+ <para>
+ <function>PQescapeStringConn</> returns the number of bytes written
+ to <parameter>to</>, not including the terminating zero byte.
+ </para>
+
+ <para>
+ <synopsis>
+ size_t PQescapeString (char *to, const char *from, size_t length);
+ </synopsis>
+ </para>
+
+ <para>
+ <function>PQescapeString</> is an older, deprecated version of
+ <function>PQescapeStringConn</>; the difference is that it does
+ not take <parameter>conn</> or <parameter>error</> parameters.
+ Because of this, it cannot adjust its behavior depending on the
+ connection properties (such as character encoding) and therefore
+ <emphasis>it might give the wrong results</>. Also, it has no way
+ to report error conditions.
+ </para>
+
+ <para>
+ <function>PQescapeString</> can be used safely in single-threaded
+ client programs that work with only one <productname>PostgreSQL</>
+ connection at a time (in this case it can find out what it needs to
+ know <quote>behind the scenes</>). In other contexts it is a security
+ hazard and should be avoided in favor of
+ <function>PQescapeStringConn</>.
+ </para>
+ </sect2>
+
+
+ <sect2 id="libpq-exec-escape-bytea">
+ <title>Escaping Binary Strings for Inclusion in SQL Commands</title>
+
+ <indexterm zone="libpq-exec-escape-bytea">
+ <primary>bytea</primary>
+ <secondary sortas="libpq">in libpq</secondary>
+ </indexterm>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQescapeByteaConn</function>
+ <indexterm>
+ <primary>PQescapeByteaConn</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Escapes binary data for use within an SQL command with the type
+ <type>bytea</type>. As with <function>PQescapeStringConn</function>,
+ this is only used when inserting data directly into an SQL command string.
+ <synopsis>
+ unsigned char *PQescapeByteaConn(PGconn *conn,
+ const unsigned char *from,
+ size_t from_length,
+ size_t *to_length);
+ </synopsis>
+ </para>
+
+ <para>
+ Certain byte values <emphasis>must</emphasis> be escaped (but all
+ byte values <emphasis>can</emphasis> be escaped) when used as part
+ of a <type>bytea</type> literal in an <acronym>SQL</acronym>
+ statement. In general, to escape a byte, it is converted into the
+ three digit octal number equal to the octet value, and preceded by
+ usually two backslashes. The single quote (<literal>'</>) and backslash
+ (<literal>\</>) characters have special alternative escape
+ sequences. See <xref linkend="datatype-binary"> for more
+ information. <function>PQescapeByteaConn</function> performs this
+ operation, escaping only the minimally required bytes.
+ </para>
+
+ <para>
+ The <parameter>from</parameter> parameter points to the first
+ byte of the string that is to be escaped, and the
+ <parameter>from_length</parameter> parameter gives the number of
+ bytes in this binary string. (A terminating zero byte is
+ neither necessary nor counted.) The <parameter>to_length</parameter>
+ parameter points to a variable that will hold the resultant
+ escaped string length. This result string length includes the terminating
+ zero byte of the result.
+ </para>
+
+ <para>
+ <function>PQescapeByteaConn</> returns an escaped version of the
+ <parameter>from</parameter> parameter binary string in memory
+ allocated with <function>malloc()</>. This memory must be freed using
+ <function>PQfreemem()</> when the result is no longer needed. The
+ return string has all special characters replaced so that they can
+ be properly processed by the <productname>PostgreSQL</productname>
+ string literal parser, and the <type>bytea</type> input function. A
+ terminating zero byte is also added. The single quotes that must
+ surround <productname>PostgreSQL</productname> string literals are
+ not part of the result string.
+ </para>
+
+ <para>
+ On error, a NULL pointer is returned, and a suitable error message
+ is stored in the <parameter>conn</> object. Currently, the only
+ possible error is insufficient memory for the result string.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQescapeBytea</function>
+ <indexterm>
+ <primary>PQescapeBytea</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ <function>PQescapeBytea</> is an older, deprecated version of
+ <function>PQescapeByteaConn</>.
+ <synopsis>
+ unsigned char *PQescapeBytea(const unsigned char *from,
+ size_t from_length,
+ size_t *to_length);
+ </synopsis>
+ </para>
+
+ <para>
+ The only difference from <function>PQescapeByteaConn</> is that
+ <function>PQescapeBytea</> does not take a <structname>PGconn</>
+ parameter. Because of this, it cannot adjust its behavior
+ depending on the connection properties (in particular, whether
+ standard-conforming strings are enabled) and therefore
+ <emphasis>it might give the wrong results</>. Also, it has no
+ way to return an error message on failure.
+ </para>
+
+ <para>
+ <function>PQescapeBytea</> can be used safely in single-threaded
+ client programs that work with only one <productname>PostgreSQL</>
+ connection at a time (in this case it can find out what it needs
+ to know <quote>behind the scenes</>). In other contexts it is
+ a security hazard and should be avoided in favor of
+ <function>PQescapeByteaConn</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQunescapeBytea</function>
+ <indexterm>
+ <primary>PQunescapeBytea</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Converts a string representation of binary data into binary data
+ — the reverse of <function>PQescapeBytea</function>. This
+ is needed when retrieving <type>bytea</type> data in text format,
+ but not when retrieving it in binary format.
+
+ <synopsis>
+ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
+ </synopsis>
+ </para>
+
+ <para>
+ The <parameter>from</parameter> parameter points to a string
+ such as might be returned by <function>PQgetvalue</function> when applied
+ to a <type>bytea</type> column. <function>PQunescapeBytea</function>
+ converts this string representation into its binary representation.
+ It returns a pointer to a buffer allocated with
+ <function>malloc()</function>, or null on error, and puts the size of
+ the buffer in <parameter>to_length</parameter>. The result must be
+ freed using <function>PQfreemem</> when it is no longer needed.
+ </para>
+
+ <para>
+ This conversion is not exactly the inverse of
+ <function>PQescapeBytea</function>, because the string is not expected
+ to be <quote>escaped</> when received from <function>PQgetvalue</function>.
+ In particular this means there is no need for string quoting considerations,
+ and so no need for a <structname>PGconn</> parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQfreemem</function>
+ <indexterm>
+ <primary>PQfreemem</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Frees memory allocated by <application>libpq</>.
+ <synopsis>
+ void PQfreemem(void *ptr);
+ </synopsis>
+ </para>
+
+ <para>
+ Frees memory allocated by <application>libpq</>, particularly
+ <function>PQescapeByteaConn</function>,
+ <function>PQescapeBytea</function>,
+ <function>PQunescapeBytea</function>,
+ and <function>PQnotifies</function>.
+ It is particularly important that this function, rather than
+ <function>free()</>, be used on Microsoft Windows. This is because
+ allocating memory in a DLL and releasing it in the application works
+ only if multithreaded/single-threaded, release/debug, and static/dynamic
+ flags are the same for the DLL and the application. On non-Microsoft
+ Windows platforms, this function is the same as the standard library
+ function <function>free()</>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="libpq-async">
+ <title>Asynchronous Command Processing</title>
+
+ <indexterm zone="libpq-async">
+ <primary>nonblocking connection</primary>
+ </indexterm>
+
+ <para>
+ The <function>PQexec</function> function is adequate for submitting
+ commands in normal, synchronous applications. It has a couple of
+ deficiencies, however, that can be of importance to some users:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <function>PQexec</function> waits for the command to be completed.
+ The application might have other work to do (such as maintaining a
+ user interface), in which case it won't want to block waiting for
+ the response.
+ </para>
+ </listitem>
+
+ <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 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);
+
+ typedef struct pgNotify {
+ char *relname; /* notification condition name */
+ int be_pid; /* process ID of notifying server process */
+ char *extra; /* notification parameter */
+ } PGnotify;
+ </synopsis>
+ After processing a <structname>PGnotify</structname> object returned
+ by <function>PQnotifies</function>, be sure to free it with
+ <function>PQfreemem</function>. It is sufficient to free the
+ <structname>PGnotify</structname> pointer; the
+ <structfield>relname</structfield> and <structfield>extra</structfield>
+ fields do not represent separate allocations. (At present, the
+ <structfield>extra</structfield> field is unused and will always point
+ to an empty string.)
+ </para>
+
+ <para>
+ <xref linkend="libpq-example-2"> gives a sample program that illustrates
+ the use of asynchronous notification.
+ </para>
+
+ <para>
+ <function>PQnotifies</function> does not actually read data from the
+ server; it just returns messages previously absorbed by another
+ <application>libpq</application> function. In prior releases of
+ <application>libpq</application>, the only way to ensure timely receipt
+ of <command>NOTIFY</> messages was to constantly submit commands, even
+ empty ones, and then check <function>PQnotifies</function> after each
+ <function>PQexec</function>. While this still works, it is deprecated
+ as a waste of processing power.
+ </para>
+
+ <para>
+ A better way to check for <command>NOTIFY</> messages when you have no
+ useful commands to execute is to call
+ <function>PQconsumeInput</function>, then check
+ <function>PQnotifies</function>. You can use
+ <function>select()</function> to wait for data to arrive from the
+ server, thereby using no <acronym>CPU</acronym> power unless there is
+ something to do. (See <function>PQsocket</function> to obtain the file
+ descriptor number to use with <function>select()</function>.) Note that
+ this will work OK whether you submit commands with
+ <function>PQsendQuery</function>/<function>PQgetResult</function> or
+ simply use <function>PQexec</function>. You should, however, remember
+ to check <function>PQnotifies</function> after each
+ <function>PQgetResult</function> or <function>PQexec</function>, to
+ see if any notifications came in during the processing of the command.
+ </para>
+
+ </sect1>
+
+ <sect1 id="libpq-copy">
+ <title>Functions Associated with the <command>COPY</command> Command</title>
+
+ <indexterm zone="libpq-copy">
+ <primary>COPY</primary>
+ <secondary>with libpq</secondary>
+ </indexterm>
+
+ <para>
+ The <command>COPY</command> command in
+ <productname>PostgreSQL</productname> has options to read from or write
+ to the network connection used by <application>libpq</application>.
+ The functions described in this section allow applications to take
+ advantage of this capability by supplying or consuming copied data.
+ </para>
+
+ <para>
+ The overall process is that the application first issues the SQL
+ <command>COPY</command> command via <function>PQexec</function> or one
+ of the equivalent functions. The response to this (if there is no
+ error in the command) will be a <structname>PGresult</> object bearing
+ a status code of <literal>PGRES_COPY_OUT</literal> or
+ <literal>PGRES_COPY_IN</literal> (depending on the specified copy
+ direction). The application should then use the functions of this
+ section to receive or transmit data rows. When the data transfer is
+ complete, another <structname>PGresult</> object is returned to indicate
+ success or failure of the transfer. Its status will be
+ <literal>PGRES_COMMAND_OK</literal> for success or
+ <literal>PGRES_FATAL_ERROR</literal> if some problem was encountered.
+ At this point further SQL commands can be issued via
+ <function>PQexec</function>. (It is not possible to execute other SQL
+ commands using the same connection while the <command>COPY</command>
+ operation is in progress.)
+ </para>
+
+ <para>
+ If a <command>COPY</command> command is issued via
+ <function>PQexec</function> in a string that could contain additional
+ commands, the application must continue fetching results via
+ <function>PQgetResult</> after completing the <command>COPY</command>
+ sequence. Only when <function>PQgetResult</> returns
+ <symbol>NULL</symbol> is it certain that the <function>PQexec</function>
+ command string is done and it is safe to issue more commands.
+ </para>
+
+ <para>
+ The functions of this section should be executed only after obtaining
+ a result status of <literal>PGRES_COPY_OUT</literal> or
+ <literal>PGRES_COPY_IN</literal> from <function>PQexec</function> or
+ <function>PQgetResult</function>.
+ </para>
+
+ <para>
+ A <structname>PGresult</> object bearing one of these status values
+ carries some additional data about the <command>COPY</command> operation
+ that is starting. This additional data is available using functions
+ that are also used in connection with query results:
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQnfields</function>
+ <indexterm>
+ <primary>PQnfields</primary>
+ <secondary>with COPY</secondary>
+ </indexterm>
+ </term>
+
+ <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" endterm="sql-copy-title"> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQfformat</function>
+ <indexterm>
+ <primary>PQfformat</primary>
+ <secondary>with COPY</secondary>
+ </indexterm>
+ </term>
+
+ <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"
+ endterm="sql-copy-title"> for details.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>PQputCopyEnd</function>
+ <indexterm>
+ <primary>PQputCopyEnd</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Sends end-of-data indication to the server during <literal>COPY_IN</> state.
+ <synopsis>
+ int PQputCopyEnd(PGconn *conn,
+ const char *errormsg);
+ </synopsis>
+ </para>
+
+ <para>
+ Ends the <literal>COPY_IN</> operation successfully if
+ <parameter>errormsg</> is <symbol>NULL</symbol>. If
+ <parameter>errormsg</> is not <symbol>NULL</symbol> then the
+ <command>COPY</> is forced to fail, with the string pointed to by
+ <parameter>errormsg</> used as the error message. (One should not
+ assume that this exact error message will come back from the server,
+ however, as the server might have already failed the
+ <command>COPY</> for its own reasons. Also note that the option
+ to force failure does not work when using pre-3.0-protocol
+ connections.)
+ </para>
+
+ <para>
+ The result is 1 if the termination data was sent, zero if it was
+ not sent because the attempt would block (this case is only possible
+ if the connection is in nonblocking mode), or -1 if an error
+ occurred. (Use <function>PQerrorMessage</function> to retrieve
+ details if the return value is -1. If the value is zero, wait for
+ write-ready and try again.)
+ </para>
+
+ <para>
+ After successfully calling <function>PQputCopyEnd</>, call
+ <function>PQgetResult</> to obtain the final result status of the
+ <command>COPY</> command. One can wait for this result to be
+ available in the usual way. Then return to normal operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="libpq-copy-receive">
+ <title>Functions for Receiving <command>COPY</command> Data</title>
+
+ <para>
+ 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 must be freed using <function>PQfreemem</> when no longer
+ needed.
+ </para>
+
+ <para>
+ When a row is successfully returned, the return value is the number
+ of data bytes in the row (this will always be greater than zero).
+ The returned string is always null-terminated, though this is
+ probably only useful for textual <command>COPY</command>. A result
+ of zero indicates that the <command>COPY</command> is still in
+ progress, but no row is yet available (this is only possible when
+ <parameter>async</> is true). A result of -1 indicates that the
+ <command>COPY</command> is done. A result of -2 indicates that an
+ error occurred (consult <function>PQerrorMessage</> for the reason).
+ </para>
+
+ <para>
+ When <parameter>async</> is true (not zero),
+ <function>PQgetCopyData</> will not block waiting for input; it
+ will return zero if the <command>COPY</command> is still in progress
+ but no complete row is available. (In this case wait for read-ready
+ and then call <function>PQconsumeInput</> before calling
+ <function>PQgetCopyData</> again.) When <parameter>async</> is
+ false (zero), <function>PQgetCopyData</> will block until data is
+ available or the operation completes.
+ </para>
+
+ <para>
+ After <function>PQgetCopyData</> returns -1, call
+ <function>PQgetResult</> to obtain the final result status of the
+ <command>COPY</> command. One can wait for this result to be
+ available in the usual way. Then return to normal operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="libpq-copy-deprecated">
+ <title>Obsolete Functions for <command>COPY</command></title>
+
+ <para>
+ These functions represent older methods of handling <command>COPY</>.
+ Although they still work, they are deprecated due to poor error handling,
+ inconvenient methods of detecting end-of-data, and lack of support for binary
+ or nonblocking transfers.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQgetline</function>
+ <indexterm>
+ <primary>PQgetline</primary>
+ </indexterm>
+ </term>
+
+ <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>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>
+ </variablelist>
+
+ </sect1>
+
+ <sect1 id="libpq-notice-processing">
+ <title>Notice Processing</title>
+
+ <indexterm zone="libpq-notice-processing">
+ <primary>notice processing</primary>
+ <secondary>in libpq</secondary>
+ </indexterm>
+
+ <para>
+ Notice and warning messages generated by the server are not returned
+ by the query execution functions, since they do not imply failure of
+ the query. Instead they are passed to a notice handling function, and
+ execution continues normally after the handler returns. The default
+ notice handling function prints the message on
+ <filename>stderr</filename>, but the application can override this
+ behavior by supplying its own handling function.
+ </para>
+
+ <para>
+ For historical reasons, there are two levels of notice handling, called
+ the notice receiver and notice processor. The default behavior is for
+ the notice receiver to format the notice and pass a string to the notice
+ processor for printing. However, an application that chooses to provide
+ its own notice receiver will typically ignore the notice processor
+ layer and just do all the work in the notice receiver.
+ </para>
+
+ <para>
+ The function <function>PQsetNoticeReceiver</function>
+ <indexterm><primary>notice
+ receiver</></><indexterm><primary>PQsetNoticeReceiver</></> sets or
+ examines the current notice receiver for a connection object.
+ Similarly, <function>PQsetNoticeProcessor</function>
+ <indexterm><primary>notice
+ processor</></><indexterm><primary>PQsetNoticeProcessor</></> sets or
+ examines the current notice processor.
+
+ <synopsis>
+ typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
+
+ PQnoticeReceiver
+ PQsetNoticeReceiver(PGconn *conn,
+ PQnoticeReceiver proc,
+ void *arg);
+
+ typedef void (*PQnoticeProcessor) (void *arg, const char *message);
+
+ PQnoticeProcessor
+ PQsetNoticeProcessor(PGconn *conn,
+ PQnoticeProcessor proc,
+ void *arg);
+ </synopsis>
+
+ Each of these functions returns the previous notice receiver or
+ processor function pointer, and sets the new value. If you supply a
+ null function pointer, no action is taken, but the current pointer is
+ returned.
+ </para>
+
+ <para>
+ When a notice or warning message is received from the server, or
+ generated internally by <application>libpq</application>, the notice
+ receiver function is called. It is passed the message in the form of
+ a <symbol>PGRES_NONFATAL_ERROR</symbol>
+ <structname>PGresult</structname>. (This allows the receiver to extract
+ individual fields using <function>PQresultErrorField</>, or the complete
+ preformatted message using <function>PQresultErrorMessage</>.) The same
+ void pointer passed to <function>PQsetNoticeReceiver</function> is also
+ passed. (This pointer can be used to access application-specific state
+ if needed.)
+ </para>
+
+ <para>
+ The default notice receiver simply extracts the message (using
+ <function>PQresultErrorMessage</>) and passes it to the notice
+ processor.
+ </para>
+
+ <para>
+ The notice processor is responsible for handling a notice or warning
+ message given in text form. It is passed the string text of the message
+ (including a trailing newline), plus a void pointer that is the same
+ one passed to <function>PQsetNoticeProcessor</function>. (This pointer
+ can be used to access application-specific state if needed.)
+ </para>
+
+ <para>
+ The default notice processor is simply:
+ <programlisting>
+static void
+defaultNoticeProcessor(void *arg, const char *message)
+{
+ fprintf(stderr, "%s", message);
+}
+</programlisting>
+ </para>
+
+ <para>
+ Once you have set a notice receiver or processor, you should expect
+ that that function could be called as long as either the
+ <structname>PGconn</> object or <structname>PGresult</> objects made
+ from it exist. At creation of a <structname>PGresult</>, the
+ <structname>PGconn</>'s current notice handling pointers are copied
+ into the <structname>PGresult</> for possible use by functions like
+ <function>PQgetvalue</function>.
+ </para>
+
+ </sect1>
+
+ <sect1 id="libpq-envars">
+ <title>Environment Variables</title>
+
+ <indexterm zone="libpq-envars">
+ <primary>environment variable</primary>
+ </indexterm>
+
+ <para>
+ The following environment variables can be used to select default
+ connection parameter values, which will be used by
+ <function>PQconnectdb</>, <function>PQsetdbLogin</> and
+ <function>PQsetdb</> if no value is directly specified by the calling
+ code. These are useful to avoid hard-coding database connection
+ information into simple client applications, for example.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGHOST</envar></primary>
+ </indexterm>
+ <envar>PGHOST</envar> sets the database server name.
+ If this begins with a slash, it specifies Unix-domain communication
+ rather than TCP/IP communication; the value is then the name of the
+ directory in which the socket file is stored (in a default installation
+ setup this would be <filename>/tmp</filename>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGHOSTADDR</envar></primary>
+ </indexterm>
+ <envar>PGHOSTADDR</envar> specifies the numeric IP address of the database
+ server. This can be set instead of or in addition to <envar>PGHOST</envar>
+ to avoid DNS lookup overhead. See the documentation of
+ these parameters, under <function>PQconnectdb</function> above, for details
+ on their interaction.
+ </para>
+ <para>
+ When neither <envar>PGHOST</envar> nor <envar>PGHOSTADDR</envar> is set,
+ the default behavior is to connect using a local Unix-domain socket; or on
+ machines without Unix-domain sockets, <application>libpq</application> will
+ attempt to connect to <literal>localhost</>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGPORT</envar></primary>
+ </indexterm>
+ <envar>PGPORT</envar> sets the TCP port number or Unix-domain socket
+ file extension for communicating with the
+ <productname>PostgreSQL</productname> server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGDATABASE</envar></primary>
+ </indexterm>
+ <envar>PGDATABASE</envar> sets the
+ <productname>PostgreSQL</productname> database name.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGUSER</envar></primary>
+ </indexterm>
+ <envar>PGUSER</envar> sets the user name used to connect to the
+ database.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGPASSWORD</envar></primary>
+ </indexterm>
+ <envar>PGPASSWORD</envar> sets the password used if the server
+ demands password authentication. Use of this environment variable
+ is not recommended for security reasons (some operating systems
+ allow non-root users to see process environment variables via
+ <application>ps</>); instead consider using the
+ <filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGPASSFILE</envar></primary>
+ </indexterm>
+ <envar>PGPASSFILE</envar> specifies the name of the password file to
+ use for lookups. If not set, it defaults to <filename>~/.pgpass</>
+ (see <xref linkend="libpq-pgpass">).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSERVICE</envar></primary>
+ </indexterm>
+ <envar>PGSERVICE</envar>
+ sets the service name to be looked up in
+ <filename>pg_service.conf</filename>. This offers a shorthand way
+ of setting all the parameters.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGREALM</envar></primary>
+ </indexterm>
+ <envar>PGREALM</envar> sets the Kerberos realm to use with
+ <productname>PostgreSQL</productname>, if it is different from the
+ local realm. If <envar>PGREALM</envar> is set,
+ <application>libpq</application> applications will attempt
+ authentication with servers for this realm and use separate ticket
+ files to avoid conflicts with local ticket files. This
+ environment variable is only used if Kerberos authentication is
+ selected by the server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGOPTIONS</envar></primary>
+ </indexterm>
+ <envar>PGOPTIONS</envar> sets additional run-time options for the
+ <productname>PostgreSQL</productname> server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSSLMODE</envar></primary>
+ </indexterm>
+ <envar>PGSSLMODE</envar> determines whether and with what priority
+ an <acronym>SSL</> connection will be negotiated with the server.
+ There are four modes: <literal>disable</> will attempt only an
+ unencrypted <acronym>SSL</> connection; <literal>allow</> will
+ negotiate, trying first a non-<acronym>SSL</> connection, then if
+ that fails, trying an <acronym>SSL</> connection; <literal>prefer</>
+ (the default) will negotiate, trying first an <acronym>SSL</>
+ connection, then if that fails, trying a regular non-<acronym>SSL</>
+ connection; <literal>require</> will try only an <acronym>SSL</>
+ connection. If <productname>PostgreSQL</> is compiled without SSL
+ support, using option <literal>require</> will cause an error, while
+ options <literal>allow</> and <literal>prefer</> will be accepted
+ but <application>libpq</> will not in fact attempt an <acronym>SSL</>
+ connection.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGREQUIRESSL</envar></primary>
+ </indexterm>
+ <envar>PGREQUIRESSL</envar> sets whether or not the connection must
+ be made over <acronym>SSL</acronym>. If set to <quote>1</quote>,
+ <application>libpq</> will refuse to connect if the server does not
+ accept an <acronym>SSL</acronym> connection (equivalent to
+ <literal>sslmode</> <literal>prefer</>). This option is deprecated
+ in favor of the <literal>sslmode</> setting, and is only available
+ if <productname>PostgreSQL</> is compiled with SSL support.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSSLKEY</envar></primary>
+ </indexterm>
+ <envar>PGSSLKEY</envar> specifies the hardware token that stores the
+ secret key for the client certificate. The value of this variable
+ should consist of a colon-separated engine name (engines are
+ <productname>OpenSSL</> loadable modules) and an engine-specific key
+ identifier. If this is not set, the secret key must be kept in a
+ file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGKRBSRVNAME</envar></primary>
+ </indexterm>
+ <envar>PGKRBSRVNAME</envar> sets the Kerberos service name to use
+ when authenticating with Kerberos 5 or GSSAPI.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGGSSLIB</envar></primary>
+ </indexterm>
+ <envar>PGGSSLIB</envar> sets the GSS library to use for GSSAPI
+ authentication.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGCONNECT_TIMEOUT</envar></primary>
+ </indexterm>
+ <envar>PGCONNECT_TIMEOUT</envar> sets the maximum number of seconds
+ that <application>libpq</application> will wait when attempting to
+ connect to the <productname>PostgreSQL</productname> server. If
+ unset or set to zero, <application>libpq</application> will wait
+ indefinitely. It is not recommended to set the timeout to less than
+ 2 seconds.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The following environment variables can be used to specify default
+ behavior for each <productname>PostgreSQL</productname> session. (See
+ also the <xref linkend="sql-alteruser" endterm="sql-alteruser-title">
+ and <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">
+ commands for ways to set default behavior on a per-user or per-database
+ basis.)
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGDATESTYLE</envar></primary>
+ </indexterm>
+ <envar>PGDATESTYLE</envar> sets the default style of date/time
+ representation. (Equivalent to <literal>SET datestyle TO
+ ...</literal>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGTZ</envar></primary>
+ </indexterm>
+ <envar>PGTZ</envar> sets the default time zone. (Equivalent to
+ <literal>SET timezone TO ...</literal>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGCLIENTENCODING</envar></primary>
+ </indexterm>
+ <envar>PGCLIENTENCODING</envar> sets the default client character
+ set encoding. (Equivalent to <literal>SET client_encoding TO
+ ...</literal>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGGEQO</envar></primary>
+ </indexterm>
+ <envar>PGGEQO</envar> sets the default mode for the genetic query
+ optimizer. (Equivalent to <literal>SET geqo TO ...</literal>.)
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ Refer to the <acronym>SQL</acronym> command <xref linkend="sql-set"
+ endterm="sql-set-title"> for information on correct values for these
+ environment variables.
+ </para>
+
+ <para>
+ The following environment variables determine internal behavior of
+ <application>libpq</application>; they override compiled-in defaults.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGSYSCONFDIR</envar></primary>
+ </indexterm>
+ <envar>PGSYSCONFDIR</envar> sets the directory containing the
+ <filename>pg_service.conf</> file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary><envar>PGLOCALEDIR</envar></primary>
+ </indexterm>
+ <envar>PGLOCALEDIR</envar> sets the directory containing the
+ <literal>locale</> files for message internationalization.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect1>
+
+
+ <sect1 id="libpq-pgpass">
+ <title>The Password File</title>
+
+ <indexterm zone="libpq-pgpass">
+ <primary>password file</primary>
+ </indexterm>
+ <indexterm zone="libpq-pgpass">
+ <primary>.pgpass</primary>
+ </indexterm>
+
+ <para>
+ The file <filename>.pgpass</filename> in a user's home directory or the
+ file referenced by <envar>PGPASSFILE</envar> can contain passwords to
+ be used if the connection requires a password (and no password has been
+ specified otherwise). On Microsoft Windows the file is named
+ <filename>%APPDATA%\postgresql\pgpass.conf</> (where
+ <filename>%APPDATA%</> refers to the Application Data subdirectory in
+ the user's profile).
+ </para>
-<para>
- -1 is returned if the given name does not match any column.
-</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.
+ </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</></></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.
- Result column numbers start at 0.
-<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>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);
+ <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>
-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 may 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</>, or
- <command>FETCH</> statement, or an <command>EXECUTE</> of a
- prepared query that contains a <command>INSERT</>,
- <command>UPDATE</>, or <command>DELETE</> statement. If the
- command that generated the <structname>PGresult</> was
- anything else, <function>PQcmdTuples</> returns the 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>
-
-</sect2>
-
-<sect2 id="libpq-exec-escape-string">
- <title>Escaping Strings for Inclusion in SQL Commands</title>
-
- <indexterm zone="libpq-exec-escape-string"><primary>PQescapeString</></>
- <indexterm zone="libpq-exec-escape-string"><primary>escaping strings</></>
-
-<para>
-<function>PQescapeString</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>PQescapeString</> performs this operation.
-</para>
-
-<tip>
-<para>
-It is especially important to do proper escaping when handling strings that
-were received from an untrustworthy source. Otherwise there is a security
-risk: you are vulnerable to <quote>SQL injection</> attacks wherein unwanted
-SQL commands are fed to your database.
-</para>
-</tip>
-
-<para>
-Note that it is not necessary nor correct to do escaping when a data
-value is passed as a separate parameter in <function>PQexecParams</> or
-its sibling routines.
-<synopsis>
-size_t PQescapeString (char *to, const char *from, size_t length);
-</synopsis>
-</para>
-
-<para>
-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 characters 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>PQescapeString</> 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 character than twice
-the value of <parameter>length</>, otherwise the behavior is
-undefined. A call to <function>PQescapeString</> writes an escaped
-version of the <parameter>from</> string to the <parameter>to</>
-buffer, replacing 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.
-</para>
-<para>
-<function>PQescapeString</> returns the number of characters written
-to <parameter>to</>, not including the terminating zero byte.
-</para>
-<para>
-Behavior is undefined if the <parameter>to</> and <parameter>from</>
-strings overlap.
-</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</>
+ <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>
- <variablelist>
- <varlistentry>
- <term><function>PQescapeBytea</function><indexterm><primary>PQescapeBytea</></></term>
- <listitem>
<para>
- Escapes binary data for use within an SQL command with the type
- <type>bytea</type>. As with <function>PQescapeString</function>,
- this is only used when inserting data directly into an SQL command string.
-<synopsis>
-unsigned char *PQescapeBytea(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>may</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
- two backslashes. The single quote (<literal>'</>) and backslash
- (<literal>\</>) characters have special alternative escape
- sequences. See <xref linkend="datatype-binary"> for more
- information. <function>PQescapeBytea</function> performs this
- operation, escaping only the minimally required bytes.
+ 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 <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. The result string length includes the terminating
- zero byte of the result.
+ 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>
- <function>PQescapeBytea</> 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.
+ 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>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>PQunescapeBytea</function><indexterm><primary>PQunescapeBytea</></></term>
- <listitem>
<para>
- Converts an escaped 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.
+ 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>
-unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
-</synopsis>
-</para>
-
-<para>
- The <parameter>from</parameter> parameter points to an escaped 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>
+ 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>
- </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>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()</>.
+ 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>
- </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 may 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>, and
-<function>PQsendQueryPrepared</function>,
-which can be used with <function>PQgetResult</function> to duplicate the
-functionality of
-<function>PQexecParams</function>,
-<function>PQprepare</function>, and
-<function>PQexecPrepared</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> may not 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>
+ <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>
- 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>
+ </sect1>
- This is an asynchronous version of <function>PQprepare</>: it
- returns 1 if it was able to dispatch the request, and 0 if not.
- After a successful call, call <function>PQgetResult</function>
- to determine whether the server successfully created the prepared
- statement.
- The function's parameters are handled identically to
- <function>PQprepare</function>. Like
- <function>PQprepare</function>, it will not work on 2.0-protocol
- connections.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>PQsendQueryPrepared</function><indexterm><primary>PQsendQueryPrepared</></></term>
-<listitem>
-<para>
- Sends a request to execute a prepared statement with given
- parameters, without waiting for the result(s).
-<synopsis>
-int PQsendQueryPrepared(PGconn *conn,
- const char *stmtName,
- int nParams,
- const char * const *paramValues,
- const int *paramLengths,
- const int *paramFormats,
- int resultFormat);
-</synopsis>
- This is similar to <function>PQsendQueryParams</function>, but the
- command to be executed is specified by naming a previously-prepared
- statement, instead of giving a query string.
- The function's parameters are handled identically to
- <function>PQexecPrepared</function>. Like
- <function>PQexecPrepared</function>, it will not work on 2.0-protocol
- connections.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term><function>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 may check
-<function>PQisBusy</function> and/or <function>PQnotifies</function> to see if
-their state has changed.
-</para>
-<para>
-<function>PQconsumeInput</function> may 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 may 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>
+ <sect1 id="libpq-ssl">
+ <title>SSL Support</title>
-<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>
+ <indexterm zone="libpq-ssl">
+ <primary>SSL</primary>
+ </indexterm>
-<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 may 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>
+ <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>
-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>
+ <para>
+ <application>libpq</application> reads the system-wide
+ <productname>OpenSSL</productname> configuration file. By default, this
+ file is named <filename>openssl.cnf</filename> and is located in the
+ directory reported by <literal>openssl version -d</>. This default
+ can be overridden by setting environment variable
+ <envar>OPENSSL_CONF</envar> to the name of the desired configuration
+ file.
+ </para>
- <indexterm zone="libpq-notify">
- <primary>NOTIFY</primary>
- <secondary>in libpq</secondary>
- </indexterm>
+ <para>
+ To verify the server certificate is trustworthy, place certificates of
+ the certificate authorities (<acronym>CA</acronym>) you trust 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>.)
+ <application>libpq</application> will then verify that the server's
+ certificate is signed by one of the trusted certificate authorities.
+ The SSL connection will fail if the server does not present a trusted
+ certificate. 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>
-<para>
-<productname>PostgreSQL</productname> offers asynchronous notification via the
-<command>LISTEN</command> and <command>NOTIFY</command> commands. A client session registers its interest in a particular
-notification condition with the <command>LISTEN</command> command (and can stop listening
-with the <command>UNLISTEN</command> command). All sessions listening on a
-particular condition will be notified asynchronously when a <command>NOTIFY</command> command with that
-condition name is executed by any session. No additional information is
-passed from the notifier to the listener. Thus, typically, any actual data
-that needs to be communicated is transferred through a database table.
-Commonly, the condition name is the same as the associated table, but it is
-not necessary for there to be any associated table.
-</para>
-
-<para>
-<application>libpq</application> applications submit
-<command>LISTEN</command> and <command>UNLISTEN</command> commands as
-ordinary SQL commands. The arrival of <command>NOTIFY</command>
-messages can subsequently be detected by calling
-<function>PQnotifies</function>.<indexterm><primary>PQnotifies</></>
-</para>
-
-<para>
-The function <function>PQnotifies</function>
- returns the next notification from a list of unhandled
- notification messages received from the server. It returns a null pointer if
- there are no pending notifications. Once a notification is
- returned from <function>PQnotifies</>, it is considered handled and will be
- removed from the list of notifications.
-<synopsis>
-PGnotify *PQnotifies(PGconn *conn);
+ <para>
+ 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, unless the secret key for the certificate is stored in a
+ hardware token, as specified by <envar>PGSSLKEY</envar>. 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.
+ </para>
-typedef struct pgNotify {
- char *relname; /* notification condition name */
- int be_pid; /* process ID of 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>
-
-<note>
-<para>
- In <productname>PostgreSQL</productname> 6.4 and later,
- the <structfield>be_pid</structfield> is that of the notifying server process,
- whereas in earlier versions it was always the <acronym>PID</acronym> of your own server process.
-</para>
-</note>
-
-<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 may 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 may 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 may 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 before trying again; it does not matter whether you call
-<function>PQconsumeInput</>.) 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 may 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 the environment variable <envar>PGSSLKEY</envar> is set, its value
+ should consist of a colon-separated engine name and key identifier. In
+ this case, <application>libpq</application> will load the specified
+ engine, i.e. the <productname>OpenSSL</> module which supports special
+ hardware, and reference the key with the specified identifier.
+ Identifiers are engine-specific. Typically, cryptography hardware tokens
+ do not reveal secret keys to the application. Instead, applications
+ delegate all cryptography operations which require the secret key to
+ the hardware token.
+ </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 may 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>
-</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-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>
+ If you are using <acronym>SSL</> inside your application (in addition
+ to inside <application>libpq</application>), you can use
+ <function>PQinitSSL(int)</> to tell <application>libpq</application>
+ that the <acronym>SSL</> library has already been initialized by your
+ application.
+ <!-- If 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>
-<synopsis>
-typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
+ <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 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>
-PQnoticeReceiver
-PQsetNoticeReceiver(PGconn *conn,
- PQnoticeReceiver proc,
- void *arg);
+ </sect1>
-typedef void (*PQnoticeProcessor) (void *arg, const char *message);
-PQnoticeProcessor
-PQsetNoticeProcessor(PGconn *conn,
- PQnoticeProcessor proc,
- void *arg);
-</synopsis>
+ <sect1 id="libpq-threading">
+ <title>Behavior in Threaded Programs</title>
-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 the name of the
-directory in which the socket file is stored (default <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 <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>
-</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. This environment variable is deprecated for security
-reasons; consider migrating to use the <filename>$HOME/.pgpass</>
-file (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, and options
-<literal>allow</> and <literal>prefer</> will be tolerated but
-<application>libpq</> will be unable to negotiate 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>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 <command>ALTER USER</> and <command>ALTER DATABASE</>
-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>
-<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.
-</para>
-</listitem>
-</itemizedlist>
-
-Refer to the <acronym>SQL</acronym> command <command>SET</command>
-for information on correct values for these environment variables.
-</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 is a file
-that can contain passwords to be used if the connection requires a
-password (and no password has been specified otherwise).
-This file should have 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 may 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>.
-</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.
-</para>
-</sect1>
-
-
-<sect1 id="libpq-ssl">
-<title>SSL Support</title>
-
-<indexterm zone="libpq-ssl">
- <primary>SSL</primary>
-</indexterm>
+ <indexterm zone="libpq-threading">
+ <primary>threads</primary>
+ <secondary>with libpq</secondary>
+ </indexterm>
+
+ <para>
+ <application>libpq</application> is reentrant and thread-safe if the
+ <filename>configure</filename> command-line option
+ <literal>--enable-thread-safety</> was used when the
+ <productname>PostgreSQL</productname> distribution was built. In
+ addition, you might need to use additional compiler command-line
+ options when you compile your application code. Refer to your
+ system's documentation for information about how to build
+ thread-enabled applications, or look in
+ <filename>src/Makefile.global</filename> for <literal>PTHREAD_CFLAGS</>
+ and <literal>PTHREAD_LIBS</>. This function allows the querying of
+ <application>libpq</application>'s thread-safe status:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>PQisthreadsafe</function>
+ <indexterm>
+ <primary>PQisthreadsafe</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns the thread safety status of the
+ <application>libpq</application> library.
+ <synopsis>
+ int PQisthreadsafe();
+ </synopsis>
+ </para>
+
+ <para>
+ Returns 1 if the <application>libpq</application> is thread-safe
+ and 0 if it is not.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ One thread restriction is that no two threads attempt to manipulate
+ the same <structname>PGconn</> object at the same time. In particular,
+ you cannot issue concurrent commands from different threads through
+ the same connection object. (If you need to run concurrent commands,
+ use multiple connections.)
+ </para>
+
+ <para>
+ <structname>PGresult</> objects are read-only after creation, and so
+ can be passed around freely between threads.
+ </para>
<para>
- <productname>PostgreSQL</> has native support for using
- <acronym>SSL</> connections to encrypt client/server communications
- for increased security. See <xref linkend="ssl-tcp"> for details
- about the server-side <acronym>SSL</> functionality.
+ The 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 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.
+ 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 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. 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.
+ 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-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</> has been 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</>.
-</para>
-
-<para>
-One 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>,
-<function>PQoidStatus</function> and
-<function>fe_setauthsvc</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>.
-There is no good reason to call <function>fe_setauthsvc</function> at all.
-</para>
-
-<para>
-<application>libpq</application> applications that use the
-<literal>crypt</literal> authentication method rely on the
-<literal>crypt()</literal> operating system function, which is often
-not thread-safe.<indexterm><primary>crypt</><secondary>thread
-safety</></> It is better to use the <literal>md5</literal> method,
-which is thread-safe on all platforms.
-</para>
-
-<para>
-<application>libpq</application> must ignore <literal>SIGPIPE</> signals
-generated internally by <function>send()</> calls to backend processes.
-When <productname>PostgreSQL</> is configured without
-<literal>--enable-thread-safety</>, <application>libpq</> sets
-<literal>SIGPIPE</> to <literal>SIG_IGN</> before each
-<function>send()</> call and restores the original signal handler after
-completion. When <literal>--enable-thread-safety</> is used,
-<application>libpq</> installs its own <literal>SIGPIPE</> handler
-before the first database connection. This handler uses thread-local
-storage to determine if a <literal>SIGPIPE</> signal has been generated
-by a libpq <function>send()</>. If an application wants to install
-its own <literal>SIGPIPE</> signal handler, it should call
-<function>PQinSend()</> to determine if it should ignore the
-<literal>SIGPIPE</> signal. This function is available in both
-thread-safe and non-thread-safe versions of <application>libpq</>.
-</para>
-
-<para>
-If you experience problems with threaded applications, run
-the program in <filename>src/tools/thread</> to see if your
-platform has thread-unsafe functions. This program is run
-by <filename>configure</filename>, but for binary distributions
-your library might not match the library used to build the binaries.
-</para>
-</sect1>
+ </sect1>
<sect1 id="libpq-build">
</indexterm>
<para>
- To build (i.e., compile and link) your <application>libpq</application> programs you need to
- do all of the following things:
+ To build (i.e., compile and link) a program using
+ <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)
<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>
</para>
- <para>
- <indexterm><primary>libpq-int.h</></>
- If your codes references the header file
- <filename>libpq-int.h</filename> and you refuse to fix your code to
- not use it, starting in <productname>PostgreSQL</> 7.2, this file will be found in
- <filename><replaceable>includedir</replaceable>/postgresql/internal/libpq-int.h</filename>,
- so you need to add the appropriate <option>-I</option> option to
- your compiler command line.
- </para>
-
</sect1>
/*
* testlibpq.c
*
- * Test the C version of LIBPQ, the POSTGRES frontend library.
+ * Test the C version of libpq, the PostgreSQL frontend library.
*/
#include <stdio.h>
#include <stdlib.h>
static void
exit_nicely(PGconn *conn)
{
- PQfinish(conn);
- exit(1);
+ PQfinish(conn);
+ exit(1);
}
int
main(int argc, char **argv)
{
- const char *conninfo;
- PGconn *conn;
- PGresult *res;
- int nFields;
- int i,
- j;
-
- /*
- * If the user supplies a parameter on the command line, use it as
- * the conninfo string; otherwise default to setting dbname=template1
- * and using environment variables or defaults for all other connection
- * parameters.
- */
- if (argc > 1)
- conninfo = argv[1];
- else
- conninfo = "dbname = template1";
-
- /* Make a connection to the database */
- conn = PQconnectdb(conninfo);
-
- /* Check to see that the backend connection was successfully made */
- if (PQstatus(conn) != CONNECTION_OK)
- {
- fprintf(stderr, "Connection to database failed: %s",
- PQerrorMessage(conn));
- exit_nicely(conn);
- }
-
- /*
- * Our test case here involves using a cursor, for which we must be
- * inside a transaction block. We could do the whole thing with a
- * single PQexec() of "select * from pg_database", but that's too
- * trivial to make a good example.
- */
-
- /* Start a transaction block */
- res = PQexec(conn, "BEGIN");
- if (PQresultStatus(res) != PGRES_COMMAND_OK)
- {
- fprintf(stderr, "BEGIN command failed: %s", PQerrorMessage(conn));
- PQclear(res);
- exit_nicely(conn);
- }
-
- /*
- * Should PQclear PGresult whenever it is no longer needed to avoid
- * memory leaks
- */
+ const char *conninfo;
+ PGconn *conn;
+ PGresult *res;
+ int nFields;
+ int i,
+ j;
+
+ /*
+ * If the user supplies a parameter on the command line, use it as the
+ * conninfo string; otherwise default to setting dbname=postgres and using
+ * environment variables or defaults for all other connection parameters.
+ */
+ if (argc > 1)
+ conninfo = argv[1];
+ else
+ conninfo = "dbname = postgres";
+
+ /* Make a connection to the database */
+ conn = PQconnectdb(conninfo);
+
+ /* Check to see that the backend connection was successfully made */
+ if (PQstatus(conn) != CONNECTION_OK)
+ {
+ fprintf(stderr, "Connection to database failed: %s",
+ PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ /*
+ * Our test case here involves using a cursor, for which we must be inside
+ * a transaction block. We could do the whole thing with a single
+ * PQexec() of "select * from pg_database", but that's too trivial to make
+ * a good example.
+ */
+
+ /* Start a transaction block */
+ res = PQexec(conn, "BEGIN");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "BEGIN command failed: %s", PQerrorMessage(conn));
PQclear(res);
-
- /*
- * Fetch rows from pg_database, the system catalog of databases
- */
- res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database");
- if (PQresultStatus(res) != PGRES_COMMAND_OK)
- {
- fprintf(stderr, "DECLARE CURSOR failed: %s", PQerrorMessage(conn));
- PQclear(res);
- exit_nicely(conn);
- }
+ exit_nicely(conn);
+ }
+
+ /*
+ * Should PQclear PGresult whenever it is no longer needed to avoid memory
+ * leaks
+ */
+ PQclear(res);
+
+ /*
+ * Fetch rows from pg_database, the system catalog of databases
+ */
+ res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "DECLARE CURSOR failed: %s", PQerrorMessage(conn));
PQclear(res);
+ exit_nicely(conn);
+ }
+ PQclear(res);
+
+ res = PQexec(conn, "FETCH ALL in myportal");
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "FETCH ALL failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
- res = PQexec(conn, "FETCH ALL in myportal");
- if (PQresultStatus(res) != PGRES_TUPLES_OK)
- {
- fprintf(stderr, "FETCH ALL failed: %s", PQerrorMessage(conn));
- PQclear(res);
- exit_nicely(conn);
- }
-
- /* first, print out the attribute names */
- nFields = PQnfields(res);
- for (i = 0; i < nFields; i++)
- printf("%-15s", PQfname(res, i));
- printf("\n\n");
+ /* first, print out the attribute names */
+ nFields = PQnfields(res);
+ 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 (j = 0; j < nFields; j++)
- printf("%-15s", PQgetvalue(res, i, j));
- printf("\n");
- }
+ /* next, print out the rows */
+ for (i = 0; i < PQntuples(res); i++)
+ {
+ for (j = 0; j < nFields; j++)
+ printf("%-15s", PQgetvalue(res, i, j));
+ printf("\n");
+ }
- PQclear(res);
+ PQclear(res);
- /* close the portal ... we don't bother to check for errors ... */
- res = PQexec(conn, "CLOSE myportal");
- PQclear(res);
+ /* close the portal ... we don't bother to check for errors ... */
+ res = PQexec(conn, "CLOSE myportal");
+ PQclear(res);
- /* end the transaction */
- res = PQexec(conn, "END");
- PQclear(res);
+ /* end the transaction */
+ res = PQexec(conn, "END");
+ PQclear(res);
- /* close the connection to the database and cleanup */
- PQfinish(conn);
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
- return 0;
+ return 0;
}
</programlisting>
</example>
<programlisting>
/*
* testlibpq2.c
- * Test of the asynchronous notification interface
+ * Test of the asynchronous notification interface
*
* Start this program, then from psql in another window do
* NOTIFY TBL2;
static void
exit_nicely(PGconn *conn)
{
- PQfinish(conn);
- exit(1);
+ PQfinish(conn);
+ exit(1);
}
int
main(int argc, char **argv)
{
- const char *conninfo;
- PGconn *conn;
- PGresult *res;
- PGnotify *notify;
- int nnotifies;
-
+ const char *conninfo;
+ PGconn *conn;
+ PGresult *res;
+ PGnotify *notify;
+ int nnotifies;
+
+ /*
+ * If the user supplies a parameter on the command line, use it as the
+ * conninfo string; otherwise default to setting dbname=postgres and using
+ * environment variables or defaults for all other connection parameters.
+ */
+ if (argc > 1)
+ conninfo = argv[1];
+ else
+ conninfo = "dbname = postgres";
+
+ /* Make a connection to the database */
+ conn = PQconnectdb(conninfo);
+
+ /* Check to see that the backend connection was successfully made */
+ if (PQstatus(conn) != CONNECTION_OK)
+ {
+ fprintf(stderr, "Connection to database failed: %s",
+ PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ /*
+ * Issue LISTEN command to enable notifications from the rule's NOTIFY.
+ */
+ res = PQexec(conn, "LISTEN TBL2");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ {
+ fprintf(stderr, "LISTEN command failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ /*
+ * should PQclear PGresult whenever it is no longer needed to avoid memory
+ * leaks
+ */
+ PQclear(res);
+
+ /* Quit after four notifies are received. */
+ nnotifies = 0;
+ while (nnotifies < 4)
+ {
/*
- * If the user supplies a parameter on the command line, use it as
- * the conninfo string; otherwise default to setting dbname=template1
- * and using environment variables or defaults for all other connection
- * parameters.
+ * Sleep until something happens on the connection. We use select(2)
+ * to wait for input, but you could also use poll() or similar
+ * facilities.
*/
- if (argc > 1)
- conninfo = argv[1];
- else
- conninfo = "dbname = template1";
+ int sock;
+ fd_set input_mask;
- /* Make a connection to the database */
- conn = PQconnectdb(conninfo);
+ sock = PQsocket(conn);
- /* Check to see that the backend connection was successfully made */
- if (PQstatus(conn) != CONNECTION_OK)
- {
- fprintf(stderr, "Connection to database failed: %s",
- PQerrorMessage(conn));
- exit_nicely(conn);
- }
+ if (sock < 0)
+ break; /* shouldn't happen */
- /*
- * Issue LISTEN command to enable notifications from the rule's NOTIFY.
- */
- res = PQexec(conn, "LISTEN TBL2");
- if (PQresultStatus(res) != PGRES_COMMAND_OK)
+ FD_ZERO(&input_mask);
+ FD_SET(sock, &input_mask);
+
+ if (select(sock + 1, &input_mask, NULL, NULL, NULL) < 0)
{
- fprintf(stderr, "LISTEN command failed: %s", PQerrorMessage(conn));
- PQclear(res);
- exit_nicely(conn);
+ fprintf(stderr, "select() failed: %s\n", strerror(errno));
+ exit_nicely(conn);
}
- /*
- * should PQclear PGresult whenever it is no longer needed to avoid
- * memory leaks
- */
- PQclear(res);
-
- /* Quit after four notifies are received. */
- nnotifies = 0;
- while (nnotifies < 4)
+ /* Now check for input */
+ PQconsumeInput(conn);
+ while ((notify = PQnotifies(conn)) != NULL)
{
- /*
- * Sleep until something happens on the connection. We use select(2)
- * to wait for input, but you could also use poll() or similar
- * facilities.
- */
- int sock;
- fd_set input_mask;
-
- sock = PQsocket(conn);
-
- if (sock < 0)
- break; /* shouldn't happen */
-
- FD_ZERO(&input_mask);
- FD_SET(sock, &input_mask);
-
- if (select(sock + 1, &input_mask, NULL, NULL, NULL) < 0)
- {
- fprintf(stderr, "select() failed: %s\n", strerror(errno));
- exit_nicely(conn);
- }
-
- /* Now check for input */
- PQconsumeInput(conn);
- while ((notify = PQnotifies(conn)) != NULL)
- {
- fprintf(stderr,
- "ASYNC NOTIFY of '%s' received from backend pid %d\n",
- notify->relname, notify->be_pid);
- PQfreemem(notify);
- nnotifies++;
- }
+ fprintf(stderr,
+ "ASYNC NOTIFY of '%s' received from backend pid %d\n",
+ notify->relname, notify->be_pid);
+ PQfreemem(notify);
+ nnotifies++;
}
+ }
- fprintf(stderr, "Done.\n");
+ fprintf(stderr, "Done.\n");
- /* close the connection to the database and cleanup */
- PQfinish(conn);
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
- return 0;
+ return 0;
}
</programlisting>
</example>
<programlisting>
/*
* testlibpq3.c
- * Test out-of-line parameters and binary I/O.
+ * Test out-of-line parameters and binary I/O.
*
* Before running this, populate a database with the following commands
* (provided in src/test/examples/testlibpq3.sql):
* t = (11 bytes) 'joe's place'
* b = (5 bytes) \000\001\002\003\004
*
+ * tuple 0: got
+ * i = (4 bytes) 2
+ * t = (8 bytes) 'ho there'
+ * b = (5 bytes) \004\003\002\001\000
*/
#include <stdio.h>
#include <stdlib.h>
static void
exit_nicely(PGconn *conn)
{
- PQfinish(conn);
- exit(1);
+ PQfinish(conn);
+ exit(1);
}
-int
-main(int argc, char **argv)
+/*
+ * This function prints a query result that is a binary-format fetch from
+ * a table defined as in the comment above. We split it out because the
+ * main() function uses it twice.
+ */
+static void
+show_binary_results(PGresult *res)
{
- const char *conninfo;
- PGconn *conn;
- PGresult *res;
- const char *paramValues[1];
- int i,
- j;
- int i_fnum,
- t_fnum,
- b_fnum;
+ int i,
+ j;
+ int i_fnum,
+ t_fnum,
+ b_fnum;
+
+ /* Use PQfnumber to avoid assumptions about field order in result */
+ i_fnum = PQfnumber(res, "i");
+ t_fnum = PQfnumber(res, "t");
+ b_fnum = PQfnumber(res, "b");
+
+ for (i = 0; i < PQntuples(res); i++)
+ {
+ char *iptr;
+ char *tptr;
+ char *bptr;
+ int blen;
+ int ival;
+
+ /* Get the field values (we ignore possibility they are null!) */
+ iptr = PQgetvalue(res, i, i_fnum);
+ tptr = PQgetvalue(res, i, t_fnum);
+ bptr = PQgetvalue(res, i, b_fnum);
/*
- * If the user supplies a parameter on the command line, use it as
- * the conninfo string; otherwise default to setting dbname=template1
- * and using environment variables or defaults for all other connection
- * parameters.
+ * The binary representation of INT4 is in network byte order, which
+ * we'd better coerce to the local byte order.
*/
- if (argc > 1)
- conninfo = argv[1];
- else
- conninfo = "dbname = template1";
-
- /* Make a connection to the database */
- conn = PQconnectdb(conninfo);
-
- /* Check to see that the backend connection was successfully made */
- if (PQstatus(conn) != CONNECTION_OK)
- {
- fprintf(stderr, "Connection to database failed: %s",
- PQerrorMessage(conn));
- exit_nicely(conn);
- }
+ ival = ntohl(*((uint32_t *) iptr));
/*
- * The point of this program is to illustrate use of PQexecParams()
- * with out-of-line parameters, as well as binary transmission of
- * results. By using out-of-line parameters we can avoid a lot of
- * tedious mucking about with quoting and escaping. Notice how we
- * don't have to do anything special with the quote mark in the
- * parameter value.
+ * The binary representation of TEXT is, well, text, and since libpq
+ * was nice enough to append a zero byte to it, it'll work just fine
+ * as a C string.
+ *
+ * The binary representation of BYTEA is a bunch of bytes, which could
+ * include embedded nulls so we have to pay attention to field length.
*/
+ blen = PQgetlength(res, i, b_fnum);
+
+ printf("tuple %d: got\n", i);
+ printf(" i = (%d bytes) %d\n",
+ PQgetlength(res, i, i_fnum), ival);
+ printf(" t = (%d bytes) '%s'\n",
+ PQgetlength(res, i, t_fnum), tptr);
+ printf(" b = (%d bytes) ", blen);
+ for (j = 0; j < blen; j++)
+ printf("\\%03o", bptr[j]);
+ printf("\n\n");
+ }
+}
- /* Here is our out-of-line parameter value */
- paramValues[0] = "joe's place";
-
- res = PQexecParams(conn,
- "SELECT * FROM test1 WHERE t = $1",
- 1, /* one param */
- NULL, /* let the backend deduce param type */
- paramValues,
- NULL, /* don't need param lengths since text */
- NULL, /* default to all text params */
- 1); /* ask for binary results */
-
- if (PQresultStatus(res) != PGRES_TUPLES_OK)
- {
- fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn));
- PQclear(res);
- exit_nicely(conn);
- }
-
- /* Use PQfnumber to avoid assumptions about field order in result */
- i_fnum = PQfnumber(res, "i");
- t_fnum = PQfnumber(res, "t");
- b_fnum = PQfnumber(res, "b");
+int
+main(int argc, char **argv)
+{
+ const char *conninfo;
+ PGconn *conn;
+ PGresult *res;
+ const char *paramValues[1];
+ int paramLengths[1];
+ int paramFormats[1];
+ uint32_t binaryIntVal;
+
+ /*
+ * If the user supplies a parameter on the command line, use it as the
+ * conninfo string; otherwise default to setting dbname=postgres and using
+ * environment variables or defaults for all other connection parameters.
+ */
+ if (argc > 1)
+ conninfo = argv[1];
+ else
+ conninfo = "dbname = postgres";
+
+ /* Make a connection to the database */
+ conn = PQconnectdb(conninfo);
+
+ /* Check to see that the backend connection was successfully made */
+ if (PQstatus(conn) != CONNECTION_OK)
+ {
+ fprintf(stderr, "Connection to database failed: %s",
+ PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ /*
+ * The point of this program is to illustrate use of PQexecParams() with
+ * out-of-line parameters, as well as binary transmission of data.
+ *
+ * This first example transmits the parameters as text, but receives the
+ * results in binary format. By using out-of-line parameters we can
+ * avoid a lot of tedious mucking about with quoting and escaping, even
+ * though the data is text. Notice how we don't have to do anything
+ * special with the quote mark in the parameter value.
+ */
+
+ /* Here is our out-of-line parameter value */
+ paramValues[0] = "joe's place";
+
+ res = PQexecParams(conn,
+ "SELECT * FROM test1 WHERE t = $1",
+ 1, /* one param */
+ NULL, /* let the backend deduce param type */
+ paramValues,
+ NULL, /* don't need param lengths since text */
+ NULL, /* default to all text params */
+ 1); /* ask for binary results */
+
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ show_binary_results(res);
+
+ PQclear(res);
+
+ /*
+ * In this second example we transmit an integer parameter in binary
+ * form, and again retrieve the results in binary form.
+ *
+ * Although we tell PQexecParams we are letting the backend deduce
+ * parameter type, we really force the decision by casting the parameter
+ * symbol in the query text. This is a good safety measure when sending
+ * binary parameters.
+ */
+
+ /* Convert integer value "2" to network byte order */
+ binaryIntVal = htonl((uint32_t) 2);
+
+ /* Set up parameter arrays for PQexecParams */
+ paramValues[0] = (char *) &binaryIntVal;
+ paramLengths[0] = sizeof(binaryIntVal);
+ paramFormats[0] = 1; /* binary */
+
+ res = PQexecParams(conn,
+ "SELECT * FROM test1 WHERE i = $1::int4",
+ 1, /* one param */
+ NULL, /* let the backend deduce param type */
+ paramValues,
+ paramLengths,
+ paramFormats,
+ 1); /* ask for binary results */
+
+ if (PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn));
+ PQclear(res);
+ exit_nicely(conn);
+ }
- for (i = 0; i < PQntuples(res); i++)
- {
- char *iptr;
- char *tptr;
- char *bptr;
- int blen;
- int ival;
-
- /* Get the field values (we ignore possibility they are null!) */
- iptr = PQgetvalue(res, i, i_fnum);
- tptr = PQgetvalue(res, i, t_fnum);
- bptr = PQgetvalue(res, i, b_fnum);
-
- /*
- * The binary representation of INT4 is in network byte order,
- * which we'd better coerce to the local byte order.
- */
- ival = ntohl(*((uint32_t *) iptr));
-
- /*
- * The binary representation of TEXT is, well, text, and since
- * libpq was nice enough to append a zero byte to it, it'll work
- * just fine as a C string.
- *
- * The binary representation of BYTEA is a bunch of bytes, which
- * could include embedded nulls so we have to pay attention to
- * field length.
- */
- blen = PQgetlength(res, i, b_fnum);
-
- printf("tuple %d: got\n", i);
- printf(" i = (%d bytes) %d\n",
- PQgetlength(res, i, i_fnum), ival);
- printf(" t = (%d bytes) '%s'\n",
- PQgetlength(res, i, t_fnum), tptr);
- printf(" b = (%d bytes) ", blen);
- for (j = 0; j < blen; j++)
- printf("\\%03o", bptr[j]);
- printf("\n\n");
- }
+ show_binary_results(res);
- PQclear(res);
+ PQclear(res);
- /* close the connection to the database and cleanup */
- PQfinish(conn);
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
- return 0;
+ return 0;
}
</programlisting>
</example>
</sect1>
</chapter>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode:sgml
-sgml-omittag:nil
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"./reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:("/usr/lib/sgml/catalog")
-sgml-local-ecat-files:nil
-End:
--->
projects / postgresql / blobdiff