The attached patch clarifies (or, rather, makes explicit) to readers how
to handle memory management for char pointers returned by libpq functions.
Although the sections on PQfinish(), PQclear() and PQfreemem() give an
indication that all pointers returned by functions point to memory
allocated in the underlying library, I thought it would be useful to make
this clear.
Gavin
Index: doc/src/sgml/libpq.sgml
===================================================================
RCS file: /usr/local/cvsroot/pgsql-server/doc/src/sgml/libpq.sgml,v
retrieving revision 1.145
diff -2 -c -r1.145 libpq.sgml
*** doc/src/sgml/libpq.sgml 9 Jan 2004 02:02:43 -0000 1.145
--- doc/src/sgml/libpq.sgml 26 Jan 2004 05:15:18 -0000
***************
*** 913,917 ****
Note that by <application>libpq</application> convention, a nonempty
<function>PQerrorMessage</function> result will
! include a trailing newline.
</para>
</listitem>
--- 913,920 ----
Note that by <application>libpq</application> convention, a nonempty
<function>PQerrorMessage</function> result will
! include a trailing newline. The caller should not free the result
! directly. It will be freed when the associated <structname>PGconn</>
! handle is passed to <function>PQfinish</function>.
!
</para>
</listitem>
***************
*** 1263,1267 ****
<para>
Converts the enumerated type returned by <function>PQresultStatus</> into
! a string constant describing the status code.
<synopsis>
char *PQresStatus(ExecStatusType status);
--- 1266,1271 ----
<para>
Converts the enumerated type returned by <function>PQresultStatus</> into
! a string constant describing the status code. The caller should not
! free the result.
<synopsis>
char *PQresStatus(ExecStatusType status);
***************
*** 1280,1284 ****
char *PQresultErrorMessage(const PGresult *res);
</synopsis>
! If there was an error, the returned string will include a trailing newline.
</para>
--- 1284,1291 ----
char *PQresultErrorMessage(const PGresult *res);
</synopsis>
! If there was an error, the returned string will include a trailing newline.
! The caller should not free the result directly. It will be freed when the
! associated <structname>PGresult</> handle is passed to
! <function>PQclear</function>.
</para>
***************
*** 1308,1312 ****
<structname>PGresult</structname> is not an error or warning result,
or does not include the specified field. Field values will normally
! not include a trailing newline.
</para>
--- 1315,1324 ----
<structname>PGresult</structname> is not an error or warning result,
or does not include the specified field. Field values will normally
! not include a trailing newline. The caller should not free the
! result directly. It will be freed when the
! associated <structname>PGresult</> handle is passed to
! <function>PQclear</function>.
!
!
</para>
***************
*** 1537,1541 ****
<para>
Returns the column name associated with the given column number.
! Column numbers start at 0.
<synopsis>
char *PQfname(const PGresult *res,
--- 1549,1556 ----
<para>
Returns the column name associated with the given column number.
! Column numbers start at 0. The caller should not free the result
! directly. It will be freed when the associated <structname>PGresult</>
! handle is passed to <function>PQclear</function>.
!
<synopsis>
char *PQfname(const PGresult *res,
***************
*** 1751,1754 ****
--- 1766,1774 ----
of a <structname>PGresult</structname>.
Row and column numbers start at 0.
+ The caller should not free the result directly.
+ It will be freed when the
+ associated <structname>PGresult</> handle is passed to
+ <function>PQclear</function>.
+
<synopsis>
char* PQgetvalue(const PGresult *res,
***************
*** 1886,1890 ****
<para>
Commonly this is just the name of the command, but it may include additional
! data such as the number of rows processed.
</para>
</listitem>
--- 1906,1914 ----
<para>
Commonly this is just the name of the command, but it may include additional
! data such as the number of rows processed. The caller should
! not free the result directly. It will be freed when the
! associated <structname>PGresult</> handle is passed to
! <function>PQclear</function>.
!
</para>
</listitem>
***************
*** 1907,1911 ****
or <command>FETCH</>, this returns a
string containing the number of rows affected. If the
! command was anything else, it returns the empty string.
</para>
</listitem>
--- 1931,1940 ----
or <command>FETCH</>, this returns a
string containing the number of rows affected. If the
! command was anything else, it returns the empty string. The
! caller should not free the result directly. It will be freed
! when the associated <structname>PGresult</> handle is passed to
! <function>PQclear</function>.
!
!
</para>
</listitem>
---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to [EMAIL PROTECTED]
