Le 26/01/2010 19:43, Joe Conway a écrit :
> On 01/25/2010 03:21 PM, Guillaume Lelarge wrote:
>> I didn't put any documentation before knowing which one will be choosen.
>> So we still need to work on the manual.
>
> Please send the documentation as a separate patch. Once I have that I
> will commit the posted patch, barring any objections in the meantime.
>
You'll find it attached with this mail. Please read it carefully, my
written english is not that good.
Thanks.
--
Guillaume.
http://www.postgresqlfr.org
http://dalibo.com
Index: doc/src/sgml/libpq.sgml
===================================================================
RCS file: /opt/cvsroot_postgresql/pgsql/doc/src/sgml/libpq.sgml,v
retrieving revision 1.295
diff -c -p -c -r1.295 libpq.sgml
*** doc/src/sgml/libpq.sgml 21 Jan 2010 14:58:52 -0000 1.295
--- doc/src/sgml/libpq.sgml 26 Jan 2010 22:52:52 -0000
***************
*** 56,62 ****
one time. (One reason to do that is to access more than one
database.) Each connection is represented by a
<structname>PGconn</><indexterm><primary>PGconn</></> object, which
! is obtained from the function <function>PQconnectdb</> or
<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.
--- 56,63 ----
one time. (One reason to do that is to access more than one
database.) Each connection is represented by a
<structname>PGconn</><indexterm><primary>PGconn</></> object, which
! is obtained from the function <function>PQconnectdb</>,
! <function>PQconnectdbParams</> or
<function>PQsetdbLogin</>. Note that these functions will always
return a non-null object pointer, unless perhaps there is too
little memory even to allocate the <structname>PGconn</> object.
***************
*** 91,125 ****
<variablelist>
<varlistentry>
! <term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></term>
<listitem>
<para>
Makes a new connection to the database server.
<synopsis>
! PGconn *PQconnectdb(const char *conninfo);
</synopsis>
</para>
<para>
This function opens a new database connection using the parameters taken
! from the string <literal>conninfo</literal>. Unlike <function>PQsetdbLogin</> below,
the parameter set can be extended without changing the function signature,
! so use of this function (or its nonblocking analogues <function>PQconnectStart</>
and <function>PQconnectPoll</function>) is preferred for new application programming.
</para>
<para>
! The passed string
! can be empty to use all default parameters, or it can contain one or more
! parameter settings separated by whitespace.
! Each parameter setting is in the form <literal>keyword = value</literal>.
! Spaces around the equal sign are optional.
! To write an empty value or a value containing
! spaces, surround it with single quotes, e.g.,
! <literal>keyword = 'a value'</literal>.
! Single quotes and backslashes within the value must be escaped with a
! backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
</para>
<para>
--- 92,121 ----
<variablelist>
<varlistentry>
! <term><function>PQconnectdbParams</function><indexterm><primary>PQconnectdbParams</></></term>
<listitem>
<para>
Makes a new connection to the database server.
<synopsis>
! PGconn *PQconnectdbParams(const char **keywords, const char **values);
</synopsis>
</para>
<para>
This function opens a new database connection using the parameters taken
! from two arrays. The first one, <literal>keywords</literal>, is defined
! as an array of strings, each one being a keyword. The second one,
! <literal>values</literal>, gives the value for each keyword. Unlike
! <function>PQsetdbLogin</> below,
the parameter set can be extended without changing the function signature,
! so use of this function (or its nonblocking analogues <function>PQconnectStartParams</>
and <function>PQconnectPoll</function>) is preferred for new application programming.
</para>
<para>
! The passed arrays can be empty to use all default parameters, or it can
! contain one or more parameter settings.
</para>
<para>
***************
*** 478,483 ****
--- 474,518 ----
</varlistentry>
<varlistentry>
+ <term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></term>
+ <listitem>
+ <para>
+ Makes a new connection to the database server.
+
+ <synopsis>
+ PGconn *PQconnectdb(const char *conninfo);
+ </synopsis>
+ </para>
+
+ <para>
+ This function opens a new database connection using the parameters taken
+ from the string <literal>conninfo</literal>.
+ </para>
+
+ <para>
+ The passed string
+ can be empty to use all default parameters, or it can contain one or more
+ parameter settings separated by whitespace.
+ Each parameter setting is in the form <literal>keyword = value</literal>.
+ Spaces around the equal sign are optional.
+ To write an empty value or a value containing
+ spaces, surround it with single quotes, e.g.,
+ <literal>keyword = 'a value'</literal>.
+ Single quotes and backslashes within the value must be escaped with a
+ backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
+ </para>
+
+ <para>
+ The currently recognized parameter key words are available above.
+ If any parameter is unspecified, then the corresponding
+ environment variable (see <xref linkend="libpq-envars">)
+ is checked. If the environment variable is not set either,
+ then the indicated built-in defaults are used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></term>
<listitem>
<para>
*************** PGconn *PQsetdb(char *pghost,
*** 532,537 ****
--- 567,573 ----
</varlistentry>
<varlistentry>
+ <term><function>PQconnectStartParams</function><indexterm><primary>PQconnectStartParams</></></term>
<term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</></></term>
<term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</></></term>
<listitem>
*************** PGconn *PQsetdb(char *pghost,
*** 540,545 ****
--- 576,585 ----
Make a connection to the database server in a nonblocking manner.
<synopsis>
+ PGconn *PQconnectStartParams(const char **keywords, const char **values);
+ </synopsis>
+
+ <synopsis>
PGconn *PQconnectStart(const char *conninfo);
</synopsis>
*************** PGconn *PQsetdb(char *pghost,
*** 549,577 ****
</para>
<para>
! These two functions are used to open a connection to a database server such
that your application's thread of execution is not blocked on remote I/O
whilst doing so.
The point of this approach is that the waits for I/O to complete can occur
in the application's main loop, rather than down inside
! <function>PQconnectdb</>, and so the application can manage this
! operation in parallel with other activities.
</para>
<para>
The database connection is made using the parameters taken from the string
! <literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
! the same format as described above for <function>PQconnectdb</function>.
</para>
<para>
! Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
restrictions are met:
<itemizedlist>
<listitem>
<para>
The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
name and reverse name queries are not made. See the documentation of
! these parameters under <function>PQconnectdb</function> above for details.
</para>
</listitem>
--- 589,626 ----
</para>
<para>
! These three functions are used to open a connection to a database server such
that your application's thread of execution is not blocked on remote I/O
whilst doing so.
The point of this approach is that the waits for I/O to complete can occur
in the application's main loop, rather than down inside
! <function>PQconnectdbParams</> or <function>PQconnectdb</>, and so the
! application can manage this operation in parallel with other activities.
</para>
<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>
+ The database connection can also be made using the parameters taken from
+ the <literal>keywords</literal> and <literal>values</literal> arrays,
+ this time passed to <function>PQconnectStartParams</function>.
+ </para>
+
<para>
! Neither <function>PQconnectStartParams</function> nor <function>PQconnectStart</function>
! nor <function>PQconnectPoll</function> will block, so long as a number of
restrictions are met:
<itemizedlist>
<listitem>
<para>
The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
name and reverse name queries are not made. See the documentation of
! these parameters under <function>PQconnectdbParams</function> above for details.
</para>
</listitem>
*************** PQconninfoOption *PQconninfoParse(const
*** 883,889 ****
parameters previously used. This can be useful for error recovery if a
working connection is lost. They differ from <function>PQreset</function> (above) in that they
act in a nonblocking manner. These functions suffer from the same
! restrictions as <function>PQconnectStart</> and <function>PQconnectPoll</>.
</para>
<para>
--- 932,939 ----
parameters previously used. This can be useful for error recovery if a
working connection is lost. They differ from <function>PQreset</function> (above) in that they
act in a nonblocking manner. These functions suffer from the same
! restrictions as <function>PQconnectStartParams</>, <function>PQconnectStart</>
! and <function>PQconnectPoll</>.
</para>
<para>
*************** PQconninfoOption *PQconninfoParse(const
*** 1096,1104 ****
</para>
<para>
! See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
! to other status codes
! that might be seen.
</para>
</listitem>
</varlistentry>
--- 1146,1154 ----
</para>
<para>
! See the entry for <function>PQconnectStartParams</>, <function>PQconnectStart</>
! and <function>PQconnectPoll</> with regards to other status codes that
! might be seen.
</para>
</listitem>
</varlistentry>
--
Sent via pgsql-hackers mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
