Обсуждение: [PATCH] libpq: Return of NULL from PQexec
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>
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. +