Message-ID: <4F392203.2040907@gmail.com>
Date: Mon, 13 Feb 2012 09:45:23 -0500
From: Jay Levitt <jay.levitt@gmail.com>
User-Agent: Postbox 3.0.2 (Macintosh/20111203)
MIME-Version: 1.0
To: "pgsql-docs@postgresql.org" <pgsql-docs@postgresql.org>
Subject: [PATCH] Use idiomatic style for varlena structs
Content-Type: multipart/mixed; boundary="------------040205080303000504080305"

This is a multi-part message in MIME format.
--------------040205080303000504080305
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

I'm new to the codebase, but I think this patch reflects real-world usage; 
the PostgreSQL code itself always calls the length field "vl_len_", and I 
believe int32 is preferred over int4 (yes?)

Jay Levitt

--------------040205080303000504080305
Content-Type: text/plain; x-mac-type="0"; x-mac-creator="0";
	name="vl_len_.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="vl_len_.patch"

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index a6d2a13..b19801d 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1733,9 +1733,11 @@ typedef struct
     <para>
      Finally, all variable-length types must also be  passed
      by  reference.   All  variable-length  types must begin
-     with a length field of exactly 4 bytes, and all data to
+     with an opaque length field of exactly 4 bytes, which will be set
+     by SET_VARSIZE; never set this field directly! All data to
      be  stored within that type must be located in the memory
-     immediately  following  that  length  field.   The
+     immediately  following  the  length  field, which is customarily
+     named <literal>vl_len_</literal>.   The
      length field contains the total length of the structure,
      that is,  it  includes  the  size  of  the  length  field
      itself.
@@ -1766,7 +1768,7 @@ typedef struct
 
 <programlisting>
 typedef struct {
-    int4 length;
+    int32 vl_len_;
     char data[1];
 } text;
 </programlisting>
@@ -1799,10 +1801,10 @@ memcpy(destination->data, buffer, 40);
 ]]>
 </programlisting>
 
-     <literal>VARHDRSZ</> is the same as <literal>sizeof(int4)</>, but
+     <literal>VARHDRSZ</> is the same as <literal>sizeof(int32)</>, but
      it's considered good style to use the macro <literal>VARHDRSZ</>
      to refer to the size of the overhead for a variable-length type.
-     Also, the length field <emphasis>must</> be set using the
+     Also, the vl_len_ field <emphasis>must</> be set using the
      <literal>SET_VARSIZE</> macro, not by simple assignment.
     </para>
 

--------------040205080303000504080305--