c8h4/postgresql
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

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

Browse source 
to handle memory management for char pointers returned by libpq functions.
Original patch by Gavin Sherry, some tweaking and consistency improvements
by Neil Conway.
This commit is contained in:
Neil Conway 2004-01-26 22:13:21 +00:00
parent be11fa26e3
commit e0707cbae9
1 changed files with 42 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
doc/src/sgml/libpq.sgml
View file

@ -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
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,
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>