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.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 34d4f1cada454ece9ea1f8435c17e7a70798efc6..c08e6b6756bd8deddaf44d98386762713e27f535 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -4810,22 +4810,29 @@ typedef struct
    parameters to be passed to the function; they must match the declared
    function argument list.  When the isint field of a
    parameter structure is true, the 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 isint
+   to the server as an integer of the indicated length (this must be
+   2 or 4 bytes); proper byte-swapping occurs.  When isint
    is false, the indicated number of bytes at *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.  result_buf is the buffer in which to
-   place the return value.  The caller must  have  allocated sufficient
+   type.  (The declaration of u.ptr as being of
+   type int * is historical; it would be better to consider
+   it void *.)
+   result_buf 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
-   result_len.  If a 1, 2, or 4-byte integer result
+   length in bytes will be returned in the integer pointed to by
+   result_len.  If a 2- or 4-byte integer result
    is expected, set result_is_int to 1, otherwise
    set it to 0.  Setting result_is_int to 1 causes
    libpq to byte-swap the value if necessary, so that it
-   is delivered as a proper int value for the client machine.
+   is delivered as a proper int value for the client machine;
+   note that a 4-byte integer is delivered into *result_buf
+   for either allowed result size.
    When 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 result_buf as being of
+   type void *.)
   
 
   

diff --git a/src/interfaces/libpq/fe-exec.c b/src/interfaces/libpq/fe-exec.c
index 3d46e15067847d7ef410f21924b71a4edaaa909a..828f18e1110119efc3bf99ecf16d98ce306458ea 100644 (file)
--- a/src/interfaces/libpq/fe-exec.c
+++ b/src/interfaces/libpq/fe-exec.c
@@ -2514,20 +2514,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.
  * ----------------
@@ -2537,12 +2535,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;
@@ -2560,12 +2558,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);
 }