[Emacs-diffs] trunk r118001: Improve doc for use of 'int', and discuss 'ssize_t'.

[Paul Eggert]

------------------------------------------------------------
revno: 118001
revision-id: address@hidden
parent: address@hidden
author: Paul Eggert  <address@hidden>
committer: Paul Eggert <address@hidden>
branch nick: trunk
timestamp: Wed 2014-10-01 13:34:55 -0700
message:
  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
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/internals.texi     
internals.texi-20091113204419-o5vbwnq5f7feedwu-6188

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-10-01 03:28:16 +0000
+++ b/doc/lispref/ChangeLog     2014-10-01 20:34:55 +0000
@@ -1,5 +1,10 @@
 2014-10-01  Paul Eggert  <address@hidden>
 
+       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.

=== modified file 'doc/lispref/internals.texi'
--- a/doc/lispref/internals.texi        2014-10-01 03:28:16 +0000
+++ b/doc/lispref/internals.texi        2014-10-01 20:34:55 +0000
@@ -1625,6 +1625,8 @@
 
 @item
 Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF.
+More generally, prefer @code{int} for integers known to be in
address@hidden range, e.g., screen column counts.
 
 @item
 Prefer @code{ptrdiff_t} for sizes, i.e., for integers bounded by the
@@ -1636,6 +1638,17 @@
 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
address@hidden 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 ..@:
address@hidden
+
address@hidden
 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.