The attached patch clarifies (or, rather, makes explicit) to readers how

to handle memory management for char pointers returned by libpq functions.
Original patch by Gavin Sherry, some tweaking and consistency improvements
by Neil Conway.

doc/src/sgml/libpq.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.145 2004/01/09 02:02:43 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.146 2004/01/26 22:13:21 neilc Exp $
 -->
 
  <chapter id="libpq">
@@ -912,7 +912,9 @@ char *PQerrorMessage(const PGconn* conn);
        <function>PQerrorMessage</function> if they fail.
        Note that by <application>libpq</application> convention, a nonempty
        <function>PQerrorMessage</function> result will
-       include a trailing newline.
+       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>
     </varlistentry>
@@ -1262,7 +1264,8 @@ processor (see <xref linkend="libpq-notice-processing">).
 <listitem>
 <para>
         Converts the enumerated type returned by <function>PQresultStatus</> into
-        a string constant describing the status code.
+        a string constant describing the status code. The caller should not 
+        free the result.
 <synopsis>
 char *PQresStatus(ExecStatusType status);
 </synopsis>
@@ -1280,6 +1283,9 @@ if there was no error.
 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>
 
 <para>
@@ -1307,7 +1313,10 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
 listed below.  <symbol>NULL</symbol> is returned if the
 <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.
+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>
 
 <para>
@@ -1536,7 +1545,9 @@ int PQnfields(const PGresult *res);
 <listitem>
 <para>
 Returns the column name associated with the given column number.
- Column numbers start at 0.
+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,
               int column_number);
@@ -1747,9 +1758,12 @@ returns 1 only if all columns of the result are binary (format 1).
 <term><function>PQgetvalue</function><indexterm><primary>PQgetvalue</></></term>
 <listitem>
 <para>
-            Returns a single field value of one row
+            Returns a single field value of one row of a
-            of a <structname>PGresult</structname>.
+            <structname>PGresult</structname>.  Row and column numbers
-            Row and column numbers start at 0.
+            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,
                  int row_number,
@@ -1885,7 +1899,10 @@ char * PQcmdStatus(PGresult *res);
 </para>
 <para>
 Commonly this is just the name of the command, but it may include additional
-data such as the number of rows processed.
+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>
 </varlistentry>
@@ -1906,7 +1923,10 @@ char * PQcmdTuples(PGresult *res);
           <command>UPDATE</>, <command>DELETE</command>, <command>MOVE</>,
           or <command>FETCH</>, this returns a
           string containing the number of rows affected.  If the
-          command was anything else, it returns the empty string.
+          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>
 </varlistentry>