Обсуждение: BUG #4053: libpq documentation should express clearly, that integers are passed in network octet order
BUG #4053: libpq documentation should express clearly, that integers are passed in network octet order
От
"Aleksej Saushev"
Дата:
The following bug has been logged online: Bug reference: 4053 Logged by: Aleksej Saushev Email address: asau@inbox.ru PostgreSQL version: 8.3 Operating system: NetBSD, but this does no matter Description: libpq documentation should express clearly, that integers are passed in network octet order Details: The documentation on PQexecParams is silent about the precise format, expected by server for binary parameters, it should be more explicit and note that integers are expected in network octet order.
Aleksej Saushev wrote: > > The following bug has been logged online: > > Bug reference: 4053 > Logged by: Aleksej Saushev > Email address: asau@inbox.ru > PostgreSQL version: 8.3 > Operating system: NetBSD, but this does no matter > Description: libpq documentation should express clearly, that > integers are passed in network octet order > Details: > > The documentation on PQexecParams is silent about the precise format, > expected by server for binary parameters, it should be more explicit > and note that integers are expected in network octet order. This brings up a good question. Exactly how do users know what format _binary_ is? int4 is network byte order, but what about int8, float4, inet? -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Bruce Momjian wrote: > Aleksej Saushev wrote: >> The following bug has been logged online: >> >> Bug reference: 4053 >> Logged by: Aleksej Saushev >> Email address: asau@inbox.ru >> PostgreSQL version: 8.3 >> Operating system: NetBSD, but this does no matter >> Description: libpq documentation should express clearly, that >> integers are passed in network octet order >> Details: >> >> The documentation on PQexecParams is silent about the precise format, >> expected by server for binary parameters, it should be more explicit >> and note that integers are expected in network octet order. > > This brings up a good question. Exactly how do users know what format > _binary_ is? int4 is network byte order, but what about int8, float4, > inet? > They don't have to if they use the libpqtypes library :) project: http://pgfoundry.org/projects/libpqtypes/ online docs: http://libpqtypes.esilo.com/ andrew
Bruce Momjian wrote: > This brings up a good question. Exactly how do users know what format > _binary_ is? int4 is network byte order, but what about int8, float4, > inet? This is exactly what libpqtypes solves. Not only do we handle formatting of binary formats, we provide a level of protection from internal format changes for libpq users. See the example here: http://libpqtypes.esilo.com/. So, documentation of binary formats (including network byte ordering) are not required. merlin
"Merlin Moncure" <mmoncure@gmail.com> writes: > Bruce Momjian wrote: >> This brings up a good question. Exactly how do users know what format >> _binary_ is? int4 is network byte order, but what about int8, float4, >> inet? > > This is exactly what libpqtypes solves. Not only do we handle > formatting of binary formats, we provide a level of protection from > internal format changes for libpq users. See the example here: > http://libpqtypes.esilo.com/. So, documentation of binary formats > (including network byte ordering) are not required. No, it is still required. There's not a single reference to libpqtypes in Postgres documentation, and libpqtypes isn't part of the distribution, if I understand it right.
Aleksej Saushev wrote: > > The following bug has been logged online: > > Bug reference: 4053 > Logged by: Aleksej Saushev > Email address: asau@inbox.ru > PostgreSQL version: 8.3 > Operating system: NetBSD, but this does no matter > Description: libpq documentation should express clearly, that > integers are passed in network octet order > Details: > > The documentation on PQexecParams is silent about the precise format, > expected by server for binary parameters, it should be more explicit > and note that integers are expected in network octet order. I have added this libpq documentation paragraph about how to determine how to pass binary values. I also added a few comments to the libpq C code. Thanks for the report; please let me know if I can improve it more. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. + Index: doc/src/sgml/libpq.sgml =================================================================== RCS file: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v retrieving revision 1.258 diff -c -c -r1.258 libpq.sgml *** doc/src/sgml/libpq.sgml 1 Jun 2008 16:23:08 -0000 1.258 --- doc/src/sgml/libpq.sgml 23 Jun 2008 21:09:39 -0000 *************** *** 1397,1402 **** --- 1397,1410 ---- If the array pointer is null then all parameters are presumed to be text strings. </para> + <para> + Values passed in binary format require knowlege of + the internal representation expected by the backend. + For example, integers must be passed in network byte + order. Passing <type>numeric</> values requires + knowledge of the server storage format, as implemented + in <filename>src/backend/utils/adt/numeric.c</>. + </para> </listitem> </varlistentry> Index: src/interfaces/libpq/fe-exec.c =================================================================== RCS file: /cvsroot/pgsql/src/interfaces/libpq/fe-exec.c,v retrieving revision 1.195 diff -c -c -r1.195 fe-exec.c *** src/interfaces/libpq/fe-exec.c 29 May 2008 22:02:44 -0000 1.195 --- src/interfaces/libpq/fe-exec.c 23 Jun 2008 21:09:39 -0000 *************** *** 976,987 **** goto sendFailed; } ! /* construct the Bind message */ if (pqPutMsgStart('B', false, conn) < 0 || pqPuts("", conn) < 0 || pqPuts(stmtName, conn) < 0) goto sendFailed; if (nParams > 0 && paramFormats) { if (pqPutInt(nParams, 2, conn) < 0) --- 976,988 ---- goto sendFailed; } ! /* Construct the Bind message */ if (pqPutMsgStart('B', false, conn) < 0 || pqPuts("", conn) < 0 || pqPuts(stmtName, conn) < 0) goto sendFailed; + /* Send parameter formats */ if (nParams > 0 && paramFormats) { if (pqPutInt(nParams, 2, conn) < 0) *************** *** 1001,1006 **** --- 1002,1008 ---- if (pqPutInt(nParams, 2, conn) < 0) goto sendFailed; + /* Send parameters */ for (i = 0; i < nParams; i++) { if (paramValues && paramValues[i])