postgres.git / summary / log / commit / refs
commit a07bd32f2b130a67bf285f8ef5f1fe4ebcc3a5b8
Author: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun Mar 08 17:35:28 2015 +0000
First released in: 9.5.0, 9.0.20, 9.1.16, 9.2.11, 9.3.7, 9.4.2
Fix documentation for libpq's PQfn().
The SGML docs claimed that 1-byte integers could be sent or received with
the "isint" options, but no such behavior has ever been implemented in
pqGetInt() or pqPutInt(). The in-code documentation header for PQfn() was
even less in tune with reality, and the code itself used parameter names
matching neither the SGML docs nor its libpq-fe.h declaration. Do a bit
of additional wordsmithing on the SGML docs while at it.
Since the business about 1-byte integers is a clear documentation bug,
back-patch to all supported branches.
doc/src/sgml/libpq.sgml | 23 +++++++++++++++--------
src/interfaces/libpq/fe-exec.c | 22 ++++++++++------------
2 files changed, 25 insertions(+), 20 deletions(-)
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 9cb96a4dbe8..a3a3fe7604a 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -4134,22 +4134,29 @@ typedef struct
parameters to be passed to the function; they must match the declared
function argument list. When the <parameter>isint</> field of a
parameter structure is true, the <parameter>u.integer</> value is sent
- to the server as an integer of the indicated length (this must be 1,
- 2, or 4 bytes); proper byte-swapping occurs. When <parameter>isint</>
+ to the server as an integer of the indicated length (this must be
+ 2 or 4 bytes); proper byte-swapping occurs. When <parameter>isint</>
is false, the indicated number of bytes at <parameter>*u.ptr</> are
sent with no processing; the data must be in the format expected by
the server for binary transmission of the function's argument data
- type. <parameter>result_buf</parameter> is the buffer in which to
- place the return value. The caller must have allocated sufficient
+ type. (The declaration of <parameter>u.ptr</> as being of
+ type <type>int *</> is historical; it would be better to consider
+ it <type>void *</>.)
+ <parameter>result_buf</parameter> points to the buffer in which to place
+ the function's return value. The caller must have allocated sufficient
space to store the return value. (There is no check!) The actual result
- length will be returned in the integer pointed to by
- <parameter>result_len</parameter>. If a 1, 2, or 4-byte integer result
+ length in bytes will be returned in the integer pointed to by
+ <parameter>result_len</parameter>. If a 2- or 4-byte integer result
is expected, set <parameter>result_is_int</parameter> to 1, otherwise
set it to 0. Setting <parameter>result_is_int</parameter> to 1 causes
<application>libpq</> to byte-swap the value if necessary, so that it
- is delivered as a proper <type>int</type> value for the client machine.
+ is delivered as a proper <type>int</type> value for the client machine;
+ note that a 4-byte integer is delivered into <parameter>*result_buf</>
+ for either allowed result size.
When <parameter>result_is_int</> is 0, the binary-format byte string
- sent by the server is returned unmodified.
+ sent by the server is returned unmodified. (In this case it's better
+ to consider <parameter>result_buf</parameter> as being of
+ type <type>void *</>.)
</para>
<para>
diff --git a/src/interfaces/libpq/fe-exec.c b/src/interfaces/libpq/fe-exec.c
index 65fb6020f82..885f23d3ded 100644
--- a/src/interfaces/libpq/fe-exec.c
+++ b/src/interfaces/libpq/fe-exec.c
@@ -2322,20 +2322,18 @@ PQendcopy(PGconn *conn)
* PQfn - Send a function call to the POSTGRES backend.
*
* conn : backend connection
- * fnid : function id
- * result_buf : pointer to result buffer (&int if integer)
- * result_len : length of return value.
- * actual_result_len: actual length returned. (differs from result_len
- * for varlena structures.)
- * result_type : If the result is an integer, this must be 1,
+ * fnid : OID of function to be called
+ * result_buf : pointer to result buffer
+ * result_len : actual length of result is returned here
+ * result_is_int : If the result is an integer, this must be 1,
* otherwise this should be 0
- * args : pointer to an array of function arguments.
+ * args : pointer to an array of function arguments
* (each has length, if integer, and value/pointer)
* nargs : # of arguments in args array.
*
* RETURNS
* PGresult with status = PGRES_COMMAND_OK if successful.
- * *actual_result_len is > 0 if there is a return value, 0 if not.
+ * *result_len is > 0 if there is a return value, 0 if not.
* PGresult with status = PGRES_FATAL_ERROR if backend returns an error.
* NULL on communications failure. conn->errorMessage will be set.
* ----------------
@@ -2345,12 +2343,12 @@ PGresult *
PQfn(PGconn *conn,
int fnid,
int *result_buf,
- int *actual_result_len,
+ int *result_len,
int result_is_int,
const PQArgBlock *args,
int nargs)
{
- *actual_result_len = 0;
+ *result_len = 0;
if (!conn)
return NULL;
@@ -2368,12 +2366,12 @@ PQfn(PGconn *conn,
if (PG_PROTOCOL_MAJOR(conn->pversion) >= 3)
return pqFunctionCall3(conn, fnid,
- result_buf, actual_result_len,
+ result_buf, result_len,
result_is_int,
args, nargs);
else
return pqFunctionCall2(conn, fnid,
- result_buf, actual_result_len,
+ result_buf, result_len,
result_is_int,
args, nargs);
}
[parent: 71b8e8e6cf12]