Обсуждение: BUG #13404: Docs do not mention "access/htup_details.h" for C functions using heap_form_tuple

The following bug has been logged on the website:

Bug reference:      13404
Logged by:          Christian Reinke
Email address:      christianr@fastmail.com
PostgreSQL version: 9.4.2
Operating system:   Linux
Description:

Bug report regarding: PostgreSQL 9.4.2 Documentation (in HTML format)
                      Section 35.9. C-Language Functions
                      Section 35.9.8. Returning Rows (Composite Types)

PostgreSQL version: 9.4.2.

Debian packages: postgresql-9.4, postgresql-doc-9.4,
postgresql-server-dev-9.4,
                 etc., all version 9.4.2-0+deb8u1.

Platform: Linux ... 3.16.0-4-amd64 #1 SMP Debian 3.16.7-ckt9-3~deb8u1
          (2015-04-24) x86_64 GNU/Linux.

I tried to compile a C-language function that uses the function
heap_form_tuple and got a warning because its declaration was missing:

gcc -I/usr/include/postgresql/9.4/server -Wall -c -fpic -lm -g test1.c
test1.c: In function ‘test1’:
test1.c:246:3: warning: implicit declaration of function ‘heap_form_tuple’
[-Wimplicit-function-declaration]
   result_tuple = heap_form_tuple (result_tuple_desc, dat, isnull);
   ^

test1.c compiled without this warning under PostgreSQL 9.1.

test1.c included the following PostgreSQL header files:
#include "postgres.h"
#include "fmgr.h"
#include "funcapi.h"
#include "executor/executor.h"

test1.c compiles successfully under PostgreSQL 9.4 if I, also, include:
#include "access/htup_details.h"

PostgreSQL 9.1 included the declaration of heap_form_tuple along the
sequence funcapi.h, executor/tuptable.h and access/htup.h.  In
PostgreSQL 9.4, the declaration of heap_form_tuple moved from
access/htup.h to a new header file access/htup_details.h, which is not
included by funcapi.h.

The HTML documentation, however, seems to say in Section 35.9.8. that it
is sufficient to include funcapi.h to get all the definitions required
for functions returning rows (composite types).

Is this a bug, or did I miss something?

christianr@fastmail.com wrote:

> PostgreSQL 9.1 included the declaration of heap_form_tuple along the
> sequence funcapi.h, executor/tuptable.h and access/htup.h.  In
> PostgreSQL 9.4, the declaration of heap_form_tuple moved from
> access/htup.h to a new header file access/htup_details.h, which is not
> included by funcapi.h.
>
> The HTML documentation, however, seems to say in Section 35.9.8. that it
> is sufficient to include funcapi.h to get all the definitions required
> for functions returning rows (composite types).
>
> Is this a bug, or did I miss something?

Hmm.  So there are two ways to fix this bug.  One is to #include
"access/htup_details.h" in funcapi.h as you propose; the other is to
change the docs to state that heap_form_tuple is in htup_details and you
need to include that separately if you want it.

I could go both ways, but seeing as we changed this in 9.3 and many
people since then first complained and then tweaked their code to cope
by #including htup_details.h, I think changing the docs is the reasonable
option.  You can write functions without using heap_form_tuple, after
all.

Other opinions?

--
Álvaro Herrera                http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> christianr@fastmail.com wrote:
>> Is this a bug, or did I miss something?

> Hmm.  So there are two ways to fix this bug.  One is to #include
> "access/htup_details.h" in funcapi.h as you propose; the other is to
> change the docs to state that heap_form_tuple is in htup_details and you
> need to include that separately if you want it.

> I could go both ways, but seeing as we changed this in 9.3 and many
> people since then first complained and then tweaked their code to cope
> by #including htup_details.h, I think changing the docs is the reasonable
> option.  You can write functions without using heap_form_tuple, after
> all.

Yeah.  I don't think anyone's ever felt that that part of the
documentation was more authoritative than the code (especially not where
it's merely reporting an old and rather messy situation).  And as you say,
if we were going to change the code, the time for that was 2 releases
back.

            regards, tom lane