[DOCS] [PATCH] libpq: Return of NULL from PQexec

[Mark Hills]

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 
To: pgsql-hack...@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 PGconn object.
The 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.
 

@@ -1748,8 +1748,10 @@ PGresult *PQexec(PGconn *conn, const char *command);
 Returns a PGresult 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 PGRES_FATAL_ERROR result.  Use
+the command to the server.  The 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
+PGRES_FATAL_ERROR).  Use
 PQerrorMessage to get more information about such
 errors.


-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] PGDATA confusion

[Thom Brown]

On 15 October 2011 03:24, Thom Brown  wrote:
> Hi,
>
> I notice that in the man page and the page for pg_ctl in the
> documentation (http://www.postgresql.org/docs/current/static/app-pg-ctl.html)
> it states that the -D parameter should point to the directory which
> contains the database files:
>
> "Specifies the file system location of the database files. If this is
> omitted, the environment variable PGDATA is used."
>
> This isn't necessarily true.  It will only need to know where the
> postgresql.conf file is.  In Debian and Ubuntu, for example, the
> "database files" reside in /var/lib/postgresql/x.x/main/, and the
> configuration files in /etc/postgresql/x.x/main/, so a user might
> assume they need to point it to the former as that's where the actual
> database itself can be found, when in fact it needs to be the latter.
>
> This same inaccuracy affects the "postgres" command
> (http://www.postgresql.org/docs/current/static/app-postgres.html) to a
> lesser extent:
>
> "Specifies the file system location of the data directory or
> configuration file(s)."
>
> Which is it?  This suggests it can be either, when only the latter
> matters.  If it also happens to be the data directory, that's
> unimportant.
>
> To add further confusion, the page describing PGDATA
> (http://www.postgresql.org/docs/current/static/storage-file-layout.html)
> refers to it like so:
>
> "All the data needed for a database cluster is stored within the
> cluster's data directory, commonly referred to as PGDATA...
>
> *snip*
>
> The PGDATA directory contains several subdirectories and control
> files... ...In addition to these required items, the cluster
> configuration files postgresql.conf, pg_hba.conf, and pg_ident.conf
> are traditionally stored in PGDATA (although in PostgreSQL 8.0 and
> later, it is possible to keep them elsewhere)."
>
> Traditionally but not necessarily, and not by default in Debian and
> Ubuntu.  In fact Gentoo (and therefore probably Sabayon too) has also
> elected for this separation of data files and config files as of 9.0.
>
> So if one set PGDATA to somewhere which had no database files at all,
> but just postgresql.conf, it could still work (assuming it, in turn,
> set data_directory correctly), but not vice versa.  It would make more
> sense to call it PGCONFIG, although I'm not proposing that, especially
> since PGDATA makes sense when it comes to initdb.
>
> There are probably plenty of other places in the docs which also don't
> adequately describe PGDATA or -D.
>
> Any disagreements?  If not, should I write a patch (since someone will
> probably accuse me of volunteering anyway) or would someone like to
> commit some adjustments?

No opinions on this?

-- 
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

-- 
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs