pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feed[PATCH] libpq: Return of NULL from PQexec
2+ messages / 2 participants
[nested] [flat]
* [PATCH] libpq: Return of NULL from PQexec
@ 2011-10-31 12:09 Mark Hills <Mark.Hills@framestore.com>
2011-11-10 18:00 ` Re: [PATCH] libpq: Return of NULL from PQexec Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 2+ messages in thread
From: Mark Hills @ 2011-10-31 12:09 UTC (permalink / raw)
To: pgsql-docs
I'm sending the patch below for inclusion.
Originally I ran this by pgsql-hackers, just to confirm the docs (and not
the code) were in need of the fix, which seems to be the case:
http://archives.postgresql.org/pgsql-hackers/2011-09/msg00614.php
Thanks
--
Mark
---------- Forwarded message ----------
Date: Mon, 12 Sep 2011 16:40:28 +0100 (BST)
From: Mark Hills <mark.hills@framestore.com>
To: pgsql-hackers@postgresql.org
Subject: libpq: Return of NULL from PQexec
The libpq documentation for PQexec states:
"If a null pointer is returned, it should be treated like a
PGRES_FATAL_ERROR result"
But this contradicts the example programs; eg. from Example Program 1:
/* Start a transaction block */
res = PQexec(conn, "BEGIN");
if (PQresultStatus(res) != PGRES_COMMAND_OK)
{
fprintf(stderr, "BEGIN command failed: %s", PQerrorMessage(conn));
PQclear(res);
exit_nicely(conn);
}
which does not check if (res != NULL).
The example is not buggy -- PQresultStatus, PQerrorMessage and,
importantly, PQclear deal with the NULL value; eg. src/libpq/fq-exec.c:
ExecStatusType
PQresultStatus(const PGresult *res)
{
if (!res)
return PGRES_FATAL_ERROR;
return res->resultStatus;
}
So I took the example to be correct, and attempted to fix the
documentation in the patch below. I hope this is useful.
In a straw-poll of code I could find using libpq, I found most follows the
example and is reliant on libpq for its NULL check.
The same also applies to PQconnect functions -- and PQstatus, PQfinish,
which I also tried to clarify in the documentation.
Thanks
--
Mark
inline patch 1: doc/src/sgml/libpq.sgml (+5/-3 lines) download inline-1.patch
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 163a893..57be7e1 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -62,7 +62,7 @@
return a non-null object pointer, unless perhaps there is too
little memory even to allocate the <structname>PGconn</> object.
The <function>PQstatus</> function should be called to check
- whether a connection was successfully made before queries are sent
+ the return value for a successful connection before queries are sent
via the connection object.
<warning>
@@ -1748,8 +1748,10 @@ PGresult *PQexec(PGconn *conn, const char *command);
Returns a <structname>PGresult</structname> pointer or possibly a null
pointer. A non-null pointer will generally be returned except in
out-of-memory conditions or serious errors such as inability to send
- the command to the server. If a null pointer is returned, it should
- be treated like a <symbol>PGRES_FATAL_ERROR</symbol> result. Use
+ the command to the server. The <function>PQresultStatus</> function
+ should be called to check the return value for any errors (including
+ the value of a null pointer, in which case it will return
+ <symbol>PGRES_FATAL_ERROR</symbol>). Use
<function>PQerrorMessage</function> to get more information about such
errors.
</para>
* Re: [PATCH] libpq: Return of NULL from PQexec
2011-10-31 12:09 [PATCH] libpq: Return of NULL from PQexec Mark Hills <Mark.Hills@framestore.com>
@ 2011-11-10 18:00 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 2+ messages in thread
From: Bruce Momjian @ 2011-11-10 18:00 UTC (permalink / raw)
To: Mark Hills <Mark.Hills@framestore.com>; +Cc: pgsql-docs
Thanks. Applied and back-patched to 9.1.
---------------------------------------------------------------------------
Mark Hills wrote:
> I'm sending the patch below for inclusion.
>
> Originally I ran this by pgsql-hackers, just to confirm the docs (and not
> the code) were in need of the fix, which seems to be the case:
>
> http://archives.postgresql.org/pgsql-hackers/2011-09/msg00614.php
>
> Thanks
>
> --
> Mark
>
> ---------- Forwarded message ----------
> Date: Mon, 12 Sep 2011 16:40:28 +0100 (BST)
> From: Mark Hills <mark.hills@framestore.com>
> To: pgsql-hackers@postgresql.org
> Subject: libpq: Return of NULL from PQexec
>
> The libpq documentation for PQexec states:
>
> "If a null pointer is returned, it should be treated like a
> PGRES_FATAL_ERROR result"
>
> But this contradicts the example programs; eg. from Example Program 1:
>
> /* Start a transaction block */
> res = PQexec(conn, "BEGIN");
> if (PQresultStatus(res) != PGRES_COMMAND_OK)
> {
> fprintf(stderr, "BEGIN command failed: %s", PQerrorMessage(conn));
> PQclear(res);
> exit_nicely(conn);
> }
>
> which does not check if (res != NULL).
>
> The example is not buggy -- PQresultStatus, PQerrorMessage and,
> importantly, PQclear deal with the NULL value; eg. src/libpq/fq-exec.c:
>
> ExecStatusType
> PQresultStatus(const PGresult *res)
> {
> if (!res)
> return PGRES_FATAL_ERROR;
> return res->resultStatus;
> }
>
> So I took the example to be correct, and attempted to fix the
> documentation in the patch below. I hope this is useful.
>
> In a straw-poll of code I could find using libpq, I found most follows the
> example and is reliant on libpq for its NULL check.
>
> The same also applies to PQconnect functions -- and PQstatus, PQfinish,
> which I also tried to clarify in the documentation.
>
> Thanks
>
> --
> Mark
>
>
> diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
> index 163a893..57be7e1 100644
> --- a/doc/src/sgml/libpq.sgml
> +++ b/doc/src/sgml/libpq.sgml
> @@ -62,7 +62,7 @@
> return a non-null object pointer, unless perhaps there is too
> little memory even to allocate the <structname>PGconn</> object.
> The <function>PQstatus</> function should be called to check
> - whether a connection was successfully made before queries are sent
> + the return value for a successful connection before queries are sent
> via the connection object.
>
> <warning>
> @@ -1748,8 +1748,10 @@ PGresult *PQexec(PGconn *conn, const char *command);
> Returns a <structname>PGresult</structname> pointer or possibly a null
> pointer. A non-null pointer will generally be returned except in
> out-of-memory conditions or serious errors such as inability to send
> - the command to the server. If a null pointer is returned, it should
> - be treated like a <symbol>PGRES_FATAL_ERROR</symbol> result. Use
> + the command to the server. The <function>PQresultStatus</> function
> + should be called to check the return value for any errors (including
> + the value of a null pointer, in which case it will return
> + <symbol>PGRES_FATAL_ERROR</symbol>). Use
> <function>PQerrorMessage</function> to get more information about such
> errors.
> </para>
>
> --
> Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
^ permalink raw reply [nested|flat] 2+ messages in thread
end of thread, other threads:[~2011-11-10 18:00 UTC | newest]
Thread overview: 2+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2011-10-31 12:09 [PATCH] libpq: Return of NULL from PQexec Mark Hills <Mark.Hills@framestore.com>
2011-11-10 18:00 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox