|
|
|
|
@ -1,5 +1,5 @@ |
|
|
|
|
<!-- |
|
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.74 2001/10/31 20:39:30 petere Exp $ |
|
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.75 2001/11/12 19:19:39 petere Exp $ |
|
|
|
|
--> |
|
|
|
|
|
|
|
|
|
<chapter id="libpq"> |
|
|
|
|
@ -70,7 +70,7 @@ PGconn *PQconnectdb(const char *conninfo) |
|
|
|
|
This routine 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 routine or the non-blocking analogues <function>PQconnectStart</> |
|
|
|
|
so use either of this routine or the nonblocking analogues <function>PQconnectStart</> |
|
|
|
|
and <function>PQconnectPoll</function> is preferred for application programming. The passed string |
|
|
|
|
can be empty to use all default parameters, or it can contain one or more |
|
|
|
|
parameter settings separated by whitespace. |
|
|
|
|
@ -106,7 +106,7 @@ PGconn *PQconnectdb(const char *conninfo) |
|
|
|
|
<para> |
|
|
|
|
IP address of host to connect to. This should be in standard |
|
|
|
|
numbers-and-dots form, as used by the BSD functions <function>inet_aton</> et al. If |
|
|
|
|
a non-zero-length string is specified, TCP/IP communication is used. |
|
|
|
|
a nonzero-length string is specified, TCP/IP communication is used. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
Using <literal>hostaddr</> instead of host allows the application to avoid a host |
|
|
|
|
@ -244,7 +244,8 @@ PGconn *PQsetdb(char *pghost, |
|
|
|
|
<para> |
|
|
|
|
<function>PQconnectStart</function>, |
|
|
|
|
<function>PQconnectPoll</function> |
|
|
|
|
Make a connection to the database server in a non-blocking manner. |
|
|
|
|
<indexterm><primary>nonblocking connection</primary></indexterm> |
|
|
|
|
Make a connection to the database server in a nonblocking manner. |
|
|
|
|
<synopsis> |
|
|
|
|
PGconn *PQconnectStart(const char *conninfo) |
|
|
|
|
</synopsis> |
|
|
|
|
@ -289,7 +290,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn) |
|
|
|
|
</para> |
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
|
To begin, call <literal>conn=PQconnectStart("<connection_info_string>")</literal>. |
|
|
|
|
To begin, 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 |
|
|
|
|
@ -413,7 +414,7 @@ switch(PQstatus(conn)) |
|
|
|
|
</para> |
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
|
These functions leave the socket in a non-blocking state as if |
|
|
|
|
These functions leave the socket in a nonblocking state as if |
|
|
|
|
<function>PQsetnonblocking</function> had been called. |
|
|
|
|
</para> |
|
|
|
|
</listitem> |
|
|
|
|
@ -495,7 +496,7 @@ void PQreset(PGconn *conn) |
|
|
|
|
<para> |
|
|
|
|
<function>PQresetStart</function> |
|
|
|
|
<function>PQresetPoll</function> |
|
|
|
|
Reset the communication port with the backend, in a non-blocking manner. |
|
|
|
|
Reset the communication port with the backend, in a nonblocking manner. |
|
|
|
|
<synopsis> |
|
|
|
|
int PQresetStart(PGconn *conn); |
|
|
|
|
</synopsis> |
|
|
|
|
@ -506,7 +507,7 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); |
|
|
|
|
reestablish a new connection to the same postmaster, 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 non-blocking manner. These functions suffer from the same |
|
|
|
|
act in a nonblocking manner. These functions suffer from the same |
|
|
|
|
restrictions as <function>PQconnectStart</> and <function>PQconnectPoll</>. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
@ -520,6 +521,8 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn); |
|
|
|
|
</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 |
|
|
|
|
@ -529,6 +532,7 @@ definition of struct <structname>PGconn</structname> is not even provided in <fi |
|
|
|
|
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.) |
|
|
|
|
|
|
|
|
|
<itemizedlist> |
|
|
|
|
<listitem> |
|
|
|
|
<para> |
|
|
|
|
@ -640,6 +644,7 @@ ConnStatusType PQstatus(const PGconn *conn) |
|
|
|
|
<listitem> |
|
|
|
|
<para> |
|
|
|
|
<function>PQerrorMessage</function> |
|
|
|
|
<indexterm><primary>error message</></> |
|
|
|
|
Returns the error message most recently generated by |
|
|
|
|
an operation on the connection. |
|
|
|
|
<synopsis> |
|
|
|
|
@ -677,6 +682,7 @@ int PQbackendPID(const PGconn *conn); |
|
|
|
|
<listitem> |
|
|
|
|
<para> |
|
|
|
|
<function>PQgetssl</function> |
|
|
|
|
<indexterm><primary>SSL</></> |
|
|
|
|
Returns the SSL structure used in the connection, or NULL |
|
|
|
|
if SSL is not in use. |
|
|
|
|
<synopsis> |
|
|
|
|
@ -858,30 +864,33 @@ as with a <structname>PGresult</structname> returned by <application>libpq</appl |
|
|
|
|
|
|
|
|
|
<sect2 id="libpq-exec-escape-string"> |
|
|
|
|
<title>Escaping strings for inclusion in SQL queries</title> |
|
|
|
|
|
|
|
|
|
<indexterm zone="libpq-exec-escape-string"><primary>escaping strings</></> |
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
|
<function>PQescapeString</function> |
|
|
|
|
Escapes a string for use within an SQL query. |
|
|
|
|
<synopsis> |
|
|
|
|
size_t PQescapeString (char *to, const char *from, size_t length); |
|
|
|
|
</synopsis> |
|
|
|
|
If you want to include strings which have been received |
|
|
|
|
from a source which is not trustworthy (for example, because they were |
|
|
|
|
If you want to include strings that have been received |
|
|
|
|
from a source that is not trustworthy (for example, because they were |
|
|
|
|
transmitted across a network), you cannot directly include them in SQL |
|
|
|
|
queries for security reasons. Instead, you have to quote special |
|
|
|
|
characters which are otherwise interpreted by the SQL parser. |
|
|
|
|
characters that are otherwise interpreted by the SQL parser. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
<function>PQescapeString</> performs this operation. The |
|
|
|
|
<parameter>from</> points to the first character of the string which |
|
|
|
|
<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 NUL character is |
|
|
|
|
neither necessary nor counted). <parameter>to</> shall point to a |
|
|
|
|
buffer which is able to hold at least one more character than twice |
|
|
|
|
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 NUL character. The single quotes which |
|
|
|
|
harm, and adding a terminating NUL character. The single quotes that |
|
|
|
|
must surround PostgreSQL string literals are not part of the result |
|
|
|
|
string. |
|
|
|
|
</para> |
|
|
|
|
@ -1175,6 +1184,8 @@ and is not thread-safe. |
|
|
|
|
<sect1 id="libpq-async"> |
|
|
|
|
<title>Asynchronous Query Processing</title> |
|
|
|
|
|
|
|
|
|
<indexterm zone="libpq-async"><primary>nonblocking connection</></> |
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
|
The <function>PQexec</function> function is adequate for submitting queries in |
|
|
|
|
simple synchronous |
|
|
|
|
@ -1220,7 +1231,7 @@ was added. |
|
|
|
|
<para> |
|
|
|
|
Old applications can neglect to use <function>PQsetnonblocking</function> |
|
|
|
|
and get the older potentially blocking behavior. Newer programs can use |
|
|
|
|
<function>PQsetnonblocking</function> to achieve a completely non-blocking |
|
|
|
|
<function>PQsetnonblocking</function> to achieve a completely nonblocking |
|
|
|
|
connection to the backend. |
|
|
|
|
|
|
|
|
|
<itemizedlist> |
|
|
|
|
@ -1260,7 +1271,7 @@ int PQsetnonblocking(PGconn *conn, int arg) |
|
|
|
|
<synopsis> |
|
|
|
|
int PQisnonblocking(const PGconn *conn) |
|
|
|
|
</synopsis> |
|
|
|
|
Returns 1 if the connection is set to non-blocking mode, |
|
|
|
|
Returns 1 if the connection is set to nonblocking mode, |
|
|
|
|
0 if blocking. |
|
|
|
|
</para> |
|
|
|
|
</listitem> |
|
|
|
|
@ -1368,7 +1379,7 @@ some reason. |
|
|
|
|
<synopsis> |
|
|
|
|
int PQflush(PGconn *conn); |
|
|
|
|
</synopsis> |
|
|
|
|
<function>PQflush</function> needs to be called on a non-blocking connection |
|
|
|
|
<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 |
|
|
|
|
backend that has not actually been sent. Only applications that have used |
|
|
|
|
@ -1395,7 +1406,7 @@ data; after which, <function>PQisBusy</function>, <function>PQgetResult</functio |
|
|
|
|
and/or <function>PQnotifies</function> can be used to process the response. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
Non-blocking connections (that have used <function>PQsetnonblocking</function>) |
|
|
|
|
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 backend. |
|
|
|
|
@ -1525,6 +1536,8 @@ typedef struct { |
|
|
|
|
<sect1 id="libpq-notify"> |
|
|
|
|
<title>Asynchronous Notification</title> |
|
|
|
|
|
|
|
|
|
<indexterm zone="libpq-notify"><primary>NOTIFY</primary></indexterm> |
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
|
<productname>PostgreSQL</productname> supports asynchronous notification via the |
|
|
|
|
<command>LISTEN</command> and <command>NOTIFY</command> commands. A backend registers its interest in a particular |
|
|
|
|
@ -1828,14 +1841,14 @@ void PQuntrace(PGconn *conn) |
|
|
|
|
</sect1> |
|
|
|
|
|
|
|
|
|
<sect1 id="libpq-control"> |
|
|
|
|
<title> |
|
|
|
|
<application>libpq</application> Control Functions</title> |
|
|
|
|
<title><application>libpq</application> Control Functions</title> |
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
|
<itemizedlist> |
|
|
|
|
<listitem> |
|
|
|
|
<para> |
|
|
|
|
<function>PQsetNoticeProcessor</function> |
|
|
|
|
<indexterm><primary>notice processor</></> |
|
|
|
|
Control reporting of notice and warning messages generated by libpq. |
|
|
|
|
<synopsis> |
|
|
|
|
typedef void (*PQnoticeProcessor) (void *arg, const char *message); |
|
|
|
|
@ -2106,6 +2119,7 @@ CPPFLAGS += -I/usr/local/pgsql/include |
|
|
|
|
</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 |
|
|
|
|
@ -2171,6 +2185,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' |
|
|
|
|
</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 PostgreSQL 7.2, this file will be found in |
|
|
|
|
|
Peter Eisentraut
24 years ago