From: Paul Eggert <eggert@cs.ucla.edu>
Date: Wed, 1 Oct 2014 20:34:55 +0000 (-0700)
Subject: Improve doc for use of 'int', and discuss 'ssize_t'.
X-Git-Tag: emacs-25.0.90~2635^2~679^2~170
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c59ef5ef53f8e33a693f1107c1d61535bbd3a187;p=emacs.git

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 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
@@ -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