Improve doc for use of 'int', and discuss 'ssize_t'.

* internals.texi (C Integer Types): Mention 'int' for other
randomish values that lie in 'int' range.  Mention 'ssize_t'.  See:
http://lists.gnu.org/archive/html/emacs-devel/2014-10/msg00019.html

2 files changed, 18 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 4a27ce5d40b..c60b7c38838 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,10 @@
 2014-10-01  Paul Eggert  <eggert@cs.ucla.edu>
 
+        Improve doc for use of 'int', and discuss 'ssize_t'.
+        * internals.texi (C Integer Types): Mention 'int' for other
+        randomish values that lie in 'int' range.  Mention 'ssize_t'.  See:
+        http://lists.gnu.org/archive/html/emacs-devel/2014-10/msg00019.html
+
         Use AUTO_CONS instead of SCOPED_CONS, etc.
         * internals.texi (Stack-allocated Objects):
         Adjust to match the revised, less error-prone macros.
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 849779b6a7b..db6ed41268c 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1625,6 +1625,8 @@ of @code{intptr_t}).
 
 @item
 Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF.
+More generally, prefer @code{int} for integers known to be in
+@code{int} range, e.g., screen column counts.
 
 @item
 Prefer @code{ptrdiff_t} for sizes, i.e., for integers bounded by the
@@ -1636,6 +1638,17 @@ anyway since they would break pointer subtraction, so this does not
 impose an arbitrary limit.
 
 @item
+Avoid @code{ssize_t} except when communicating to low-level APIs that
+have @code{ssize_t}-related limitations.  Although it's equivalent to
+@code{ptrdiff_t} on typical platforms, @code{ssize_t} is occasionally
+narrower, so using it for size-related calculations could overflow.
+Also, @code{ptrdiff_t} is more ubiquitous and better-standardized, has
+standard @code{printf} formats, and is the basis for Emacs's internal
+size-overflow checking.  When using @code{ssize_t}, please note that
+POSIX requires support only for values in the range @minus{}1 ..@:
+@code{SSIZE_MAX}.
+
+@item
 Prefer @code{intptr_t} for internal representations of pointers, or
 for integers bounded only by the number of objects that can exist at
 any given time or by the total number of bytes that can be allocated.