From c59ef5ef53f8e33a693f1107c1d61535bbd3a187 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Wed, 1 Oct 2014 13:34:55 -0700 Subject: [PATCH] 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 --- doc/lispref/ChangeLog | 5 +++++ doc/lispref/internals.texi | 13 +++++++++++++ 2 files changed, 18 insertions(+) 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 + 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. -- 2.11.4.GIT