11<!--
2- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.145 2004/01/09 02:02:43 momjian Exp $
2+ $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.146 2004/01/26 22:13:21 neilc Exp $
33-->
44
55 <chapter id="libpq">
@@ -903,7 +903,7 @@ only protocol 2.0. (Protocol 1.0 is obsolete and not supported by <application>
903903 Returns the error message most recently generated by
904904 an operation on the connection.
905905<synopsis>
906- char *PQerrorMessage(const PGconn* conn);
906+ char *PQerrorMessage(const PGconn * conn);
907907</synopsis>
908908 </para>
909909
@@ -912,7 +912,9 @@ char *PQerrorMessage(const PGconn* conn);
912912 <function>PQerrorMessage</function> if they fail.
913913 Note that by <application>libpq</application> convention, a nonempty
914914 <function>PQerrorMessage</function> result will
915- include a trailing newline.
915+ include a trailing newline. The caller should not free the result
916+ directly. It will be freed when the associated <structname>PGconn</>
917+ handle is passed to <function>PQfinish</function>.
916918 </para>
917919 </listitem>
918920 </varlistentry>
@@ -1262,7 +1264,8 @@ processor (see <xref linkend="libpq-notice-processing">).
12621264<listitem>
12631265<para>
12641266 Converts the enumerated type returned by <function>PQresultStatus</> into
1265- a string constant describing the status code.
1267+ a string constant describing the status code. The caller should not
1268+ free the result.
12661269<synopsis>
12671270char *PQresStatus(ExecStatusType status);
12681271</synopsis>
@@ -1279,7 +1282,10 @@ if there was no error.
12791282<synopsis>
12801283char *PQresultErrorMessage(const PGresult *res);
12811284</synopsis>
1282- If there was an error, the returned string will include a trailing newline.
1285+ If there was an error, the returned string will include a trailing newline.
1286+ The caller should not free the result directly. It will be freed when the
1287+ associated <structname>PGresult</> handle is passed to
1288+ <function>PQclear</function>.
12831289</para>
12841290
12851291<para>
@@ -1307,7 +1313,10 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
13071313listed below. <symbol>NULL</symbol> is returned if the
13081314<structname>PGresult</structname> is not an error or warning result,
13091315or does not include the specified field. Field values will normally
1310- not include a trailing newline.
1316+ not include a trailing newline. The caller should not free the
1317+ result directly. It will be freed when the
1318+ associated <structname>PGresult</> handle is passed to
1319+ <function>PQclear</function>.
13111320</para>
13121321
13131322<para>
@@ -1535,8 +1544,10 @@ int PQnfields(const PGresult *res);
15351544<term><function>PQfname</function><indexterm><primary>PQfname</></></term>
15361545<listitem>
15371546<para>
1538- Returns the column name associated with the given column number.
1539- Column numbers start at 0.
1547+ Returns the column name associated with the given column number.
1548+ Column numbers start at 0. The caller should not free the result
1549+ directly. It will be freed when the associated <structname>PGresult</>
1550+ handle is passed to <function>PQclear</function>.
15401551<synopsis>
15411552char *PQfname(const PGresult *res,
15421553 int column_number);
@@ -1566,8 +1577,8 @@ int PQfnumber(const PGresult *res,
15661577
15671578<para>
15681579 The given name is treated like an identifier in an SQL command,
1569-
1570-
1580+
1581+
15711582<programlisting>
15721583select 1 as FOO, 2 as "BAR";
15731584</programlisting>
@@ -1747,11 +1758,14 @@ returns 1 only if all columns of the result are binary (format 1).
17471758<term><function>PQgetvalue</function><indexterm><primary>PQgetvalue</></></term>
17481759<listitem>
17491760<para>
1750- Returns a single field value of one row
1751- of a <structname>PGresult</structname>.
1752- Row and column numbers start at 0.
1761+ Returns a single field value of one row of a
1762+ <structname>PGresult</structname>. Row and column numbers
1763+ start at 0. The caller should not free the result
1764+ directly. It will be freed when the associated
1765+ <structname>PGresult</> handle is passed to
1766+ <function>PQclear</function>.
17531767<synopsis>
1754- char* PQgetvalue(const PGresult *res,
1768+ char * PQgetvalue(const PGresult *res,
17551769 int row_number,
17561770 int column_number);
17571771</synopsis>
@@ -1880,12 +1894,15 @@ results.
18801894 Returns the command status tag from the SQL command that
18811895 generated the <structname>PGresult</structname>.
18821896<synopsis>
1883- char *
1897+ char *PQcmdStatus(PGresult *res);
18841898</synopsis>
18851899</para>
18861900<para>
18871901Commonly this is just the name of the command, but it may include additional
1888- data such as the number of rows processed.
1902+ data such as the number of rows processed. The caller should
1903+ not free the result directly. It will be freed when the
1904+ associated <structname>PGresult</> handle is passed to
1905+ <function>PQclear</function>.
18891906</para>
18901907</listitem>
18911908</varlistentry>
@@ -1896,7 +1913,7 @@ data such as the number of rows processed.
18961913<para>
18971914 Returns the number of rows affected by the SQL command.
18981915<synopsis>
1899- char *
1916+ char *PQcmdTuples(PGresult *res);
19001917</synopsis>
19011918</para>
19021919
@@ -1906,7 +1923,10 @@ char * PQcmdTuples(PGresult *res);
19061923 <command>UPDATE</>, <command>DELETE</command>, <command>MOVE</>,
19071924 or <command>FETCH</>, this returns a
19081925 string containing the number of rows affected. If the
1909- command was anything else, it returns the empty string.
1926+ command was anything else, it returns the empty string. The
1927+ caller should not free the result directly. It will be freed
1928+ when the associated <structname>PGresult</> handle is passed to
1929+ <function>PQclear</function>.
19101930</para>
19111931</listitem>
19121932</varlistentry>
@@ -1940,7 +1960,7 @@ Oid PQoidValue(const PGresult *res);
19401960 OIDs.) If the command was not an <command>INSERT</command>,
19411961 returns an empty string.
19421962<synopsis>
1943- char *
1963+ char *PQoidStatus(const PGresult *res);
19441964</synopsis>
19451965</para>
19461966
@@ -2522,7 +2542,7 @@ parameters and results substitutes for a fast-path function call.
25222542The function <function>PQfn</function><indexterm><primary>PQfn</></>
25232543requests execution of a server function via the fast-path interface:
25242544<synopsis>
2525- PGresult* PQfn(PGconn* conn,
2545+ PGresult * PQfn(PGconn * conn,
25262546 int fnid,
25272547 int *result_buf,
25282548 int *result_len,
@@ -2620,7 +2640,7 @@ The function <function>PQnotifies</function>
26202640 returned from <function>PQnotifies</>, it is considered handled and will be
26212641 removed from the list of notifications.
26222642<synopsis>
2623- PGnotify* PQnotifies(PGconn *conn);
2643+ PGnotify * PQnotifies(PGconn *conn);
26242644
26252645typedef struct pgNotify {
26262646 char *relname; /* notification condition name */
@@ -3291,7 +3311,7 @@ a void pointer that is the same one passed to
32913311The default notice processor is simply
32923312<programlisting>
32933313static void
3294- defaultNoticeProcessor(void *
3314+ defaultNoticeProcessor(void *arg, const char *message)
32953315{
32963316 fprintf(stderr, "%s", message);
32973317}
