Date: Mon, 31 Oct 2011 12:09:45 +0000 (GMT)
From: Mark Hills <Mark.Hills@framestore.com>
To: pgsql-docs@postgresql.org
Subject: [PATCH] libpq: Return of NULL from PQexec
Message-ID: <alpine.LFD.2.01.1110311204150.4558@sys880.ldn.framestore.com>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII

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>