mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-21 06:53:23 +02:00
5ed27e35f3
have length words. COPY OUT reimplemented per new protocol: it doesn't need \. anymore, thank goodness. COPY BINARY to/from frontend works, at least as far as the backend is concerned --- libpq's PQgetline API is not up to snuff, and will have to be replaced with something that is null-safe. libpq uses message length words for performance improvement (no cycles wasted rescanning long messages), but not yet for error recovery.
3101 lines
100 KiB
Plaintext
3101 lines
100 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.120 2003/04/22 00:08:06 tgl Exp $
|
|
-->
|
|
|
|
<chapter id="libpq">
|
|
<title><application>libpq</application> - C Library</title>
|
|
|
|
<indexterm zone="libpq">
|
|
<primary>libpq</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
<application>libpq</application> is the <acronym>C</acronym>
|
|
application programmer's interface to
|
|
<productname>PostgreSQL</productname>. <application>libpq</application> is a set
|
|
of library functions that allow client programs to pass queries to the
|
|
<productname>PostgreSQL</productname> backend server and to receive the
|
|
results of these queries. <application>libpq</application> is also the
|
|
underlying engine for several other <productname>PostgreSQL</productname>
|
|
application interfaces, including <application>libpq++</application> (C++),
|
|
<application>libpgtcl</application> (Tcl), <productname>Perl</productname>, and
|
|
<application>ECPG</application>. So some aspects of <application>libpq</>'s behavior will be
|
|
important to you if you use one of those packages.
|
|
</para>
|
|
|
|
<para>
|
|
Three 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> and must link with the
|
|
<application>libpq</application> library.
|
|
</para>
|
|
|
|
<sect1 id="libpq-connect">
|
|
<title>Database Connection Functions</title>
|
|
|
|
<para>
|
|
The following functions deal with making a connection to a
|
|
<productname>PostgreSQL</productname> backend server. An
|
|
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</> 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 little memory even to allocate the
|
|
<structname>PGconn</> object. The <function>PQstatus</> function
|
|
should be called to check whether a connection was successfully
|
|
made before queries are sent via the connection object.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQconnectdb</function></term>
|
|
<listitem>
|
|
<para>
|
|
Makes a new connection to the database server.
|
|
<synopsis>
|
|
PGconn *PQconnectdb(const char *conninfo);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
This function opens a new database connection using the parameters taken
|
|
from the string <literal>conninfo</literal>. Unlike <function>PQsetdbLogin</> below,
|
|
the parameter set can be extended without changing the function signature,
|
|
so use either of this function or the 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>
|
|
|
|
<para>
|
|
The currently recognized parameter key words are:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>host</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Name of host to connect to.
|
|
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>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>hostaddr</literal></term>
|
|
<listitem>
|
|
<para>
|
|
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. If
|
|
a nonzero-length string is specified, TCP/IP communication is
|
|
used.
|
|
</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 is forced. If <literal>hostaddr</> is specified without
|
|
<literal>host</>, the value for <literal>hostaddr</> gives the remote address; if Kerberos is
|
|
used, this causes a reverse name query. 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</>.
|
|
</para>
|
|
<para>
|
|
Without either a host name or host address, <application>libpq</application> will connect using a
|
|
local Unix domain socket.
|
|
</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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>dbname</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The database name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>user</literal></term>
|
|
<listitem>
|
|
<para>
|
|
User name to connect as.
|
|
</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 infinite.
|
|
</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>requiressl</literal></term>
|
|
<listitem>
|
|
<para>
|
|
If set to 1, an <acronym>SSL</acronym> connection to the server is required.
|
|
<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 server.
|
|
This option is only available if
|
|
<productname>PostgreSQL</> is compiled with SSL support.
|
|
</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
|
|
<filename><replaceable>PREFIX</>/share/pg_service.conf.sample</> for
|
|
information on how to set up the file.
|
|
</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 hardwired defaults are used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsetdbLogin</function></term>
|
|
<listitem>
|
|
<para>
|
|
Makes a new connection to the database server.
|
|
<synopsis>
|
|
PGconn *PQsetdbLogin(const char *pghost,
|
|
const char *pgport,
|
|
const char *pgoptions,
|
|
const char *pgtty,
|
|
const char *dbName,
|
|
const char *login,
|
|
const char *pwd);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
This is the predecessor of <function>PQconnectdb</function> with a fixed
|
|
number of parameters. It has the same functionality except that the
|
|
missing parameters cannot be specified in the call.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsetdb</function></term>
|
|
<listitem>
|
|
<para>
|
|
Makes a new connection to the database server.
|
|
<synopsis>
|
|
PGconn *PQsetdb(char *pghost,
|
|
char *pgport,
|
|
char *pgoptions,
|
|
char *pgtty,
|
|
char *dbName);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
This is a macro that calls <function>PQsetdbLogin</function> with null pointers
|
|
for the <parameter>login</> and <parameter>pwd</> parameters. It is provided
|
|
for backward compatibility with very old programs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQconnectStart</function></term>
|
|
<term><function>PQconnectPoll</function></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.
|
|
</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, as 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 for yourself 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. Loop thus: If <function>PQconnectPoll(conn)</function> last returned
|
|
<symbol>PGRES_POLLING_READING</symbol>, perform a <function>select()</> for reading on the socket determined using <function>PQsocket(conn)</function>. If
|
|
it last returned <symbol>PGRES_POLLING_WRITING</symbol>, perform a <function>select()</> for writing on
|
|
that same socket. If you have yet to call <function>PQconnectPoll</function>, i.e., after the call
|
|
to <function>PQconnectStart</function>, behave as if it last returned <symbol>PGRES_POLLING_WRITING</symbol>. If
|
|
<function>select()</> shows that the socket is ready, consider it <quote>active</quote>. If it has
|
|
been decided that this connection is <quote>active</quote>, call <function>PQconnectPoll(conn)</function>
|
|
again. If this call returns <symbol>PGRES_POLLING_FAILED</symbol>, the connection procedure
|
|
has failed. If this call returns <symbol>PGRES_POLLING_OK</symbol>, the connection has been
|
|
successfully made.
|
|
</para>
|
|
|
|
<para>
|
|
Note that the use of <function>select()</function> to ensure that the socket is ready is merely
|
|
a (likely) example; those with other facilities available, such as a
|
|
<function>poll()</function> call, may of course use that instead.
|
|
</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 connection start-up to continue.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>CONNECTION_SETENV</symbol></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Negotiating environment (part of the connection start-up).
|
|
</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 may 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>
|
|
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 a
|
|
call to <function>PQconnectStart</function> or <function>PQconnectPoll</function> failed.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQconnectPoll</function> will currently block if
|
|
<application>libpq</> is compiled with SSL support. This restriction may be removed in the future.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, these functions leave the connection in a nonblocking state as if
|
|
<function>PQsetnonblocking</function> had been called.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQconndefaults</function></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
|
|
key-word 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>
|
|
|
|
<para>
|
|
In <productname>PostgreSQL</productname> versions before 7.0, <function>PQconndefaults</function> returned a pointer
|
|
to a static array, rather than a dynamically allocated array. That
|
|
was not thread-safe, so the behavior has been changed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfinish</function></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 should not be used after <function>PQfinish</function> has been called.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQreset</function></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>PQresetStart</function></term>
|
|
<term><function>PQresetPoll</function></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>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
<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 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.)
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQdb</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the database name of the connection.
|
|
<synopsis>
|
|
char *PQdb(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQdb</> and the next several functions return the values established
|
|
at connection. These values are fixed for the life of the <structname>PGconn</>
|
|
object.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQuser</function></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></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the password of the connection.
|
|
<synopsis>
|
|
char *PQpass(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQhost</function></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></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the port of the connection.
|
|
<synopsis>
|
|
char *PQport(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQtty</function></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></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the command-line options passed in the connection request.
|
|
<synopsis>
|
|
char *PQoptions(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQstatus</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the status of the connection.
|
|
<synopsis>
|
|
ConnStatusType PQstatus(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
The status can be one of a number of values.
|
|
However, only two of these are
|
|
seen outside of an asynchronous connection procedure:
|
|
<literal>CONNECTION_OK</literal> and
|
|
<literal>CONNECTION_BAD</literal>. A good
|
|
connection to the database has the status <literal>CONNECTION_OK</literal>.
|
|
A failed connection
|
|
attempt is signaled by status
|
|
<literal>CONNECTION_BAD</literal>.
|
|
Ordinarily, an OK status will remain so until
|
|
<function>PQfinish</function>, but a
|
|
communications failure might result in the status changing to
|
|
<literal>CONNECTION_BAD</literal> prematurely.
|
|
In that case the application
|
|
could try to recover by calling <function>PQreset</function>.
|
|
</para>
|
|
|
|
<para>
|
|
See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
|
|
to other status codes
|
|
that might be seen.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQerrorMessage</function></term>
|
|
<listitem>
|
|
<para>
|
|
<indexterm><primary>error message</></>
|
|
Returns the error message most recently generated by
|
|
an operation on the connection.
|
|
<synopsis>
|
|
char *PQerrorMessage(const PGconn* conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
Nearly all <application>libpq</> functions will set a message for
|
|
<function>PQerrorMessage</function> if they fail.
|
|
Note that by <application>libpq</application> convention, a nonempty
|
|
<function>PQerrorMessage</function> result will
|
|
include a trailing newline.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsocket</function></term>
|
|
<listitem>
|
|
<para>
|
|
Obtains the file descriptor number of the connection socket to
|
|
the server. A valid descriptor will be greater than or equal
|
|
to 0; a result of -1 indicates that no server connection is
|
|
currently open.
|
|
<synopsis>
|
|
int PQsocket(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQbackendPID</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the process <acronym>ID</acronym> of the backend server process
|
|
handling this connection.
|
|
<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
|
|
notifying backend process). Note that the
|
|
<acronym>PID</acronym> belongs to a process executing on the
|
|
database server host, not the local host!
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQgetssl</function></term>
|
|
<listitem>
|
|
<para>
|
|
<indexterm><primary>SSL</></>
|
|
Returns the SSL structure used in the connection, or null
|
|
if SSL is not in use.
|
|
<synopsis>
|
|
SSL *PQgetssl(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
This structure can be used to verify encryption levels, check
|
|
server certificates, and more. Refer to the <productname>OpenSSL</> documentation
|
|
for information about this structure.
|
|
</para>
|
|
<para>
|
|
You must define <symbol>USE_SSL</symbol> in order to get the
|
|
prototype for this function. Doing this will also
|
|
automatically include <filename>ssl.h</filename> from <productname>OpenSSL</productname>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</sect1>
|
|
|
|
<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>
|
|
|
|
<sect2 id="libpq-exec-main">
|
|
<title>Main Functions</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQexec</function></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 the error.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The <function>PGresult</function> 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.
|
|
If <quote>autocommit</quote> is on, multiple queries sent in a single
|
|
function call are processed in a single transaction.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQresultStatus</function></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>The query successfully executed.</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 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> often
|
|
exposes a bug in the client software.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQresStatus</function></term>
|
|
<listitem>
|
|
<para>
|
|
Converts the enumerated type returned by <function>PQresultStatus</> into
|
|
a string constant describing the status code.
|
|
<synopsis>
|
|
char *PQresStatus(ExecStatusType status);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQresultErrorMessage</function></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>
|
|
</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>PQclear</function></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(PQresult *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 client application.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQmakeEmptyPGresult</function></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>
|
|
</sect2>
|
|
|
|
<sect2 id="libpq-exec-escape-string">
|
|
<title>Escaping Strings for Inclusion in SQL Commands</title>
|
|
|
|
<indexterm zone="libpq-exec-escape-string"><primary>escaping strings</></>
|
|
|
|
<para>
|
|
<function>PQescapeString</function> escapes a string for use within an SQL commmand.
|
|
<synopsis>
|
|
size_t PQescapeString (char *to, const char *from, size_t length);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
If you want to use strings that have been received
|
|
from a source that is not trustworthy (for example, because a random user
|
|
entered them), you should not directly include them in SQL
|
|
commands for security reasons. Instead, you have to escape certain
|
|
characters that are otherwise interpreted specially by the SQL parser.
|
|
<function>PQescapeString</> performs this operation.
|
|
</para>
|
|
<para>
|
|
The parameter <parameter>from</> points to the first character of the string that
|
|
is to be escaped, and the <parameter>length</> parameter counts the
|
|
number of characters in this string. (A terminating zero byte is
|
|
neither necessary nor counted.) <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 part of the result
|
|
string.
|
|
</para>
|
|
<para>
|
|
<function>PQescapeString</> returns the number of characters written
|
|
to <parameter>to</>, not including the terminating zero byte.
|
|
Behavior is undefined when 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>escaping binary strings</primary>
|
|
</indexterm>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQescapeBytea</function></term>
|
|
<listitem>
|
|
<para>
|
|
Escapes binary data for use within an SQL command with the type <type>bytea</type>.
|
|
<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.
|
|
</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 reflects 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.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQescapeBytea</> returns an escaped version of the
|
|
<parameter>from</parameter> parameter binary string in memory
|
|
allocated with <function>malloc()</>, and must be freed using
|
|
<function>PQfreemem()</>.
|
|
The return string has all special characters replaced
|
|
so that they can be properly processed by the PostgreSQL string literal
|
|
parser, and the <type>bytea</type> input function. A terminating zero
|
|
byte is also added. The single quotes that must surround
|
|
PostgreSQL string literals are not part of the result string.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQunescapeBytea</function></term>
|
|
<listitem>
|
|
<para>
|
|
Converts an escaped string representation of binary data into binary
|
|
data --- the reverse of <function>PQescapeBytea</function>.
|
|
<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 memory must be
|
|
freed using <function>PQfreemem()</>.
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfreemem</function></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 Win32, which can not free memory across
|
|
DLL's, unless multithreaded DLL's (/MD in VC6) are used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="libpq-exec-select-info">
|
|
<title>Retrieving Query Result Information</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQntuples</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the number of rows (tuples)
|
|
in the query result.
|
|
<synopsis>
|
|
int PQntuples(const PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQnfields</function></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></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the column name associated with the given column number.
|
|
Column numbers start at 0.
|
|
<synopsis>
|
|
char *PQfname(const PGresult *res,
|
|
int column_number);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfnumber</function></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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQftype</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the column 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 name 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></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the type-specific modification data 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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfsize</function></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 binary representation
|
|
of the data type. -1 is returned if the column has a variable size.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQbinaryTuples</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns 1 if the <structname>PGresult</> contains binary row data
|
|
and 0 if it contains text data.
|
|
<synopsis>
|
|
int PQbinaryTuples(const PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
Currently, binary row data can only be returned by a query that
|
|
extracts data from a binary cursor.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect2>
|
|
|
|
<sect2 id="libpq-exec-select-values">
|
|
<title>Retrieving Query Result Values</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQgetvalue</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns a single column value of one row
|
|
of a <structname>PGresult</structname>.
|
|
Row and colums indices start at 0.
|
|
<synopsis>
|
|
char* PQgetvalue(const PGresult *res,
|
|
int row_number,
|
|
int column_number);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
For most queries, the value returned by <function>PQgetvalue</function>
|
|
is a null-terminated character string representation
|
|
of the column value. But if <function>PQbinaryTuples</function> returns 1,
|
|
the value returned by <function>PQgetvalue</function> is the binary
|
|
representation of the
|
|
type in the internal format of the backend server
|
|
(but not including the size word, if the column is variable-length).
|
|
It is then the programmer's responsibility to cast and
|
|
convert the data to the correct C type.
|
|
</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></term>
|
|
<listitem>
|
|
<para>
|
|
Tests a column 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 column 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
|
|
column.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQgetlength</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the length of a column 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>. Note that for character-represented
|
|
values, this size has little to do with the binary size reported by <function>PQfsize</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQprint</function></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 and this
|
|
function is no longer actively supported.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect2>
|
|
|
|
<sect2 id="libpq-exec-nonselect">
|
|
<title>Retrieving Result Information for Other Commands</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQcmdStatus</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the command status string from the SQL command that
|
|
generated the <structname>PGresult</structname>.
|
|
<synopsis>
|
|
char * PQcmdStatus(PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQcmdTuples</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the number of rows affected by the SQL command.
|
|
<synopsis>
|
|
char * PQcmdTuples(PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
If the <acronym>SQL</acronym> command that generated the
|
|
<structname>PGresult</structname> was <command>INSERT</>, <command>UPDATE</>, or <command>DELETE</command>, this returns a
|
|
string containing the number of rows affected. If the
|
|
command was anything else, it returns the empty string.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQoidValue</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the OID of the inserted row, if the
|
|
<acronym>SQL</acronym> command was an <command>INSERT</command>
|
|
that inserted exactly one row into a table that has OIDs.
|
|
Otherwise, returns <literal>InvalidOid</literal>.
|
|
<synopsis>
|
|
Oid PQoidValue(const PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
The type <type>Oid</type> and the constant
|
|
<literal>InvalidOid</literal> will be defined if you include
|
|
the <application>libpq</application> header file. They will
|
|
both be some integer type.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQoidStatus</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns a string with the OID of the inserted row, if the
|
|
<acronym>SQL</acronym> command was an
|
|
<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>
|
|
and is not thread-safe.
|
|
</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>.
|
|
</para>
|
|
<para>
|
|
Older programs that used this functionality as well as
|
|
<function>PQputline</function> and <function>PQputnbytes</function>
|
|
could block waiting to send data to the server. To
|
|
address that issue, the function <function>PQsetnonblocking</function>
|
|
was added.
|
|
Old applications can neglect to use <function>PQsetnonblocking</function>
|
|
and get the old potentially blocking behavior. Newer programs can use
|
|
<function>PQsetnonblocking</function> to achieve a completely nonblocking
|
|
connection to the server.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQsetnonblocking</function></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 and
|
|
blocking if <parameter>arg</parameter> is 0. Returns 0 if OK, -1 if error.
|
|
</para>
|
|
<para>
|
|
In the nonblocking state, calls to
|
|
<function>PQputline</function>, <function>PQputnbytes</function>,
|
|
<function>PQsendQuery</function>, and <function>PQendcopy</function>
|
|
will not block but instead return an error if they need to be called
|
|
again.
|
|
</para>
|
|
<para>
|
|
When a database connection has been set to nonblocking mode and
|
|
<function>PQexec</function> is called, it will temporarily set the state
|
|
of the connection to blocking until the <function>PQexec</function> call
|
|
completes.
|
|
</para>
|
|
<para>
|
|
More of <application>libpq</application> is expected to be made safe for
|
|
the nonblocking mode in the future.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQisnonblocking</function></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>PQsendQuery</function></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>
|
|
</para>
|
|
|
|
<para>
|
|
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>PQgetResult</function></term>
|
|
<listitem>
|
|
<para>
|
|
Waits for the next result from a prior <function>PQsendQuery</function>,
|
|
and return 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 three more
|
|
functions:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQconsumeInput</function></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 used). 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></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>
|
|
|
|
<varlistentry>
|
|
<term><function>PQflush</function></term>
|
|
<listitem>
|
|
<para>
|
|
Attempts to flush any data queued 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>
|
|
|
|
<para>
|
|
<function>PQflush</function> needs to be called on a nonblocking connection
|
|
before calling <function>select()</function> to determine if a response has
|
|
arrived. If 0 is returned it ensures that there is no data queued to the
|
|
server that has not actually been sent. Only applications that have used
|
|
<function>PQsetnonblocking</function> have a need for this.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
A typical application using these functions will have a main loop that uses
|
|
<function>select()</function> 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>
|
|
Nonblocking connections (that have used <function>PQsetnonblocking</function>)
|
|
should not use <function>select()</function> until <function>PQflush</function>
|
|
has returned 0 indicating that there is no buffered data waiting to be sent
|
|
to the server.
|
|
</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.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQrequestCancel</function></term>
|
|
<listitem>
|
|
<para>
|
|
Requests that the server abandon
|
|
processing of the current command.
|
|
<synopsis>
|
|
int PQrequestCancel(PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
The return value is 1 if the cancel request was successfully
|
|
dispatched and 0 if not. (If not, <function>PQerrorMessage</function> tells why not.)
|
|
Successful dispatch is no guarantee that the request will have any
|
|
effect, however. Regardless of the return value of <function>PQrequestCancel</function>,
|
|
the application must continue with the normal result-reading
|
|
sequence using <function>PQgetResult</function>. 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>
|
|
Note that if the current command is part of a transaction block, cancellation
|
|
will abort the whole transaction.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQrequestCancel</function> can safely be invoked from a signal handler.
|
|
So, it is also possible to use it in conjunction with plain
|
|
<function>PQexec</function>, if the decision to cancel can be made in a signal
|
|
handler. For example, <application>psql</application> invokes
|
|
<function>PQrequestCancel</function> from a <symbol>SIGINT</> signal handler, thus allowing
|
|
interactive cancellation of commands that it issues through <function>PQexec</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-fastpath">
|
|
<title>The Fast-Path Interface</title>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> provides a fast-path interface to send
|
|
function calls to the server. This is a trapdoor into system internals and
|
|
can be a potential security hole. Most users will not need this feature.
|
|
</para>
|
|
|
|
<para>
|
|
The function <function>PQfn</function> 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>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 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
|
|
tells <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 byte string sent by the server is returned
|
|
unmodified.)
|
|
<parameter>args</> and <parameter>nargs</> specify the arguments to be passed to the function.
|
|
</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>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-notify">
|
|
<title>Asynchronous Notification</title>
|
|
|
|
<indexterm zone="libpq-notify"><primary>NOTIFY</primary></indexterm>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> offers asynchronous notification via the
|
|
<command>LISTEN</command> and <command>NOTIFY</command> commands. A server-side 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 command. The arrival of <command>NOTIFY</command>
|
|
messages can subsequently be detected by calling <function>PQnotifies</function>.
|
|
</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 name */
|
|
int be_pid; /* process ID of server process */
|
|
} PGnotify;
|
|
</synopsis>
|
|
After processing a <structname>PGnotify</structname> object returned by <function>PQnotifies</function>,
|
|
be sure to free it with <function>PQfreemem()</function>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
In <productname>PostgreSQL</productname> 6.4 and later,
|
|
the <literal>be_pid</literal> is that of the notifying backend process,
|
|
whereas in earlier versions it was always the <acronym>PID</acronym> of your own backend 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>.
|
|
Therefore, functions are necessary to access this network
|
|
connection directly so applications may take advantage of this capability.
|
|
</para>
|
|
|
|
<para>
|
|
These functions 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>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQgetline</function></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).
|
|
The code in the file
|
|
<filename>src/bin/psql/copy.c</filename>
|
|
contains example functions that correctly handle the <command>COPY</command> protocol.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQgetlineAsync</function></term>
|
|
<listitem>
|
|
<para>
|
|
Reads a row of COPY 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
|
|
COPY, actual parsing of the 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></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 COPY datastream 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> 7.4, 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 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></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></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>
|
|
|
|
<para>
|
|
An example:
|
|
|
|
<programlisting>
|
|
PQexec(conn, "CREATE TABLE foo (a integer, b varchar(16), d double precision);");
|
|
PQexec(conn, "COPY foo FROM STDIN;");
|
|
PQputline(conn, "3\thello world\t4.5\n");
|
|
PQputline(conn, "4\tgoodbye world\t7.11\n");
|
|
...
|
|
PQendcopy(conn);
|
|
</programlisting>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-trace">
|
|
<title>Tracing Functions</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQtrace</function></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></term>
|
|
<listitem>
|
|
<para>
|
|
Disables tracing started by <function>PQtrace</function>.
|
|
<synopsis>
|
|
void PQuntrace(PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-control">
|
|
<title>Notice Processing</title>
|
|
|
|
<para>
|
|
The function <function>PQsetNoticeProcessor</function>
|
|
<indexterm><primary>notice processor</></>
|
|
controls the reporting of notice and warning messages generated by the server.
|
|
<synopsis>
|
|
typedef void (*PQnoticeProcessor) (void *arg, const char *message);
|
|
|
|
PQnoticeProcessor
|
|
PQsetNoticeProcessor(PGconn *conn,
|
|
PQnoticeProcessor proc,
|
|
void *arg);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
By default, <application>libpq</application> prints notice messages
|
|
from the server, as well as a few error messages that it generates by
|
|
itself, on <filename>stderr</filename>.
|
|
This behavior can be overridden by supplying a callback function that
|
|
does something else with the messages, a so-called notice processor.
|
|
The callback function is passed
|
|
the text of the message (which includes 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.)
|
|
The default notice processor is simply
|
|
<programlisting>
|
|
static void
|
|
defaultNoticeProcessor(void * arg, const char * message)
|
|
{
|
|
fprintf(stderr, "%s", message);
|
|
}
|
|
</programlisting>
|
|
To use a special notice processor, call
|
|
<function>PQsetNoticeProcessor</function> just after
|
|
creation of a new <structname>PGconn</> object.
|
|
</para>
|
|
|
|
<para>
|
|
The return value is the pointer to the previous notice processor.
|
|
If you supply a null callback function pointer, no action is taken,
|
|
but the current pointer is returned.
|
|
</para>
|
|
|
|
<para>
|
|
Once you have set a notice 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 processor pointer is 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 variables</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 default 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>PGPORT</envar></primary>
|
|
</indexterm>
|
|
<envar>PGPORT</envar> sets the default 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 default
|
|
<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>
|
|
<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>
|
|
<envar>PGOPTIONS</envar> sets additional run-time options for
|
|
the <productname>PostgreSQL</productname> server.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<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.
|
|
This option is only available if
|
|
<productname>PostgreSQL</> is compiled with SSL support.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<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. This
|
|
option should be set to at least 2 seconds.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
The following environment variables can be used to specify default
|
|
behavior for every <productname>PostgreSQL</productname> session.
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGDATESTYLE</envar>
|
|
sets the default style of date/time representation.
|
|
(Equivalent to <literal>SET datestyle TO ...</literal>.)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGTZ</envar>
|
|
sets the default time zone.
|
|
(Equivalent to <literal>SET timezone TO ...</literal>.)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGCLIENTENCODING</envar>
|
|
sets the default client character set encoding.
|
|
(Equivalent to <literal>SET client_encoding TO ...</literal>.)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<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 <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 these fields may be a literal name or <literal>*</literal>, which
|
|
matches anything. The first matching entry will be used, so put more-specific
|
|
entries first. When an entry contain <literal>:</literal> or
|
|
<literal>\</literal>, it must be escaped 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-threading">
|
|
<title>Threading Behavior</title>
|
|
|
|
<indexterm zone="libpq-threading">
|
|
<primary>threads</primary>
|
|
<secondary>with libpq</secondary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
<application>libpq</application> is thread-safe as of
|
|
<productname>PostgreSQL</productname> 7.0, so long as 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, start up 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>PQoidStatus</function> and
|
|
<function>fe_setauthsvc</function> are not thread-safe and should not be
|
|
used in multithread programs. <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. It is better to use the
|
|
<literal>md5</literal> method, which is thread-safe on all
|
|
platforms.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="libpq-build">
|
|
<title>Building <application>libpq</application> Programs</title>
|
|
|
|
<para>
|
|
To build (i.e., compile and link) your <application>libpq</application> programs you need to
|
|
do all of the following things:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Include the <filename>libpq-fe.h</filename> header file:
|
|
<programlisting>
|
|
#include <libpq-fe.h>
|
|
</programlisting>
|
|
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)
|
|
foo.c:35: `PGresult' undeclared (first use in this function)
|
|
foo.c:54: `CONNECTION_BAD' undeclared (first use in this function)
|
|
foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function)
|
|
foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function)
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Point your compiler to the directory where the <productname>PostgreSQL</> header
|
|
files were installed, by supplying the
|
|
<literal>-I<replaceable>directory</replaceable></literal> option
|
|
to your compiler. (In some cases the compiler will look into
|
|
the directory in question by default, so you can omit this
|
|
option.) For instance, your compile command line could look
|
|
like:
|
|
<programlisting>
|
|
cc -c -I/usr/local/pgsql/include testprog.c
|
|
</programlisting>
|
|
If you are using makefiles then add the option to the
|
|
<varname>CPPFLAGS</varname> variable:
|
|
<programlisting>
|
|
CPPFLAGS += -I/usr/local/pgsql/include
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm><primary>pg_config</></>
|
|
If there is any chance that your program might be compiled by
|
|
other users then you should not hardcode the directory location
|
|
like that. Instead, you can run the utility
|
|
<command>pg_config</command> to find out where the header files
|
|
are on the local system:
|
|
<screen>
|
|
<prompt>$</prompt> pg_config --includedir
|
|
<computeroutput>/usr/local/include</computeroutput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
Failure to specify the correct option to the compiler will
|
|
result in an error message such as
|
|
<screen>
|
|
testlibpq.c:8:22: libpq-fe.h: No such file or directory
|
|
</screen>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
When linking the final program, specify the option
|
|
<literal>-lpq</literal> so that the <application>libpq</application> library gets pulled
|
|
in, as well as the option
|
|
<literal>-L<replaceable>directory</replaceable></literal> to
|
|
point the compiler to the directory where the <application>libpq</application> library resides. (Again, the
|
|
compiler will search some directories by default.) For maximum
|
|
portability, put the <option>-L</option> option before the
|
|
<option>-lpq</option> option. For example:
|
|
<programlisting>
|
|
cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
You can find out the library directory using
|
|
<command>pg_config</command> as well:
|
|
<screen>
|
|
<prompt>$</prompt> pg_config --libdir
|
|
<computeroutput>/usr/local/pgsql/lib</computeroutput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
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'
|
|
testlibpq.o(.text+0x71): undefined reference to `PQstatus'
|
|
testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
|
|
</screen>
|
|
This means you forgot <option>-lpq</option>.
|
|
<screen>
|
|
/usr/bin/ld: cannot find -lpq
|
|
</screen>
|
|
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>
|
|
|
|
|
|
<sect1 id="libpq-example">
|
|
<title>Example Programs</title>
|
|
|
|
<example id="libpq-example-1">
|
|
<title><application>libpq</application> Example Program 1</title>
|
|
|
|
<programlisting>
|
|
/*
|
|
* testlibpq.c
|
|
*
|
|
* Test the C version of libpq, the <productname>PostgreSQL</> frontend
|
|
* library.
|
|
*/
|
|
#include <stdio.h>
|
|
#include <libpq-fe.h>
|
|
|
|
void
|
|
exit_nicely(PGconn *conn)
|
|
{
|
|
PQfinish(conn);
|
|
exit(1);
|
|
}
|
|
|
|
main()
|
|
{
|
|
char *pghost,
|
|
*pgport,
|
|
*pgoptions,
|
|
*pgtty;
|
|
char *dbName;
|
|
int nFields;
|
|
int i,
|
|
j;
|
|
|
|
/* FILE *debug; */
|
|
|
|
PGconn *conn;
|
|
PGresult *res;
|
|
|
|
/*
|
|
* begin, by setting the parameters for a backend connection if the
|
|
* parameters are null, then the system will try to use reasonable
|
|
* defaults by looking up environment variables or, failing that,
|
|
* using hardwired constants
|
|
*/
|
|
pghost = NULL; /* host name of the backend server */
|
|
pgport = NULL; /* port of the backend server */
|
|
pgoptions = NULL; /* special options to start up the backend
|
|
* server */
|
|
pgtty = NULL; /* unused */
|
|
dbName = "template1";
|
|
|
|
/* make a connection to the database */
|
|
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
|
|
|
|
/*
|
|
* check to see that the backend connection was successfully made
|
|
*/
|
|
if (PQstatus(conn) == CONNECTION_BAD)
|
|
{
|
|
fprintf(stderr, "Connection to database '%s' failed.\n", dbName);
|
|
fprintf(stderr, "%s", PQerrorMessage(conn));
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/* debug = fopen("/tmp/trace.out","w"); */
|
|
/* PQtrace(conn, debug); */
|
|
|
|
/* start a transaction block */
|
|
res = PQexec(conn, "BEGIN");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "BEGIN command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/*
|
|
* should PQclear PGresult whenever it is no longer needed to avoid
|
|
* memory leaks
|
|
*/
|
|
PQclear(res);
|
|
|
|
/*
|
|
* fetch rows from the pg_database, the system catalog of
|
|
* databases
|
|
*/
|
|
res = PQexec(conn, "DECLARE mycursor CURSOR FOR SELECT * FROM pg_database");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "DECLARE CURSOR command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
PQclear(res);
|
|
res = PQexec(conn, "FETCH ALL in mycursor");
|
|
if (!res || PQresultStatus(res) != PGRES_TUPLES_OK)
|
|
{
|
|
fprintf(stderr, "FETCH ALL command didn't return tuples properly\n");
|
|
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");
|
|
|
|
/* 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);
|
|
|
|
/* close the cursor */
|
|
res = PQexec(conn, "CLOSE mycursor");
|
|
PQclear(res);
|
|
|
|
/* commit the transaction */
|
|
res = PQexec(conn, "COMMIT");
|
|
PQclear(res);
|
|
|
|
/* close the connection to the database and cleanup */
|
|
PQfinish(conn);
|
|
|
|
/* fclose(debug); */
|
|
return 0;
|
|
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example id="libpq-example-2">
|
|
<title><application>libpq</application> Example Program 2</title>
|
|
|
|
<programlisting>
|
|
/*
|
|
* testlibpq2.c
|
|
* Test of the asynchronous notification interface
|
|
*
|
|
* Start this program, then from psql in another window do
|
|
* NOTIFY TBL2;
|
|
*
|
|
* Or, if you want to get fancy, try this:
|
|
* Populate a database with the following:
|
|
*
|
|
* CREATE TABLE TBL1 (i int4);
|
|
*
|
|
* CREATE TABLE TBL2 (i int4);
|
|
*
|
|
* CREATE RULE r1 AS ON INSERT TO TBL1 DO
|
|
* (INSERT INTO TBL2 values (new.i); NOTIFY TBL2);
|
|
*
|
|
* and do
|
|
*
|
|
* INSERT INTO TBL1 values (10);
|
|
*
|
|
*/
|
|
#include <stdio.h>
|
|
#include "libpq-fe.h"
|
|
|
|
void
|
|
exit_nicely(PGconn *conn)
|
|
{
|
|
PQfinish(conn);
|
|
exit(1);
|
|
}
|
|
|
|
main()
|
|
{
|
|
char *pghost,
|
|
*pgport,
|
|
*pgoptions,
|
|
*pgtty;
|
|
char *dbName;
|
|
int nFields;
|
|
int i,
|
|
j;
|
|
|
|
PGconn *conn;
|
|
PGresult *res;
|
|
PGnotify *notify;
|
|
|
|
/*
|
|
* begin, by setting the parameters for a backend connection if the
|
|
* parameters are null, then the system will try to use reasonable
|
|
* defaults by looking up environment variables or, failing that,
|
|
* using hardwired constants
|
|
*/
|
|
pghost = NULL; /* host name of the backend server */
|
|
pgport = NULL; /* port of the backend server */
|
|
pgoptions = NULL; /* special options to start up the backend
|
|
* server */
|
|
pgtty = NULL; /* unused */
|
|
dbName = getenv("USER"); /* change this to the name of your test
|
|
* database */
|
|
|
|
/* make a connection to the database */
|
|
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
|
|
|
|
/*
|
|
* check to see that the backend connection was successfully made
|
|
*/
|
|
if (PQstatus(conn) == CONNECTION_BAD)
|
|
{
|
|
fprintf(stderr, "Connection to database '%s' failed.\n", dbName);
|
|
fprintf(stderr, "%s", PQerrorMessage(conn));
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
res = PQexec(conn, "LISTEN TBL2");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "LISTEN command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/*
|
|
* should PQclear PGresult whenever it is no longer needed to avoid
|
|
* memory leaks
|
|
*/
|
|
PQclear(res);
|
|
|
|
while (1)
|
|
{
|
|
|
|
/*
|
|
* wait a little bit between checks; waiting with select()
|
|
* would be more efficient.
|
|
*/
|
|
sleep(1);
|
|
/* collect any asynchronous backend messages */
|
|
PQconsumeInput(conn);
|
|
/* check for asynchronous notify messages */
|
|
while ((notify = PQnotifies(conn)) != NULL)
|
|
{
|
|
fprintf(stderr,
|
|
"ASYNC NOTIFY of '%s' from backend pid '%d' received\n",
|
|
notify->relname, notify->be_pid);
|
|
PQfreemem(notify);
|
|
}
|
|
}
|
|
|
|
/* close the connection to the database and cleanup */
|
|
PQfinish(conn);
|
|
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example id="libpq-example-3">
|
|
<title><application>libpq</application> Example Program 3</>
|
|
|
|
<programlisting>
|
|
/*
|
|
* testlibpq3.c Test the C version of Libpq, the <productname>PostgreSQL</> frontend
|
|
* library. tests the binary cursor interface
|
|
*
|
|
*
|
|
*
|
|
* populate a database by doing the following:
|
|
*
|
|
* CREATE TABLE test1 (i int4, d real, p polygon);
|
|
*
|
|
* INSERT INTO test1 values (1, 3.567, polygon '(3.0, 4.0, 1.0, 2.0)');
|
|
*
|
|
* INSERT INTO test1 values (2, 89.05, polygon '(4.0, 3.0, 2.0, 1.0)');
|
|
*
|
|
* the expected output is:
|
|
*
|
|
* tuple 0: got i = (4 bytes) 1, d = (4 bytes) 3.567000, p = (4
|
|
* bytes) 2 points boundbox = (hi=3.000000/4.000000, lo =
|
|
* 1.000000,2.000000) tuple 1: got i = (4 bytes) 2, d = (4 bytes)
|
|
* 89.050003, p = (4 bytes) 2 points boundbox =
|
|
* (hi=4.000000/3.000000, lo = 2.000000,1.000000)
|
|
*
|
|
*
|
|
*/
|
|
#include <stdio.h>
|
|
#include "libpq-fe.h"
|
|
#include "utils/geo_decls.h" /* for the POLYGON type */
|
|
|
|
void
|
|
exit_nicely(PGconn *conn)
|
|
{
|
|
PQfinish(conn);
|
|
exit(1);
|
|
}
|
|
|
|
main()
|
|
{
|
|
char *pghost,
|
|
*pgport,
|
|
*pgoptions,
|
|
*pgtty;
|
|
char *dbName;
|
|
int nFields;
|
|
int i,
|
|
j;
|
|
int i_fnum,
|
|
d_fnum,
|
|
p_fnum;
|
|
PGconn *conn;
|
|
PGresult *res;
|
|
|
|
/*
|
|
* begin, by setting the parameters for a backend connection if the
|
|
* parameters are null, then the system will try to use reasonable
|
|
* defaults by looking up environment variables or, failing that,
|
|
* using hardwired constants
|
|
*/
|
|
pghost = NULL; /* host name of the backend server */
|
|
pgport = NULL; /* port of the backend server */
|
|
pgoptions = NULL; /* special options to start up the backend
|
|
* server */
|
|
pgtty = NULL; /* unused */
|
|
|
|
dbName = getenv("USER"); /* change this to the name of your test
|
|
* database */
|
|
|
|
/* make a connection to the database */
|
|
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
|
|
|
|
/*
|
|
* check to see that the backend connection was successfully made
|
|
*/
|
|
if (PQstatus(conn) == CONNECTION_BAD)
|
|
{
|
|
fprintf(stderr, "Connection to database '%s' failed.\n", dbName);
|
|
fprintf(stderr, "%s", PQerrorMessage(conn));
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/* start a transaction block */
|
|
res = PQexec(conn, "BEGIN");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "BEGIN command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/*
|
|
* should PQclear PGresult whenever it is no longer needed to avoid
|
|
* memory leaks
|
|
*/
|
|
PQclear(res);
|
|
|
|
/*
|
|
* fetch rows from the pg_database, the system catalog of
|
|
* databases
|
|
*/
|
|
res = PQexec(conn, "DECLARE mycursor BINARY CURSOR FOR SELECT * FROM test1");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "DECLARE CURSOR command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
PQclear(res);
|
|
|
|
res = PQexec(conn, "FETCH ALL in mycursor");
|
|
if (!res || PQresultStatus(res) != PGRES_TUPLES_OK)
|
|
{
|
|
fprintf(stderr, "FETCH ALL command didn't return tuples properly\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
i_fnum = PQfnumber(res, "i");
|
|
d_fnum = PQfnumber(res, "d");
|
|
p_fnum = PQfnumber(res, "p");
|
|
|
|
for (i = 0; i < 3; i++)
|
|
{
|
|
printf("type[%d] = %d, size[%d] = %d\n",
|
|
i, PQftype(res, i),
|
|
i, PQfsize(res, i));
|
|
}
|
|
for (i = 0; i < PQntuples(res); i++)
|
|
{
|
|
int *ival;
|
|
float *dval;
|
|
int plen;
|
|
POLYGON *pval;
|
|
|
|
/* we hard-wire this to the 3 fields we know about */
|
|
ival = (int *) PQgetvalue(res, i, i_fnum);
|
|
dval = (float *) PQgetvalue(res, i, d_fnum);
|
|
plen = PQgetlength(res, i, p_fnum);
|
|
|
|
/*
|
|
* plen doesn't include the length field so need to
|
|
* increment by VARHDSZ
|
|
*/
|
|
pval = (POLYGON *) malloc(plen + VARHDRSZ);
|
|
pval->size = plen;
|
|
memmove((char *) &pval->npts, PQgetvalue(res, i, p_fnum), plen);
|
|
printf("tuple %d: got\n", i);
|
|
printf(" i = (%d bytes) %d,\n",
|
|
PQgetlength(res, i, i_fnum), *ival);
|
|
printf(" d = (%d bytes) %f,\n",
|
|
PQgetlength(res, i, d_fnum), *dval);
|
|
printf(" p = (%d bytes) %d points \tboundbox = (hi=%f/%f, lo = %f,%f)\n",
|
|
PQgetlength(res, i, d_fnum),
|
|
pval->npts,
|
|
pval->boundbox.xh,
|
|
pval->boundbox.yh,
|
|
pval->boundbox.xl,
|
|
pval->boundbox.yl);
|
|
}
|
|
PQclear(res);
|
|
|
|
/* close the cursor */
|
|
res = PQexec(conn, "CLOSE mycursor");
|
|
PQclear(res);
|
|
|
|
/* commit the transaction */
|
|
res = PQexec(conn, "COMMIT");
|
|
PQclear(res);
|
|
|
|
/* close the connection to the database and cleanup */
|
|
PQfinish(conn);
|
|
|
|
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:
|
|
-->
|