From 1a0bc4c2bfc278b63965486b1525ad04a1f85989 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 8 Mar 2015 13:35:28 -0400 Subject: [PATCH] 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 34d4f1cada..c08e6b6756 100644 --- 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 3d46e15067..828f18e111 100644 --- 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); }