[PATCH:libX11] specs/libX11: Update Portability Considerations for the 21st century

[Alan Coopersmith]

Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>
---
 specs/libX11/AppC.xml | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

The current version of this section can be seen at:
https://www.x.org/releases/X11R7.7/doc/libX11/libX11/libX11.html#Portability_Considerations

diff --git a/specs/libX11/AppC.xml b/specs/libX11/AppC.xml
index bac148c..8eb1e00 100644
--- a/specs/libX11/AppC.xml
+++ b/specs/libX11/AppC.xml
@@ -3211,13 +3211,12 @@ You must pass back the same pointer and size that were returned by
 </sect2>
 <sect2 id="Portability_Considerations">
 <title>Portability Considerations</title>
 <para>
 <!-- .LP -->
-Many machine architectures, 
-including many of the more recent <acronym>RISC</acronym> architectures,
-do not correctly access data at unaligned locations; 
+Many machine architectures
+do not correctly or efficiently access data at unaligned locations;
 their compilers pad out structures to preserve this characteristic.
 Many other machines capable of unaligned references pad inside of structures
 as well to preserve alignment, because accessing aligned data is
 usually much faster.
 Because the library and the server use structures to access data at
@@ -3227,11 +3226,13 @@ that is, 16-bit data starts on 16-bit boundaries in the request
 and 32-bit data on 32-bit boundaries.
 All requests <emphasis remap='I'>must</emphasis> be a multiple of 32 bits in length to preserve
 the natural alignment in the data stream.
 You must pad structures out to 32-bit boundaries.
 Pad information does not have to be zeroed unless you want to
-preserve such fields for future use in your protocol requests.
+preserve such fields for future use in your protocol requests,
+but it is recommended to zero it to avoid inadvertant data leakage
+and improve compressability.
 Floating point varies radically between machines and should be
 avoided completely if at all possible.
 </para>
 <para>
 <!-- .LP -->
@@ -3264,19 +3265,27 @@ take on values larger than the maximum 16-bit
 <type>unsigned</type>
 <type>int</type>.
 </para>
 <para>
 <!-- .LP -->
-The library currently assumes that a
+The library has always assumed that a
 <type>char</type>
 is 8 bits, a
 <type>short</type>
 is 16 bits, an
 <type>int</type>
 is 16 or 32 bits, and a
 <type>long</type>
-is 32 bits.  
+is 32 bits.
+Unfortunately, this assumption remains on machines where a <type>long</type>
+can hold 64-bits, and many functions and structures require unnecessarily
+large fields to avoid breaking compatibility with existing code.  Special
+care must be taken with arrays of values that are transmitted in the
+protocol as CARD32 or INT32 but have to be converted to arrays of 64-bit
+<type>long</type> when passed to or from client applications.
+</para>
+<para>
 The 
 <function>PackData</function>
 macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. 
 However, much more work is needed to make this work properly.
 </para>
-- 
2.7.4