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

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 4a27ce5d40bd20c43bd71499e29dd4d0080278c4..c60b7c388383e8c5c93f9bde3b7de8048c0fc0c5 100644 (file)
--- 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 849779b6a7befbbb87b32f0c16bcfe95ef3496d8..db6ed41268c071397d806895f8f0fcd4e66436c5 100644 (file)
--- 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
@@ -1635,6 +1637,17 @@ for signed types.  Using @code{ptrdiff_t} limits objects to
 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