public inbox for [email protected]
help / color / mirror / Atom feedPatch for bind message to clarify signedness of parameters and result column format codes
3+ messages / 2 participants
[nested] [flat]
* Patch for bind message to clarify signedness of parameters and result column format codes
@ 2026-06-09 11:51 Dave Cramer <[email protected]>
2026-06-10 13:16 ` Re: Patch for bind message to clarify signedness of parameters and result column format codes Peter Eisentraut <[email protected]>
0 siblings, 1 reply; 3+ messages in thread
From: Dave Cramer @ 2026-06-09 11:51 UTC (permalink / raw)
To: Pg Docs <[email protected]>
Currently we don't say whether the number of parameters is signed or
unsigned. Same with results
See attached patch.
Regards,
Dave Cramer
Attachments:
[application/octet-stream] 0001-doc-clarify-unsigned-integer-fields-in-protocol-messages.patch (9.3K, ../../CADK3HHLsX7gnp83i5onq4JXiaqYU6kheTKyvdmHLi0aF1w5m=A@mail.gmail.com/3-0001-doc-clarify-unsigned-integer-fields-in-protocol-messages.patch)
download | inline diff:
From c4bf7e27a96602409b08eef9bbd9e4ce75aec000 Mon Sep 17 00:00:00 2001
From: Dave Cramer <[email protected]>
Date: Thu, 21 May 2026 08:31:48 -0700
Subject: [PATCH] doc: clarify signedness of integer fields in protocol
messages
Add (unsigned) or (signed) annotations to protocol message fields
to help client implementors correctly size their integer types when
parsing or constructing protocol messages.
---
doc/src/sgml/protocol.sgml | 52 +++++++++++++++++++++-----------------
1 file changed, 29 insertions(+), 23 deletions(-)
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 49f81676712..c6cefb48434 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -4242,7 +4242,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- The process ID of this backend.
+ The process ID of this backend (signed).
</para>
</listitem>
</varlistentry>
@@ -4326,7 +4326,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
or that the parameters all use the default format (text);
or one, in which case the specified format code is applied
to all parameters; or it can equal the actual number of
- parameters.
+ parameters (unsigned).
</para>
</listitem>
</varlistentry>
@@ -4346,7 +4346,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of parameter values that follow (possibly zero).
- This must match the number of parameters needed by the query.
+ This must match the number of parameters needed by the query
+ (unsigned).
</para>
</listitem>
</varlistentry>
@@ -4362,7 +4363,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The length of the parameter value, in bytes (this count
- does not include itself). Can be zero.
+ does not include itself, signed). Can be zero.
As a special case, -1 indicates a NULL parameter value.
No value bytes follow in the NULL case.
</para>
@@ -4397,7 +4398,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
(text);
or one, in which case the specified format code is applied
to all result columns (if any); or it can equal the actual
- number of result columns of the query.
+ number of result columns of the query (unsigned).
</para>
</listitem>
</varlistentry>
@@ -4795,7 +4796,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of columns in the data to be copied
- (denoted <replaceable>N</replaceable> below).
+ (denoted <replaceable>N</replaceable> below, unsigned).
</para>
</listitem>
</varlistentry>
@@ -4855,7 +4856,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of columns in the data to be copied
- (denoted <replaceable>N</replaceable> below).
+ (denoted <replaceable>N</replaceable> below, unsigned).
</para>
</listitem>
</varlistentry>
@@ -4915,7 +4916,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of columns in the data to be copied
- (denoted <replaceable>N</replaceable> below).
+ (denoted <replaceable>N</replaceable> below, unsigned).
</para>
</listitem>
</varlistentry>
@@ -4960,7 +4961,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int16</term>
<listitem>
<para>
- The number of column values that follow (possibly zero).
+ The number of column values that follow (possibly zero,
+ unsigned).
</para>
</listitem>
</varlistentry>
@@ -4976,7 +4978,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The length of the column value, in bytes (this count
- does not include itself). Can be zero.
+ does not include itself, signed). Can be zero.
As a special case, -1 indicates a NULL column value.
No value bytes follow in the NULL case.
</para>
@@ -5164,7 +5166,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<para>
Maximum number of rows to return, if portal contains
a query that returns rows (ignored otherwise). Zero
- denotes <quote>no limit</quote>.
+ denotes <quote>no limit</quote> (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5238,7 +5240,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
or that the arguments all use the default format (text);
or one, in which case the specified format code is applied
to all arguments; or it can equal the actual number of
- arguments.
+ arguments (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5258,7 +5260,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
Specifies the number of arguments being supplied to the
- function.
+ function (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5274,7 +5276,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The length of the argument value, in bytes (this count
- does not include itself). Can be zero.
+ does not include itself, signed). Can be zero.
As a special case, -1 indicates a NULL argument value.
No value bytes follow in the NULL case.
</para>
@@ -5338,7 +5340,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The length of the function result value, in bytes (this count
- does not include itself). Can be zero.
+ does not include itself, signed). Can be zero.
As a special case, -1 indicates a NULL function result.
No value bytes follow in the NULL case.
</para>
@@ -5460,7 +5462,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- Number of protocol options not recognized by the server.
+ Number of protocol options not recognized by the server
+ (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5592,7 +5595,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- The process ID of the notifying backend process.
+ The process ID of the notifying backend process (signed).
</para>
</listitem>
</varlistentry>
@@ -5645,7 +5648,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of parameters used by the statement
- (can be zero).
+ (can be zero, unsigned).
</para>
</listitem>
</varlistentry>
@@ -5760,7 +5763,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
(can be zero). Note that this is not an indication of
the number of parameters that might appear in the
query string, only the number that the frontend wants to
- prespecify types for.
+ prespecify types for (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5972,7 +5975,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int16</term>
<listitem>
<para>
- Specifies the number of fields in a row (can be zero).
+ Specifies the number of fields in a row (can be zero,
+ unsigned).
</para>
</listitem>
</varlistentry>
@@ -6025,7 +6029,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int16</term>
<listitem>
<para>
- The data type size (see <varname>pg_type.typlen</varname>).
+ The data type size (see <varname>pg_type.typlen</varname>,
+ signed).
Note that negative values denote variable-width types.
</para>
</listitem>
@@ -6035,7 +6040,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- The type modifier (see <varname>pg_attribute.atttypmod</varname>).
+ The type modifier (see <varname>pg_attribute.atttypmod</varname>,
+ signed).
The meaning of the modifier is type-specific.
</para>
</listitem>
@@ -6095,7 +6101,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
Length of SASL mechanism specific "Initial Client Response" that
- follows, or -1 if there is no Initial Response.
+ follows (signed), or -1 if there is no Initial Response.
</para>
</listitem>
</varlistentry>
--
2.50.1 (Apple Git-155)
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Patch for bind message to clarify signedness of parameters and result column format codes
2026-06-09 11:51 Patch for bind message to clarify signedness of parameters and result column format codes Dave Cramer <[email protected]>
@ 2026-06-10 13:16 ` Peter Eisentraut <[email protected]>
2026-06-10 14:03 ` Re: Patch for bind message to clarify signedness of parameters and result column format codes Dave Cramer <[email protected]>
0 siblings, 1 reply; 3+ messages in thread
From: Peter Eisentraut @ 2026-06-10 13:16 UTC (permalink / raw)
To: Dave Cramer <[email protected]>; Pg Docs <[email protected]>
On 09.06.26 13:51, Dave Cramer wrote:
> Currently we don't say whether the number of parameters is signed or
> unsigned. Same with results
Instead of repeating this with every message, we should clarify this in
the section "Message Data Types".
I had always assumed that a type designation like Int16 or Int32 is
signed, because of how they look like C types. But on the other hand,
the POSIX functions to convert between host and network order only deal
with unsigned types. So it's not obvious either way.
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Patch for bind message to clarify signedness of parameters and result column format codes
2026-06-09 11:51 Patch for bind message to clarify signedness of parameters and result column format codes Dave Cramer <[email protected]>
2026-06-10 13:16 ` Re: Patch for bind message to clarify signedness of parameters and result column format codes Peter Eisentraut <[email protected]>
@ 2026-06-10 14:03 ` Dave Cramer <[email protected]>
0 siblings, 0 replies; 3+ messages in thread
From: Dave Cramer @ 2026-06-10 14:03 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: Pg Docs <[email protected]>
On Wed, 10 Jun 2026 at 09:16, Peter Eisentraut <[email protected]> wrote:
> On 09.06.26 13:51, Dave Cramer wrote:
> > Currently we don't say whether the number of parameters is signed or
> > unsigned. Same with results
>
> Instead of repeating this with every message, we should clarify this in
> the section "Message Data Types".
>
I've attached a new patch.
>
> I had always assumed that a type designation like Int16 or Int32 is
> signed, because of how they look like C types. But on the other hand,
> the POSIX functions to convert between host and network order only deal
> with unsigned types. So it's not obvious either way.
>
> It was surprising to me that some of them were unsigned
Dave
Attachments:
[application/octet-stream] 0002-doc-clarify-signedness-of-integer-fields-in-protocol.patch (6.7K, ../../CADK3HHL9L1jV0=iCQhCQJh_-8xhrNZxvtigWO+Joa75tZDRGOQ@mail.gmail.com/3-0002-doc-clarify-signedness-of-integer-fields-in-protocol.patch)
download | inline diff:
From 12c1471f30a0cb89b2f463430eba1c89331afec1 Mon Sep 17 00:00:00 2001
From: Dave Cramer <[email protected]>
Date: Wed, 10 Jun 2026 09:58:39 -0400
Subject: [PATCH] doc: clarify signedness of integer fields in protocol
messages
State the default integer signedness convention in the Message Data
Types section, and annotate the fields that are exceptions (unsigned
counts) with an inline note. This helps client implementors correctly
size their integer types when parsing or constructing protocol
messages.
---
doc/src/sgml/protocol.sgml | 39 ++++++++++++++++++++++----------------
1 file changed, 23 insertions(+), 16 deletions(-)
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 49f81676712..23a761a65a4 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -3743,8 +3743,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int<replaceable>n</replaceable>(<replaceable>i</replaceable>)</term>
<listitem>
<para>
- An <replaceable>n</replaceable>-bit integer in network byte
- order (most significant byte first).
+ An <replaceable>n</replaceable>-bit two's-complement signed
+ integer in network byte order (most significant byte first).
+ Some message fields — typically array or repetition counts —
+ use the same wire format with unsigned semantics; this is noted
+ in the individual field description where it applies.
If <replaceable>i</replaceable> is specified it
is the exact value that will appear, otherwise the value
is variable. Eg. Int16, Int32(42).
@@ -4326,7 +4329,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
or that the parameters all use the default format (text);
or one, in which case the specified format code is applied
to all parameters; or it can equal the actual number of
- parameters.
+ parameters (unsigned).
</para>
</listitem>
</varlistentry>
@@ -4346,7 +4349,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of parameter values that follow (possibly zero).
- This must match the number of parameters needed by the query.
+ This must match the number of parameters needed by the query
+ (unsigned).
</para>
</listitem>
</varlistentry>
@@ -4397,7 +4401,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
(text);
or one, in which case the specified format code is applied
to all result columns (if any); or it can equal the actual
- number of result columns of the query.
+ number of result columns of the query (unsigned).
</para>
</listitem>
</varlistentry>
@@ -4795,7 +4799,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of columns in the data to be copied
- (denoted <replaceable>N</replaceable> below).
+ (denoted <replaceable>N</replaceable> below, unsigned).
</para>
</listitem>
</varlistentry>
@@ -4855,7 +4859,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of columns in the data to be copied
- (denoted <replaceable>N</replaceable> below).
+ (denoted <replaceable>N</replaceable> below, unsigned).
</para>
</listitem>
</varlistentry>
@@ -4915,7 +4919,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of columns in the data to be copied
- (denoted <replaceable>N</replaceable> below).
+ (denoted <replaceable>N</replaceable> below, unsigned).
</para>
</listitem>
</varlistentry>
@@ -4960,7 +4964,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int16</term>
<listitem>
<para>
- The number of column values that follow (possibly zero).
+ The number of column values that follow (possibly zero,
+ unsigned).
</para>
</listitem>
</varlistentry>
@@ -5164,7 +5169,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<para>
Maximum number of rows to return, if portal contains
a query that returns rows (ignored otherwise). Zero
- denotes <quote>no limit</quote>.
+ denotes <quote>no limit</quote> (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5238,7 +5243,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
or that the arguments all use the default format (text);
or one, in which case the specified format code is applied
to all arguments; or it can equal the actual number of
- arguments.
+ arguments (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5258,7 +5263,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
Specifies the number of arguments being supplied to the
- function.
+ function (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5460,7 +5465,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32</term>
<listitem>
<para>
- Number of protocol options not recognized by the server.
+ Number of protocol options not recognized by the server
+ (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5645,7 +5651,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The number of parameters used by the statement
- (can be zero).
+ (can be zero, unsigned).
</para>
</listitem>
</varlistentry>
@@ -5760,7 +5766,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
(can be zero). Note that this is not an indication of
the number of parameters that might appear in the
query string, only the number that the frontend wants to
- prespecify types for.
+ prespecify types for (unsigned).
</para>
</listitem>
</varlistentry>
@@ -5972,7 +5978,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int16</term>
<listitem>
<para>
- Specifies the number of fields in a row (can be zero).
+ Specifies the number of fields in a row (can be zero,
+ unsigned).
</para>
</listitem>
</varlistentry>
--
2.50.1 (Apple Git-155)
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2026-06-10 14:03 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-06-09 11:51 Patch for bind message to clarify signedness of parameters and result column format codes Dave Cramer <[email protected]>
2026-06-10 13:16 ` Peter Eisentraut <[email protected]>
2026-06-10 14:03 ` Dave Cramer <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox