Put a @table around @include summary.out.
[kopensolaris-gnu/glibc.git] / manual / =limits.texinfo
1 @node Representation Limits
2 @chapter Representation Limits
3
4 This chapter contains information about constants and parameters that
5 characterize the representation of the various integer and
6 floating-point types supported by the GNU C library.
7
8 @menu
9 * Integer Representation Limits::
10 * Floating-Point Limits::
11 @end menu
12
13 @node Integer Representation Limits
14 @section Integer Representation Limits
15 @cindex integer representation limits
16 @cindex representation limits, integer
17 @cindex limits, integer representation
18
19 Sometimes it is necessary for programs to know about the internal
20 representation of various integer subtypes.  For example, if you want
21 your program to be careful not to overflow an @code{int} counter
22 variable, you need to know what the largest representable value that
23 fits in an @code{int} is.  These kinds of parameters can vary from
24 compiler to compiler and machine to machine.  Another typical use of
25 this kind of parameter is in conditionalizing data structure definitions
26 with @samp{#ifdef} to select the most appropriate integer subtype that
27 can represent the required range of values.
28
29 Macros representing the minimum and maximum limits of the integer types
30 are defined in the header file @file{limits.h}.  The values of these
31 macros are all integer constant expressions.
32 @pindex limits.h
33
34 @comment limits.h
35 @comment ANSI
36 @deftypevr Macro int CHAR_BIT
37 This is the number of bits in a @code{char}, usually eight.
38 @end deftypevr
39
40 @comment limits.h
41 @comment ANSI
42 @deftypevr Macro int SCHAR_MIN
43 This is the minimum value that can be represented by a @code{signed char}.
44 @end deftypevr
45
46 @comment limits.h
47 @comment ANSI
48 @deftypevr Macro int SCHAR_MAX
49 This is the maximum value that can be represented by a @code{signed char}.
50 @end deftypevr
51
52 @comment limits.h
53 @comment ANSI
54 @deftypevr Macro int UCHAR_MAX
55 This is the maximum value that can be represented by a @code{unsigned char}.
56 (The minimum value of an @code{unsigned char} is zero.)
57 @end deftypevr
58
59 @comment limits.h
60 @comment ANSI
61 @deftypevr Macro int CHAR_MIN
62 This is the minimum value that can be represented by a @code{char}.
63 It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero
64 otherwise.
65 @end deftypevr
66
67 @comment limits.h
68 @comment ANSI
69 @deftypevr Macro int CHAR_MAX
70 This is the maximum value that can be represented by a @code{char}.
71 It's equal to @code{SCHAR_MAX} if @code{char} is signed, or
72 @code{UCHAR_MAX} otherwise.
73 @end deftypevr
74
75 @comment limits.h
76 @comment ANSI
77 @deftypevr Macro int SHRT_MIN
78 This is the minimum value that can be represented by a @code{signed
79 short int}.  On most machines that the GNU C library runs on,
80 @code{short} integers are 16-bit quantities.
81 @end deftypevr
82
83 @comment limits.h
84 @comment ANSI
85 @deftypevr Macro int SHRT_MAX
86 This is the maximum value that can be represented by a @code{signed
87 short int}.
88 @end deftypevr
89
90 @comment limits.h
91 @comment ANSI
92 @deftypevr Macro int USHRT_MAX
93 This is the maximum value that can be represented by an @code{unsigned
94 short int}.  (The minimum value of an @code{unsigned short int} is zero.)
95 @end deftypevr
96
97 @comment limits.h
98 @comment ANSI
99 @deftypevr Macro int INT_MIN
100 This is the minimum value that can be represented by a @code{signed
101 int}.  On most machines that the GNU C system runs on, an @code{int} is
102 a 32-bit quantity.
103 @end deftypevr
104
105 @comment limits.h
106 @comment ANSI
107 @deftypevr Macro int INT_MAX
108 This is the maximum value that can be represented by a @code{signed
109 int}.
110 @end deftypevr
111
112 @comment limits.h
113 @comment ANSI
114 @deftypevr Macro {unsigned int} UINT_MAX
115 This is the maximum value that can be represented by an @code{unsigned
116 int}.  (The minimum value of an @code{unsigned int} is zero.)
117 @end deftypevr
118
119 @comment limits.h
120 @comment ANSI
121 @deftypevr Macro {long int} LONG_MIN
122 This is the minimum value that can be represented by a @code{signed long
123 int}.  On most machines that the GNU C system runs on, @code{long}
124 integers are 32-bit quantities, the same size as @code{int}.
125 @end deftypevr
126
127 @comment limits.h
128 @comment ANSI
129 @deftypevr Macro {long int} LONG_MAX
130 This is the maximum value that can be represented by a @code{signed long
131 int}.
132 @end deftypevr
133
134 @comment limits.h
135 @comment ANSI
136 @deftypevr Macro {unsigned long int} ULONG_MAX
137 This is the maximum value that can be represented by an @code{unsigned
138 long int}.  (The minimum value of an @code{unsigned long int} is zero.)
139 @end deftypevr
140
141 @strong{Incomplete:}  There should be corresponding limits for the GNU
142 C Compiler's @code{long long} type, too.  (But they are not now present
143 in the header file.)
144
145 The header file @file{limits.h} also defines some additional constants
146 that parameterize various operating system and file system limits.  These
147 constants are described in @ref{System Parameters} and @ref{File System
148 Parameters}.
149 @pindex limits.h
150
151
152 @node Floating-Point Limits 
153 @section Floating-Point Limits
154 @cindex floating-point number representation
155 @cindex representation, floating-point number
156 @cindex limits, floating-point representation
157
158 Because floating-point numbers are represented internally as approximate
159 quantities, algorithms for manipulating floating-point data often need
160 to be parameterized in terms of the accuracy of the representation.
161 Some of the functions in the C library itself need this information; for
162 example, the algorithms for printing and reading floating-point numbers
163 (@pxref{Input/Output on Streams}) and for calculating trigonometric and
164 irrational functions (@pxref{Mathematics}) use information about the
165 underlying floating-point representation to avoid round-off error and
166 loss of accuracy.  User programs that implement numerical analysis
167 techniques also often need to be parameterized in this way in order to
168 minimize or compute error bounds.
169
170 The specific representation of floating-point numbers varies from
171 machine to machine.  The GNU C library defines a set of parameters which
172 characterize each of the supported floating-point representations on a
173 particular system.
174
175 @menu
176 * Floating-Point Representation::       Definitions of terminology.
177 * Floating-Point Parameters::           Descriptions of the library facilities.
178 * IEEE Floating-Point::                 An example of a common representation.
179 @end menu
180
181 @node Floating-Point Representation
182 @subsection Floating-Point Representation
183
184 This section introduces the terminology used to characterize the
185 representation of floating-point numbers.
186
187 You are probably already familiar with most of these concepts in terms
188 of scientific or exponential notation for floating-point numbers.  For
189 example, the number @code{123456.0} could be expressed in exponential
190 notation as @code{1.23456e+05}, a shorthand notation indicating that the
191 mantissa @code{1.23456} is multiplied by the base @code{10} raised to
192 power @code{5}.
193
194 More formally, the internal representation of a floating-point number
195 can be characterized in terms of the following parameters:
196
197 @itemize @bullet
198 @item
199 The @dfn{sign} is either @code{-1} or @code{1}.
200 @cindex sign (of floating-point number)
201
202 @item
203 The @dfn{base} or @dfn{radix} for exponentiation; an integer greater
204 than @code{1}.  This is a constant for the particular representation.
205 @cindex base (of floating-point number)
206 @cindex radix (of floating-point number)
207
208 @item
209 The @dfn{exponent} to which the base is raised.  The upper and lower
210 bounds of the exponent value are constants for the particular
211 representation.
212 @cindex exponent (of floating-point number)
213
214 Sometimes, in the actual bits representing the floating-point number,
215 the exponent is @dfn{biased} by adding a constant to it, to make it
216 always be represented as an unsigned quantity.  This is only important
217 if you have some reason to pick apart the bit fields making up the
218 floating-point number by hand, which is something for which the GNU
219 library provides no support.  So this is ignored in the discussion that
220 follows.
221 @cindex bias (of floating-point number exponent)
222
223 @item
224 The value of the @dfn{mantissa} or @dfn{significand}, which is an
225 unsigned integer.
226 @cindex mantissa (of floating-point number)
227 @cindex significand (of floating-point number)
228
229 @item 
230 The @dfn{precision} of the mantissa.  If the base of the representation
231 is @var{b}, then the precision is the number of base-@var{b} digits in
232 the mantissa.  This is a constant for the particular representation.
233
234 Many floating-point representations have an implicit @dfn{hidden bit} in
235 the mantissa.  Any such hidden bits are counted in the precision.
236 Again, the GNU library provides no facilities for dealing with such low-level
237 aspects of the representation.
238 @cindex precision (of floating-point number)
239 @cindex hidden bit (of floating-point number mantissa)
240 @end itemize
241
242 The mantissa of a floating-point number actually represents an implicit
243 fraction whose denominator is the base raised to the power of the
244 precision.  Since the largest representable mantissa is one less than
245 this denominator, the value of the fraction is always strictly less than
246 @code{1}.  The mathematical value of a floating-point number is then the
247 product of this fraction; the sign; and the base raised to the exponent.
248
249 If the floating-point number is @dfn{normalized}, the mantissa is also
250 greater than or equal to the base raised to the power of one less
251 than the precision (unless the number represents a floating-point zero,
252 in which case the mantissa is zero).  The fractional quantity is
253 therefore greater than or equal to @code{1/@var{b}}, where @var{b} is
254 the base.
255 @cindex normalized floating-point number
256
257 @node Floating-Point Parameters
258 @subsection Floating-Point Parameters
259
260 @strong{Incomplete:}  This section needs some more concrete examples
261 of what these parameters mean and how to use them in a program.
262
263 These macro definitions can be accessed by including the header file
264 @file{float.h} in your program.
265 @pindex float.h
266
267 Macro names starting with @samp{FLT_} refer to the @code{float} type,
268 while names beginning with @samp{DBL_} refer to the @code{double} type
269 and names beginning with @samp{LDBL_} refer to the @code{long double}
270 type.  (In implementations that do not support @code{long double} as
271 a distinct data type, the values for those constants are the same
272 as the corresponding constants for the @code{double} type.)@refill
273 @cindex @code{float} representation limits
274 @cindex @code{double} representation limits
275 @cindex @code{long double} representation limits
276
277 Of these macros, only @code{FLT_RADIX} is guaranteed to be a constant
278 expression.  The other macros listed here cannot be reliably used in
279 places that require constant expressions, such as @samp{#if}
280 preprocessing directives or array size specifications.
281
282 Although the ANSI C standard specifies minimum and maximum values for
283 most of these parameters, the GNU C implementation uses whatever
284 floating-point representations are supported by the underlying hardware.
285 So whether GNU C actually satisfies the ANSI C requirements depends on
286 what machine it is running on.
287
288 @comment float.h
289 @comment ANSI
290 @deftypevr Macro int FLT_ROUNDS
291 This value characterizes the rounding mode for floating-point addition.
292 The following values indicate standard rounding modes:
293
294 @table @code
295 @item -1
296 The mode is indeterminable.
297 @item 0
298 Rounding is towards zero.
299 @item 1
300 Rounding is to the nearest number.
301 @item 2
302 Rounding is towards positive infinity.
303 @item 3
304 Rounding is towards negative infinity.
305 @end table
306
307 @noindent
308 Any other value represents a machine-dependent nonstandard rounding
309 mode.
310 @end deftypevr
311
312 @comment float.h
313 @comment ANSI
314 @deftypevr Macro int FLT_RADIX
315 This is the value of the base, or radix, of exponent representation.
316 This is guaranteed to be a constant expression, unlike the other macros
317 described in this section.
318 @end deftypevr
319
320 @comment float.h
321 @comment ANSI
322 @deftypevr Macro int FLT_MANT_DIG
323 This is the number of base-@code{FLT_RADIX} digits in the floating-point
324 mantissa for the @code{float} data type.
325 @end deftypevr
326
327 @comment float.h
328 @comment ANSI
329 @deftypevr Macro int DBL_MANT_DIG
330 This is the number of base-@code{FLT_RADIX} digits in the floating-point
331 mantissa for the @code{double} data type.
332 @end deftypevr
333
334 @comment float.h
335 @comment ANSI
336 @deftypevr Macro int LDBL_MANT_DIG
337 This is the number of base-@code{FLT_RADIX} digits in the floating-point
338 mantissa for the @code{long double} data type.
339 @end deftypevr
340
341 @comment float.h
342 @comment ANSI
343 @deftypevr Macro int FLT_DIG
344 This is the number of decimal digits of precision for the @code{float}
345 data type.  Technically, if @var{p} and @var{b} are the precision and
346 base (respectively) for the representation, then the decimal precision
347 @var{q} is the maximum number of decimal digits such that any floating
348 point number with @var{q} base 10 digits can be rounded to a floating
349 point number with @var{p} base @var{b} digits and back again, without
350 change to the @var{q} decimal digits.
351
352 The value of this macro is guaranteed to be at least @code{6}.
353 @end deftypevr
354
355 @comment float.h
356 @comment ANSI
357 @deftypevr Macro int DBL_DIG
358 This is similar to @code{FLT_DIG}, but is for the @code{double} data
359 type.  The value of this macro is guaranteed to be at least @code{10}.
360 @end deftypevr
361
362 @comment float.h
363 @comment ANSI
364 @deftypevr Macro int LDBL_DIG
365 This is similar to @code{FLT_DIG}, but is for the @code{long double}
366 data type.  The value of this macro is guaranteed to be at least
367 @code{10}.
368 @end deftypevr
369
370 @comment float.h
371 @comment ANSI
372 @deftypevr Macro int FLT_MIN_EXP
373 This is the minimum negative integer such that the mathematical value
374 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
375 normalized floating-point number of type @code{float}.  In terms of the
376 actual implementation, this is just the smallest value that can be
377 represented in the exponent field of the number.
378 @end deftypevr
379
380 @comment float.h
381 @comment ANSI
382 @deftypevr Macro int DBL_MIN_EXP
383 This is similar to @code{FLT_MIN_EXP}, but is for the @code{double} data
384 type.
385 @end deftypevr
386
387 @comment float.h
388 @comment ANSI
389 @deftypevr Macro int LDBL_MIN_EXP
390 This is similar to @code{FLT_MIN_EXP}, but is for the @code{long double}
391 data type.
392 @end deftypevr
393
394 @comment float.h
395 @comment ANSI
396 @deftypevr Macro int FLT_MIN_10_EXP
397 This is the minimum negative integer such that the mathematical value
398 @code{10} raised to this power minus 1 can be represented as a
399 normalized floating-point number of type @code{float}.  This is
400 guaranteed to be no greater than @code{-37}.
401 @end deftypevr
402
403 @comment float.h
404 @comment ANSI
405 @deftypevr Macro int DBL_MIN_10_EXP
406 This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{double}
407 data type.
408 @end deftypevr
409
410 @comment float.h
411 @comment ANSI
412 @deftypevr Macro int LDBL_MIN_10_EXP
413 This is similar to @code{FLT_MIN_10_EXP}, but is for the @code{long
414 double} data type.
415 @end deftypevr
416
417
418
419 @comment float.h
420 @comment ANSI
421 @deftypevr Macro int FLT_MAX_EXP
422 This is the maximum negative integer such that the mathematical value
423 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
424 floating-point number of type @code{float}.  In terms of the actual
425 implementation, this is just the largest value that can be represented
426 in the exponent field of the number.
427 @end deftypevr
428
429 @comment float.h
430 @comment ANSI
431 @deftypevr Macro int DBL_MAX_EXP
432 This is similar to @code{FLT_MAX_EXP}, but is for the @code{double} data
433 type.
434 @end deftypevr
435
436 @comment float.h
437 @comment ANSI
438 @deftypevr Macro int LDBL_MAX_EXP
439 This is similar to @code{FLT_MAX_EXP}, but is for the @code{long double}
440 data type.
441 @end deftypevr
442
443 @comment float.h
444 @comment ANSI
445 @deftypevr Macro int FLT_MAX_10_EXP
446 This is the maximum negative integer such that the mathematical value
447 @code{10} raised to this power minus 1 can be represented as a
448 normalized floating-point number of type @code{float}.  This is
449 guaranteed to be at least @code{37}.
450 @end deftypevr
451
452 @comment float.h
453 @comment ANSI
454 @deftypevr Macro int DBL_MAX_10_EXP
455 This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{double}
456 data type.
457 @end deftypevr
458
459 @comment float.h
460 @comment ANSI
461 @deftypevr Macro int LDBL_MAX_10_EXP
462 This is similar to @code{FLT_MAX_10_EXP}, but is for the @code{long
463 double} data type.
464 @end deftypevr
465
466
467 @comment float.h
468 @comment ANSI
469 @deftypevr Macro double FLT_MAX
470 The value of this macro is the maximum representable floating-point
471 number of type @code{float}, and is guaranteed to be at least
472 @code{1E+37}.
473 @end deftypevr
474
475 @comment float.h
476 @comment ANSI
477 @deftypevr Macro double DBL_MAX
478 The value of this macro is the maximum representable floating-point
479 number of type @code{double}, and is guaranteed to be at least
480 @code{1E+37}.
481 @end deftypevr
482
483 @comment float.h
484 @comment ANSI
485 @deftypevr Macro {long double} LDBL_MAX
486 The value of this macro is the maximum representable floating-point
487 number of type @code{long double}, and is guaranteed to be at least
488 @code{1E+37}.
489 @end deftypevr
490
491
492 @comment float.h
493 @comment ANSI
494 @deftypevr Macro double FLT_MIN
495 The value of this macro is the minimum normalized positive
496 floating-point number that is representable by type @code{float}, and is
497 guaranteed to be no more than @code{1E-37}.
498 @end deftypevr
499
500 @comment float.h
501 @comment ANSI
502 @deftypevr Macro double DBL_MIN
503 The value of this macro is the minimum normalized positive
504 floating-point number that is representable by type @code{double}, and
505 is guaranteed to be no more than @code{1E-37}.
506 @end deftypevr
507
508 @comment float.h
509 @comment ANSI
510 @deftypevr Macro {long double} LDBL_MIN
511 The value of this macro is the minimum normalized positive
512 floating-point number that is representable by type @code{long double},
513 and is guaranteed to be no more than @code{1E-37}.
514 @end deftypevr
515
516
517 @comment float.h
518 @comment ANSI
519 @deftypevr Macro double FLT_EPSILON
520 This is the minimum positive floating-point number of type @code{float}
521 such that @code{1.0 + FLT_EPSILON != 1.0} is true.  It's guaranteed to
522 be no greater than @code{1E-5}.
523 @end deftypevr
524
525 @comment float.h
526 @comment ANSI
527 @deftypevr Macro double DBL_EPSILON
528 This is similar to @code{FLT_EPSILON}, but is for the @code{double}
529 type.  The maximum value is @code{1E-9}.
530 @end deftypevr
531
532 @comment float.h
533 @comment ANSI
534 @deftypevr Macro {long double} LDBL_EPSILON
535 This is similar to @code{FLT_EPSILON}, but is for the @code{long double}
536 type.  The maximum value is @code{1E-9}.
537 @end deftypevr
538
539
540 @node IEEE Floating Point
541 @subsection IEEE Floating Point
542 @cindex IEEE floating-point representation 
543 @cindex floating-point, IEEE
544 @cindex IEEE Std 754
545
546
547 Here is an example showing how these parameters work for a common
548 floating point representation, specified by the @cite{IEEE Standard for
549 Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985)}.  Nearly
550 all computers today use this format.
551
552 The IEEE single-precision float representation uses a base of 2.  There
553 is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total
554 precision is 24 base-2 digits), and an 8-bit exponent that can represent
555 values in the range -125 to 128, inclusive.
556
557 So, for an implementation that uses this representation for the
558 @code{float} data type, appropriate values for the corresponding
559 parameters are:
560
561 @example
562 FLT_RADIX                             2
563 FLT_MANT_DIG                         24
564 FLT_DIG                               6
565 FLT_MIN_EXP                        -125
566 FLT_MIN_10_EXP                      -37
567 FLT_MAX_EXP                         128
568 FLT_MAX_10_EXP                      +38
569 FLT_MIN                 1.17549435E-38F
570 FLT_MAX                 3.40282347E+38F
571 FLT_EPSILON             1.19209290E-07F
572 @end example
573
574 Here are the values for the @code{double} data type:
575
576 @example
577 DBL_MANT_DIG                         53
578 DBL_DIG                              15
579 DBL_MIN_EXP                       -1021
580 DBL_MIN_10_EXP                     -307
581 DBL_MAX_EXP                        1024
582 DBL_MAX_10_EXP                      308
583 DBL_MAX         1.7976931348623157E+308
584 DBL_MIN         2.2250738585072014E-308
585 DBL_EPSILON     2.2204460492503131E-016
586 @end example