summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRical Jasan <ricaljasan@pacific.net>2017-07-27 05:04:48 -0700
committerRical Jasan <ricaljasan@pacific.net>2017-08-10 20:28:28 -0700
commit925733a913ff7087e56f6ffebd2998f683212e78 (patch)
treeb6d38143b185f423100d5416a173579b361bc605
parent4fcdfbfcf9d5c5a313da43f78309aa2745b2dc32 (diff)
downloadglibc-925733a913ff7087e56f6ffebd2998f683212e78.tar.gz
manual: Rewrite the section on widths of integer types.
The manual contradicted itself by saying the number of bits in an integer type needed to be computed, and then listing a number of macros that later standards provided for exactly that. The entire section has been reworked to provide those macros first, while preserving the documentation of CHAR_BIT and the associated examples within that context. * manual/lang.texi (Computing the Width of an Integer Data Type): Rename section to "Width of an Integer Type". Remove inaccurate statement regarding lack of C language facilities for determining width of integer types, and reorder content to improve flow and context of discussion.
-rw-r--r--ChangeLog9
-rw-r--r--manual/lang.texi79
2 files changed, 48 insertions, 40 deletions
diff --git a/ChangeLog b/ChangeLog
index 421e82afa0..9e7dd959da 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
2017-08-10 Rical Jasan <ricaljasan@pacific.net>
+ * manual/lang.texi
+ (Computing the Width of an Integer Data Type): Rename section to
+ "Width of an Integer Type". Remove inaccurate statement regarding
+ lack of C language facilities for determining width of integer
+ types, and reorder content to improve flow and context of
+ discussion.
+
+2017-08-10 Rical Jasan <ricaljasan@pacific.net>
+
* lang.texi (va_copy): Change standard from ISO to C99.
(__va_copy): Add standard and header annotation.
Update description for clarity of origins and current use.
diff --git a/manual/lang.texi b/manual/lang.texi
index d8c4bd7f69..ca90a59f8f 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -609,48 +609,17 @@ which give you this information in full detail.
@end menu
@node Width of Type
-@subsection Computing the Width of an Integer Data Type
+@subsection Width of an Integer Type
@cindex integer type width
@cindex width of integer type
@cindex type measurements, integer
-
-The most common reason that a program needs to know how many bits are in
-an integer type is for using an array of @code{long int} as a bit vector.
-You can access the bit at index @var{n} with
-
-@smallexample
-vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
-@end smallexample
-
-@noindent
-provided you define @code{LONGBITS} as the number of bits in a
-@code{long int}.
-
@pindex limits.h
-There is no operator in the C language that can give you the number of
-bits in an integer data type. But you can compute it from the macro
-@code{CHAR_BIT}, defined in the header file @file{limits.h}.
-
-@deftypevr Macro int CHAR_BIT
-@standards{C90, limits.h}
-This is the number of bits in a @code{char}. POSIX.1-2001 requires
-this to be 8.
-You can compute the number of bits in any data type @var{type} like
-this:
-
-@smallexample
-sizeof (@var{type}) * CHAR_BIT
-@end smallexample
-@end deftypevr
-
-That expression includes padding bits as well as value and sign bits.
-On all systems supported by @theglibc{}, standard integer types other
-than @code{_Bool} do not have any padding bits. TS 18661-1:2014
-defines additional macros for the width of integer types (the number
-of value and sign bits); these macros can also be used in @code{#if}
-preprocessor directives, whereas @code{sizeof} cannot. The following
-macros are defined in @file{limits.h}.
+TS 18661-1:2014 defines macros for the width of integer types (the
+number of value and sign bits). One benefit of these macros is they
+can be used in @code{#if} preprocessor directives, whereas
+@code{sizeof} cannot. The following macros are defined in
+@file{limits.h}.
@vtable @code
@item CHAR_WIDTH
@@ -665,7 +634,6 @@ macros are defined in @file{limits.h}.
@itemx LLONG_WIDTH
@itemx ULLONG_WIDTH
@standards{ISO, limits.h}
-
These are the widths of the types @code{char}, @code{signed char},
@code{unsigned char}, @code{short int}, @code{unsigned short int},
@code{int}, @code{unsigned int}, @code{long int}, @code{unsigned long
@@ -675,7 +643,7 @@ respectively.
Further such macros are defined in @file{stdint.h}. Apart from those
for types specified by width (@pxref{Integers}), the following are
-defined.
+defined:
@vtable @code
@item INTPTR_WIDTH
@@ -686,12 +654,43 @@ defined.
@itemx WCHAR_WIDTH
@itemx WINT_WIDTH
@standards{ISO, stdint.h}
-
These are the widths of the types @code{intptr_t}, @code{uintptr_t},
@code{ptrdiff_t}, @code{sig_atomic_t}, @code{size_t}, @code{wchar_t}
and @code{wint_t}, respectively.
@end vtable
+A common reason that a program needs to know how many bits are in an
+integer type is for using an array of @code{unsigned long int} as a
+bit vector. You can access the bit at index @var{n} with:
+
+@smallexample
+vector[@var{n} / ULONG_WIDTH] & (1UL << (@var{n} % ULONG_WIDTH))
+@end smallexample
+
+Before @code{ULONG_WIDTH} was a part of the C language,
+@code{CHAR_BIT} was used to compute the number of bits in an integer
+data type.
+
+@deftypevr Macro int CHAR_BIT
+@standards{C90, limits.h}
+This is the number of bits in a @code{char}. POSIX.1-2001 requires
+this to be 8.
+@end deftypevr
+
+The number of bits in any data type @var{type} can be computed like
+this:
+
+@smallexample
+sizeof (@var{type}) * CHAR_BIT
+@end smallexample
+
+That expression includes padding bits as well as value and sign bits.
+On all systems supported by @theglibc{}, standard integer types other
+than @code{_Bool} do not have any padding bits.
+
+@strong{Portability Note:} One cannot actually easily compute the
+number of usable bits in a portable manner.
+
@node Range of Type
@subsection Range of an Integer Type
@cindex integer type range