From e0707cbae9cb5360cd044231fda921fffe8095c5 Mon Sep 17 00:00:00 2001
From: Neil Conway <neilc@samurai.com>
Date: Mon, 26 Jan 2004 22:13:21 +0000
Subject: [PATCH] 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 | 64 +++++++++++++++++++++++++++--------------
1 file changed, 42 insertions(+), 22 deletions(-)
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index bfd66945f9c..ec1324c810c 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/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">
@@ -903,7 +903,7 @@ only protocol 2.0. (Protocol 1.0 is obsolete and not supported by <application>
Returns the error message most recently generated by
an operation on the connection.
<synopsis>
-char *PQerrorMessage(const PGconn* conn);
+char *PQerrorMessage(const PGconn *conn);
</synopsis>
</para>
@@ -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>
@@ -1279,7 +1282,10 @@ if there was no error.
<synopsis>
char *PQresultErrorMessage(const PGresult *res);
</synopsis>
-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 <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>
@@ -1535,8 +1544,10 @@ int PQnfields(const PGresult *res);
<term><function>PQfname</function><indexterm><primary>PQfname</></></term>
<listitem>
<para>
- 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 <structname>PGresult</>
+handle is passed to <function>PQclear</function>.
<synopsis>
char *PQfname(const PGresult *res,
int column_number);
@@ -1566,8 +1577,8 @@ int PQfnumber(const PGresult *res,
<para>
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
<programlisting>
select 1 as FOO, 2 as "BAR";
</programlisting>
@@ -1747,11 +1758,14 @@ 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
- of a <structname>PGresult</structname>.
- Row and column numbers start at 0.
+ Returns a single field value of one row 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,
+char *PQgetvalue(const PGresult *res,
int row_number,
int column_number);
</synopsis>
@@ -1880,12 +1894,15 @@ results.
Returns the command status tag from the SQL command that
generated the <structname>PGresult</structname>.
<synopsis>
-char * PQcmdStatus(PGresult *res);
+char *PQcmdStatus(PGresult *res);
</synopsis>
</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>
@@ -1896,7 +1913,7 @@ data such as the number of rows processed.
<para>
Returns the number of rows affected by the SQL command.
<synopsis>
-char * PQcmdTuples(PGresult *res);
+char *PQcmdTuples(PGresult *res);
</synopsis>
</para>
@@ -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>
@@ -1940,7 +1960,7 @@ Oid PQoidValue(const PGresult *res);
OIDs.) If the command was not an <command>INSERT</command>,
returns an empty string.
<synopsis>
-char * PQoidStatus(const PGresult *res);
+char *PQoidStatus(const PGresult *res);
</synopsis>
</para>
@@ -2522,7 +2542,7 @@ parameters and results substitutes for a fast-path function call.
The function <function>PQfn</function><indexterm><primary>PQfn</></>
requests execution of a server function via the fast-path interface:
<synopsis>
-PGresult* PQfn(PGconn* conn,
+PGresult *PQfn(PGconn *conn,
int fnid,
int *result_buf,
int *result_len,
@@ -2620,7 +2640,7 @@ The function <function>PQnotifies</function>
returned from <function>PQnotifies</>, it is considered handled and will be
removed from the list of notifications.
<synopsis>
-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
<programlisting>
static void
-defaultNoticeProcessor(void * arg, const char * message)
+defaultNoticeProcessor(void *arg, const char *message)
{
fprintf(stderr, "%s", message);
}
--
GitLab