From 12c1471f30a0cb89b2f463430eba1c89331afec1 Mon Sep 17 00:00:00 2001
From: Dave Cramer <davecramer@gmail.com>
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)