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.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index bfd66945f9c14319ba18f6787ddbb3f0127427b0..ec1324c810c3bf75baf076cac0b5b10612f3f60a 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 
 
  
@@ -903,7 +903,7 @@ only protocol 2.0.  (Protocol 1.0 is obsolete and not supported by 
        Returns the error message most recently generated by
        an operation on the connection.
 
-char *PQerrorMessage(const PGconn* conn);
+char *PQerrorMessage(const PGconn *conn);
 
       
 
@@ -912,7 +912,9 @@ char *PQerrorMessage(const PGconn* conn);
        PQerrorMessage if they fail.
        Note that by libpq convention, a nonempty
        PQerrorMessage 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 PGconn 
+       handle is passed to PQfinish.
       
      
     
@@ -1262,7 +1264,8 @@ processor (see ).
 
 
         Converts the enumerated type returned by PQresultStatus into
-        a string constant describing the status code.
+        a string constant describing the status code. The caller should not 
+        free the result.
 
 char *PQresStatus(ExecStatusType status);
 
@@ -1279,7 +1282,10 @@ if there was no error.
 
 char *PQresultErrorMessage(const PGresult *res);
 
-If there was an error, the returned string will include a trailing newline.
+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 PGresult handle is passed to 
+PQclear.
 
 
 
@@ -1307,7 +1313,10 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
 listed below.  NULL is returned if the
 PGresult 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 PGresult handle is passed to
+PQclear.
 
 
 
@@ -1535,8 +1544,10 @@ int PQnfields(const PGresult *res);
 PQfnamePQfname
 
 
- Returns the column name associated with the given column number.
- Column numbers start at 0.
+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 PGresult
+handle is passed to PQclear.
 
 char *PQfname(const PGresult *res,
               int column_number);
@@ -1566,8 +1577,8 @@ int PQfnumber(const PGresult *res,
 
 
         The given name is treated like an identifier in an SQL command,
-   that is, it is downcased unless double-quoted.  For example,
-   given a query result generated from the SQL command
+        that is, it is downcased unless double-quoted.  For example,
+        given a query result generated from the SQL command
 
 select 1 as FOO, 2 as "BAR";
 
@@ -1747,11 +1758,14 @@ returns 1 only if all columns of the result are binary (format 1).
 PQgetvaluePQgetvalue
 
 
-            Returns a single field value of one row
-            of a PGresult.
-            Row and column numbers start at 0.
+            Returns a single field value of one row of a
+            PGresult.  Row and column numbers
+            start at 0.  The caller should not free the result
+            directly.  It will be freed when the associated
+            PGresult handle is passed to
+            PQclear.
 
-char* PQgetvalue(const PGresult *res,
+char *PQgetvalue(const PGresult *res,
                  int row_number,
                  int column_number);
 
@@ -1880,12 +1894,15 @@ results.
           Returns the command status tag from the SQL command that
           generated the PGresult.
 
-char * PQcmdStatus(PGresult *res);
+char *PQcmdStatus(PGresult *res);
 
 
 
 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 PGresult handle is passed to
+PQclear.
 
 
 
@@ -1896,7 +1913,7 @@ data such as the number of rows processed.
 
           Returns the number of rows affected by the SQL command.
 
-char * PQcmdTuples(PGresult *res);
+char *PQcmdTuples(PGresult *res);
 
 
 
@@ -1906,7 +1923,10 @@ char * PQcmdTuples(PGresult *res);
           UPDATE, DELETE, MOVE,
           or 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 PGresult handle is passed to
+          PQclear.
 
 
 
@@ -1940,7 +1960,7 @@ Oid PQoidValue(const PGresult *res);
           OIDs.)  If the command was not an INSERT,
           returns an empty string.
 
-char * PQoidStatus(const PGresult *res);
+char *PQoidStatus(const PGresult *res);
 
 
 
@@ -2522,7 +2542,7 @@ parameters and results substitutes for a fast-path function call.
 The function PQfnPQfn
 requests execution of a server function via the fast-path interface:
 
-PGresult* PQfn(PGconn* conn,
+PGresult *PQfn(PGconn *conn,
                int fnid,
                int *result_buf,
                int *result_len,
@@ -2620,7 +2640,7 @@ The function PQnotifies
           returned from PQnotifies, it is considered handled and will be
           removed from the list of notifications.
 
-PGnotify* PQnotifies(PGconn *conn);
+PGnotify *PQnotifies(PGconn *conn);
 
 typedef struct pgNotify {
     char *relname;              /* notification condition name */
@@ -3291,7 +3311,7 @@ a void pointer that is the same one passed to
 The default notice processor is simply
 
 static void
-defaultNoticeProcessor(void * arg, const char * message)
+defaultNoticeProcessor(void *arg, const char *message)
 {
     fprintf(stderr, "%s", message);
 }