Received: from maia.hub.org (maia-2.hub.org [200.46.204.251])
	by mail.postgresql.org (Postfix) with ESMTP id D0268174C086
	for <pgsql-docs-postgresql.org@mail.postgresql.org>;
	Thu, 10 Nov 2011 14:19:20 -0400 (AST)
Received: from mail.postgresql.org ([200.46.204.86])
	by maia.hub.org (mx1.hub.org [200.46.204.251]) (amavisd-maia,
	port 10024) with ESMTP id 66796-06-2 for
	<pgsql-docs-postgresql.org@mail.postgresql.org>;
	Thu, 10 Nov 2011 18:19:14 +0000 (UTC)
X-Greylist: from auto-whitelisted by SQLgrey-1.8.0-rc2
Received: from momjian.us (momjian.us [72.94.173.45])
	by mail.postgresql.org (Postfix) with ESMTP id 20585A6B59
	for <pgsql-docs@postgresql.org>; Thu, 10 Nov 2011 14:01:01 -0400 (AST)
Received: (from bruce@localhost) by momjian.us (8.11.6/8.11.6) id
 pAAI0t926533;
	Thu, 10 Nov 2011 13:00:55 -0500 (EST)
From: Bruce Momjian <bruce@momjian.us>
Message-Id: <201111101800.pAAI0t926533@momjian.us>
Subject: Re: [PATCH] libpq: Return of NULL from PQexec
In-Reply-To: <alpine.LFD.2.01.1110311204150.4558@sys880.ldn.framestore.com>
To: Mark Hills <Mark.Hills@framestore.com>
Date: Thu, 10 Nov 2011 13:00:55 -0500 (EST)
CC: pgsql-docs@postgresql.org
X-Mailer: ELM [version 2.4ME+ PL124 (25)]
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset="US-ASCII"
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Spam-Status: No, hits=-3.101 tagged_above=-5 required=5 tests=BAYES_00=-1.9,
	RP_MATCHES_RCVD=-1.201
X-Spam-Level: 
X-Archive-Number: 201111/11
X-Sequence-Number: 7086


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. +