Miscellaneous corrections after 1st proofreading.
[kopensolaris-gnu/glibc.git] / manual / lang.texi
1 @node Language Features, Library Summary, System Configuration, Top
2 @c !!! this title is too long -- it gets 2 lines in contents
3 @appendix Library Facilities that are Part of the C Language
4
5 Some of the facilities implemented by the C library really should be
6 thought of as parts of the C language itself.  These facilities ought to
7 be documented in the C Language Manual, not in the library manual; but
8 since we don't have the language manual yet, and documentation for these
9 features has been written, we are publishing it here.
10
11 @menu
12 * Consistency Checking::        Using @code{assert} to abort if
13                                  something ``impossible'' happens.
14 * Variadic Functions::          Defining functions with varying numbers
15                                  of args. 
16 * Null Pointer Constant::       The macro @code{NULL}.
17 * Important Data Types::        Data types for object sizes.
18 * Data Type Measurements::      Parameters of data type representations.
19 @end menu
20
21 @node Consistency Checking
22 @section Explicitly Checking Internal Consistency
23 @cindex consistency checking
24 @cindex impossible events
25 @cindex assertions
26
27 When you're writing a program, it's often a good idea to put in checks
28 at strategic places for ``impossible'' errors or violations of basic
29 assumptions.  These checks are helpful in debugging problems due to
30 misunderstandings between different parts of the program.
31
32 @pindex assert.h
33 The @code{assert} macro, defined in the header file @file{assert.h},
34 provides a convenient way to abort the program while printing a message
35 about where in the program the error was detected.
36
37 @vindex NDEBUG
38 Once you think your program is debugged, you can disable the error
39 checks performed by the @code{assert} macro by recompiling with the
40 macro @code{NDEBUG} defined.  This means you don't actually have to
41 change the program source code to disable these checks.
42
43 But disabling these consistency checks is undesirable unless they make
44 the program significantly slower.  All else being equal, more error
45 checking is good no matter who is running the program.  A wise user
46 would rather have a program crash, visibly, than have it return nonsense
47 without indicating anything might be wrong.
48
49 @comment assert.h
50 @comment ANSI
51 @deftypefn Macro void assert (int @var{expression})
52 Verify the programmer's belief that @var{expression} should be nonzero
53 at this point in the program.
54
55 If @code{NDEBUG} is not defined, @code{assert} tests the value of
56 @var{expression}.  If it is false (zero), @code{assert} aborts the
57 program (@pxref{Aborting a Program}) after printing a message of the
58 form:
59
60 @example
61 @file{@var{file}}:@var{linenum}: Assertion `@var{expression}' failed.
62 @end example
63
64 @noindent
65 on the standard error stream @code{stderr} (@pxref{Standard Streams}).
66 The filename and line number are taken from the C preprocessor macros
67 @code{__FILE__} and @code{__LINE__} and specify where the call to
68 @code{assert} was written.
69
70 If the preprocessor macro @code{NDEBUG} is defined at the point where
71 @file{assert.h} is included, the @code{assert} macro is defined to do
72 absolutely nothing.
73
74 @strong{Warning:} Even the argument expression @var{expression} is not
75 evaluated if @code{NDEBUG} is in effect.  So never use @code{assert}
76 with arguments that involve side effects.  For example, @code{assert
77 (++i > 0);} is a bad idea, because @code{i} will not be incremented if
78 @code{NDEBUG} is defined.
79 @end deftypefn
80
81 @strong{Usage note:} The @code{assert} facility is designed for
82 detecting @emph{internal inconsistency}; it is not suitable for
83 reporting invalid input or improper usage by @emph{the user} of the
84 program.
85
86 The information in the diagnostic messages printd by the @code{assert}
87 macro is intended to to help you, the programmer, track down the cause
88 of a bug, but is not really useful for telling a user of your program
89 why his or her input was invalid or why a command could not be carried
90 out.  So you can't use @code{assert} to print the error messages for
91 these eventualities.
92
93 What's more, your program should not abort when given invalid input, as
94 @code{assert} would do---it should exit with nonzero status (@pxref{Exit
95 Status}) after printing its error messages, or perhaps read another
96 command or move on to the next input file.
97
98 @xref{Error Messages}, for information on printing error messages for
99 problems that @emph{do not} represent bugs in the program.
100
101
102 @node Variadic Functions
103 @section Variadic Functions
104 @cindex variable number of arguments
105 @cindex variadic functions
106 @cindex optional arguments
107
108 ANSI C defines a syntax for declaring a function to take a variable
109 number or type of arguments.  (Such functions are referred to as
110 @dfn{varargs functions} or @dfn{variadic functions}.)  However, the
111 language itself provides no mechanism for such functions to access their
112 non-required arguments; instead, you use the variable arguments macros
113 defined in @file{stdarg.h}.
114
115 This section describes how to declare variadic functions, how to write
116 them, and how to call them properly.
117
118 @strong{Compatibility Note:} Many older C dialects provide a similar,
119 but incompatible, mechanism for defining functions with variable numbers
120 of arguments, using @file{varargs.h}.
121
122 @menu
123 * Why Variadic::                Reasons for making functions take
124                                  variable arguments. 
125 * How Variadic::                How to define and call variadic functions.
126 * Variadic Example::            A complete example.
127 @end menu
128
129 @node Why Variadic
130 @subsection Why Variadic Functions are Used
131
132 Ordinary C functions take a fixed number of arguments.  When you define
133 a function, you specify the data type for each argument.  Every call to
134 the function should supply the expected number of arguments, with types
135 that can be converted to the specified ones.  Thus, if the function foo
136 is declared with @code{int foo (int, char *);} then you must call it
137 with two arguments, a number (any kind will do) and a string pointer.
138
139 But some functions perform operations that can meaningfully accept an
140 unlimited number of arguments.
141
142 In some cases a function can handle any number of values by operating on
143 all of them as a block.  For example, consider a function that allocates
144 a one-dimensional array with @code{malloc} to hold a specified set of
145 values.  This operation makes sense for any number of values, as long as
146 the length of the array corresponds to that number.  Without facilities
147 for variable arguments, you would have to define a separate function for
148 each possible array size.
149
150 The library function @code{printf} (@pxref{Formatted Output}) is an
151 example of another class of function where variable arguments are
152 useful.  This function prints its arguments (which can vary in type as
153 well as number) under the control of a format template string.
154
155 These are good reasons to define a @dfn{variadic} function which can
156 handle as many arguments as the caller chooses to pass.
157
158 Some functions such as @code{open} take a fixed set of arguments, but
159 occasionally ignore the last few.  Strict adherence to ANSI C requires
160 these functions to be defined as variadic; in practice, however, the GNU
161 C compiler and most other C compilers let you define such a function to
162 take a fixed set of arguments---the most it can ever use---and then only
163 @emph{declare} the function as variadic (or not declare its arguments
164 at all!).
165
166 @node How Variadic
167 @subsection How Variadic Functions are Defined and Used
168
169 Defining and using a variadic function involves three steps:
170
171 @itemize @bullet
172 @item
173 @emph{Define} the function as variadic, using an ellipsis
174 (@samp{@dots{}}) in the argument list, and using special macros to
175 access the variable arguments.  @xref{Receiving Arguments}.
176
177 @item
178 @emph{Declare} the function as variadic, using a prototype with an
179 ellipsis (@samp{@dots{}}), in all the files which call it.
180 @xref{Variadic Prototypes}.
181
182 @item
183 @emph{Call} the function by writing the fixed arguments followed by the
184 additional variable arguments.  @xref{Calling Variadics}.
185 @end itemize
186
187 @menu
188 * Variadic Prototypes::  How to make a prototype for a function
189                           with variable arguments.
190 * Receiving Arguments::  Steps you must follow to access the
191                           optional argument values.
192 * How Many Arguments::   How to decide whether there are more arguments. 
193 * Calling Variadics::    Things you need to know about calling
194                           variable arguments functions.
195 * Argument Macros::      Detailed specification of the macros
196                           for accessing variable arguments.
197 @end menu
198
199 @node Variadic Prototypes
200 @subsubsection Syntax for Variable Arguments
201 @cindex function prototypes (variadic)
202 @cindex prototypes for variadic functions
203 @cindex variadic function prototypes
204
205 A function that accepts a variable number of arguments must be declared
206 with a prototype that says so.   You write the fixed arguments as usual,
207 and then tack on @samp{@dots{}} to indicate the possibility of 
208 additional arguments.  The syntax of ANSI C requires at least one fixed
209 argument before the @samp{@dots{}}.  For example,
210
211 @example
212 int 
213 func (const char *a, int b, @dots{})
214 @{
215   @dots{}
216 @}      
217 @end example
218
219 @noindent
220 outlines a definition of a function @code{func} which returns an
221 @code{int} and takes two required arguments, a @code{const char *} and
222 an @code{int}.  These are followed by any number of anonymous
223 arguments.
224
225 @strong{Portability note:} For some C compilers, the last required
226 argument must not be declared @code{register} in the function
227 definition.  Furthermore, this argument's type must be
228 @dfn{self-promoting}: that is, the default promotions must not change
229 its type.  This rules out array and function types, as well as
230 @code{float}, @code{char} (whether signed or not) and @code{short}
231 (whether signed or not).  This is actually an ANSI C requirement.
232
233 @node Receiving Arguments
234 @subsubsection Receiving the Argument Values
235 @cindex variadic function argument access
236 @cindex arguments (variadic functions)
237
238 Ordinary fixed arguments have individual names, and you can use these
239 names to access their values.  But optional arguments have no
240 names---nothing but @samp{@dots{}}.  How can you access them?
241
242 @pindex stdarg.h
243 The only way to access them is sequentially, in the order they were
244 written, and you must use special macros from @file{stdarg.h} in the
245 following three step process:
246
247 @enumerate
248 @item
249 You initialize an argument pointer variable of type @code{va_list} using
250 @code{va_start}.  The argument pointer when initialized points to the
251 first optional argument.
252
253 @item
254 You access the optional arguments by successive calls to @code{va_arg}.
255 The first call to @code{va_arg} gives you the first optional argument,
256 the next call gives you the second, and so on.
257
258 You can stop at any time if you wish to ignore any remaining optional
259 arguments.  It is perfectly all right for a function to access fewer
260 arguments than were supplied in the call, but you will get garbage
261 values if you try to access too many arguments.
262
263 @item
264 You indicate that you are finished with the argument pointer variable by
265 calling @code{va_end}.
266
267 (In practice, with most C compilers, calling @code{va_end} does nothing
268 and you do not really need to call it.  This is always true in the GNU C
269 compiler.  But you might as well call @code{va_end} just in case your
270 program is someday compiled with a peculiar compiler.)
271 @end enumerate
272
273 @xref{Argument Macros}, for the full definitions of @code{va_start}, 
274 @code{va_arg} and @code{va_end}.
275
276 Steps 1 and 3 must be performed in the function that accepts the
277 optional arguments.  However, you can pass the @code{va_list} variable
278 as an argument to another function and perform all or part of step 2
279 there.
280
281 You can perform the entire sequence of the three steps multiple times
282 within a single function invocation.  If you want to ignore the optional
283 arguments, you can do these steps zero times.
284
285 You can have more than one argument pointer variable if you like.  You
286 can initialize each variable with @code{va_start} when you wish, and
287 then you can fetch arguments with each argument pointer as you wish.
288 Each argument pointer variable will sequence through the same set of
289 argument values, but at its own pace.
290
291 @strong{Portability note:} With some compilers, once you pass an
292 argument pointer value to a subroutine, you must not keep using the same
293 argument pointer value after that subroutine returns.  For full
294 portability, you should just pass it to @code{va_end}.  This is actually
295 an ANSI C requirement, but most ANSI C compilers work happily
296 regardless.
297
298 @node How Many Arguments
299 @subsubsection How Many Arguments Were Supplied
300 @cindex number of arguments passed
301 @cindex how many arguments
302 @cindex arguments, how many
303
304 There is no general way for a function to determine the number and type
305 of the optional arguments it was called with.  So whoever designs the
306 function typically designs a convention for the caller to tell it how
307 many arguments it has, and what kind.  It is up to you to define an
308 appropriate calling convention for each variadic function, and write all
309 calls accordingly.
310
311 One kind of calling convention is to pass the number of optional
312 arguments as one of the fixed arguments.  This convention works provided
313 all of the optional arguments are of the same type.
314
315 A similar alternative is to have one of the required arguments be a bit
316 mask, with a bit for each possible purpose for which an optional
317 argument might be supplied.  You would test the bits in a predefined
318 sequence; if the bit is set, fetch the value of the next argument,
319 otherwise use a default value.
320
321 A required argument can be used as a pattern to specify both the number
322 and types of the optional arguments.  The format string argument to
323 @code{printf} is one example of this.
324
325 Another possibility is to pass an ``end marker'' value as the last
326 optional argument.  For example, for a function that manipulates an
327 arbitrary number of pointer arguments, a null pointer might indicate the
328 end of the argument list.  (This assumes that a null pointer isn't
329 otherwise meaningful to the function.)
330
331
332 @node Calling Variadics
333 @subsubsection Calling Variadic Functions
334 @cindex variadic functions, calling
335 @cindex calling variadic functions
336 @cindex declaring variadic functions
337
338 You don't have to write anything special when you call a variadic function.
339 Just write the arguments (required arguments, followed by optional ones)
340 inside parentheses, separated by commas, as usual.  But you should prepare
341 by declaring the function with a prototype, and you must know how the
342 argument values are converted.
343
344 In principle, functions that are @emph{defined} to be variadic must also
345 be @emph{declared} to be variadic using a function prototype whenever
346 you call them.  (@xref{Variadic Prototypes}, for how.)  This is because
347 some C compilers use a different calling convention to pass the same set
348 of argument values to a function depending on whether that function
349 takes variable arguments or fixed arguments.
350
351 In practice, the GNU C compiler always passes a given set of argument
352 types in the same way regardless of whether they are optional or
353 required.  So, as long as the argument types are self-promoting, you can
354 safely omit declaring them.  Usually it is a good idea to declare the
355 argument types for variadic functions, and indeed for all functions.
356 But there are a few functions which it is extremely convenient not to
357 have to declare as variadic---for example, @code{open} and
358 @code{printf}.
359
360 @cindex default argument promotions
361 @cindex argument promotion
362 Since the prototype doesn't specify types for optional arguments, in a
363 call to a variadic function the @dfn{default argument promotions} are
364 performed on the optional argument values.  This means the objects of
365 type @code{char} or @code{short int} (whether signed or not) are
366 promoted to either @code{int} or @code{unsigned int}, as appropriate;
367 and that objects of type @code{float} are promoted to type
368 @code{double}.  So, if the caller passes a @code{char} as an optional
369 argument, it is promoted to a @code{int}, and the function should get it
370 with @code{va_arg (@var{ap}, int)}.
371
372 Conversion of the required arguments is controlled by the function
373 prototype in the usual way: the argument expression is converted to the
374 declared argument type as if it were being assigned to a variable of
375 that type.
376
377 @node Argument Macros
378 @subsubsection Argument Access Macros
379
380 Here are descriptions of the macros used to retrieve variable arguments.
381 These macros are defined in the header file @file{stdarg.h}.
382 @pindex stdarg.h
383
384 @comment stdarg.h
385 @comment ANSI
386 @deftp {Data Type} va_list
387 The type @code{va_list} is used for argument pointer variables.
388 @end deftp
389
390 @comment stdarg.h
391 @comment ANSI
392 @deftypefn {Macro} void va_start (va_list @var{ap}, @var{last_required})
393 This macro initializes the argument pointer variable @var{ap} to point
394 to the first of the optional arguments of the current function;
395 @var{last_required} must be the last required argument to the function.
396 @end deftypefn
397
398 @comment stdarg.h
399 @comment ANSI
400 @deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type})
401 The @code{va_arg} macro returns the value of the next optional argument,
402 and modifies the value of @var{ap} to point to the subsequent argument.
403 Thus, successive uses of @code{va_arg} return successive optional 
404 arguments.
405
406 The type of the value returned by @code{va_arg} is @var{type} as
407 specified in the call.  @var{type} must be a self-promoting type (not
408 @code{char} or @code{short int} or @code{float}) that matches the type
409 of the actual argument.
410 @end deftypefn
411
412 @comment stdarg.h
413 @comment ANSI
414 @deftypefn {Macro} void va_end (va_list @var{ap})
415 This ends the use of @var{ap}.  After a @code{va_end} call, further
416 @code{va_arg} calls with the same @var{ap} may not work.  You should invoke
417 @code{va_end} before returning from the function in which @code{va_start}
418 was invoked with the same @var{ap} argument.
419
420 In the GNU C library, @code{va_end} does nothing, and you need not ever
421 use it except for reasons of portability.
422 @refill
423 @end deftypefn
424
425 @node Variadic Example
426 @subsection Example of a Variadic Function
427
428 Here is a complete sample function that accepts variable numbers of
429 arguments.  The first argument to the function is the count of remaining
430 arguments, which are added up and the result returned.  While trivial,
431 this function is sufficient to illustrate how to use the variable
432 arguments facility.
433
434 @comment Yes, this example has been tested.
435 @example
436 @include add.c.texi
437 @end example
438
439 @node Null Pointer Constant
440 @section Null Pointer Constant
441 @cindex null pointer constant
442
443 The null pointer constant is guaranteed not to point to any real object.
444 You can assign it to any pointer variable since it has type @code{void
445 *}.  The preferred way to write a null pointer constant is with
446 @code{NULL}.
447
448 @comment stddef.h
449 @comment ANSI
450 @deftypevr Macro {void *} NULL
451 This is a null pointer constant.
452 @end deftypevr
453
454 You can also use @code{0} or @code{(void *)0} as a null pointer
455 constant, but using @code{NULL} is cleaner because it makes the purpose
456 of the constant more evident.
457
458 If you use the null pointer constant as a function argument, then for
459 complete portability you should make sure that the function has a
460 prototype declaration.  Otherwise, if the target machine has two
461 different pointer representations, the compiler won't know which
462 representation to use for that argument.  You can avoid the problem by
463 explicitly casting the constant to the proper pointer type, but we
464 recommend instead adding a prototype for the function you are calling.
465
466 @node Important Data Types
467 @section Important Data Types
468
469 The result of subtracting two pointers in C is always an integer, but the
470 precise data type varies from C compiler to C compiler.  Likewise, the
471 data type of the result of @code{sizeof} also varies between compilers.
472 ANSI defines standard aliases for these two types, so you can refer to
473 them in a portable fashion.  They are defined in the header file 
474 @file{stddef.h}.
475 @pindex stddef.h
476
477 @comment stddef.h
478 @comment ANSI
479 @deftp {Data Type} ptrdiff_t
480 This is the signed integer type of the result of subtracting two
481 pointers.  For example, with the declaration @code{char *p1, *p2;}, the
482 expression @code{p2 - p1} is of type @code{ptrdiff_t}.  This will
483 probably be one of the standard signed integer types (@code{short int},
484 @code{int} or @code{long int}), but might be a nonstandard type that
485 exists only for this purpose.
486 @end deftp
487
488 @comment stddef.h
489 @comment ANSI
490 @deftp {Data Type} size_t
491 This is an unsigned integer type used to represent the sizes of objects.
492 The result of the @code{sizeof} operator is of this type, and functions
493 such as @code{malloc} (@pxref{Unconstrained Allocation}) and
494 @code{memcpy} (@pxref{Copying and Concatenation}) accept arguments of
495 this type to specify object sizes.
496
497 @strong{Usage Note:} @code{size_t} is the preferred way to declare any
498 arguments or variables that hold the size of an object.
499 @end deftp
500
501 In the GNU system @code{size_t} is equivalent to one of the types 
502 @code{unsigned int} and @code{unsigned long int}.  These types have
503 identical properties on the GNU system, and for most purposes, you
504 can use them interchangeably.  However, they are distinct as data types, 
505 which makes a difference in certain contexts.
506
507 For example, when you specify the type of a function argument in a
508 function prototype, it makes a difference which one you use.  If the
509 system header files declare @code{malloc} with an argument of type
510 @code{size_t} and you declare @code{malloc} with an argument of type
511 @code{unsigned int}, you will get a compilation error if @code{size_t}
512 happens to be @code{unsigned long int} on your system.  To avoid any
513 possibility of error, when a function argument or value is supposed to
514 have type @code{size_t}, never declare its type in any other way.
515
516 @strong{Compatibility Note:} Pre-ANSI C implementations generally used
517 @code{unsigned int} for representing object sizes and @code{int} for
518 pointer subtraction results.  They did not necessarily define either
519 @code{size_t} or @code{ptrdiff_t}.  Unix systems did define
520 @code{size_t}, in @file{sys/types.h}, but the definition was usually a
521 signed type.
522
523 @node Data Type Measurements
524 @section Data Type Measurements
525
526 Most of the time, if you choose the proper C data type for each object
527 in your program, you need not be concerned with just how it is
528 represented or how many bits it uses.  When you do need such
529 information, the C language itself does not provide a way to get it.
530 The header files @file{limits.h} and @file{float.h} contain macros
531 which give you this information in full detail.
532
533 @menu
534 * Width of Type::           How many bits does an integer type hold?
535 * Range of Type::           What are the largest and smallest values
536                              that an integer type can hold?
537 * Floating Type Macros::    Parameters that measure the floating point types. 
538 * Structure Measurement::   Getting measurements on structure types.
539 @end menu
540
541 @node Width of Type
542 @subsection Computing the Width of an Integer Data Type
543 @cindex integer type width
544 @cindex width of integer type
545 @cindex type measurements, integer
546
547 The most common reason that a program needs to know how many bits are in
548 an integer type is for using an array of @code{long} as a bit vector.
549 You can access the bit at index @var{n} with
550
551 @example
552 vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
553 @end example
554
555 @noindent
556 provided you define @code{LONGBITS} as the number of bits in a
557 @code{long}.
558
559 @pindex limits.h
560 There is no operator in the C language that can give you the number of
561 bits in an integer data type.  But you can compute it from the macro
562 @code{CHAR_BIT}, defined in the header file @file{limits.h}.
563
564 @table @code
565 @comment limits.h
566 @comment ANSI
567 @item CHAR_BIT
568 This is the number of bits in a @code{char}---eight, on most systems.
569 The value has type @code{int}.
570
571 You can compute the number of bits in any data type @var{type} like
572 this:
573
574 @example
575 sizeof (@var{type}) * CHAR_BIT
576 @end example
577 @end table
578
579 @node Range of Type
580 @subsection Range of an Integer Type
581 @cindex integer type range
582 @cindex range of integer type
583 @cindex limits, integer types
584
585 Suppose you need to store an integer value which can range from zero to
586 one million.  Which is the smallest type you can use?  There is no
587 general rule; it depends on the C compiler and target machine.  You can
588 use the @samp{MIN} and @samp{MAX} macros in @file{limits.h} to determine
589 which type will work.
590
591 Each signed integer type has a pair of macros which give the smallest
592 and largest values that it can hold.  Each unsigned integer type has one
593 such macro, for the maximum value; the minimum value is, of course,
594 zero.
595
596 The values of these macros are all integer constant expressions.  The
597 @samp{MAX} and @samp{MIN} macros for @code{char} and @code{short} types
598 have values of type @code{int}.  The @samp{MAX} and @samp{MIN} macros
599 for the other types have values of the same type described by the
600 macro---thus, @code{ULONG_MAX} has type @code{unsigned long int}.
601
602 @table @code
603 @comment limits.h
604 @comment ANSI
605 @item SCHAR_MIN
606 This is the minimum value that can be represented by a @code{signed char}.
607
608 @comment limits.h
609 @comment ANSI
610 @item SCHAR_MAX
611 @itemx UCHAR_MAX
612 These are the maximum values that can be represented by a @code{signed
613 char} and @code{unsigned char}, respectively.
614
615 @comment limits.h
616 @comment ANSI
617 @item CHAR_MIN
618 This is the minimum value that can be represented by a @code{char}.
619 It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero
620 otherwise.
621
622 @comment limits.h
623 @comment ANSI
624 @item CHAR_MAX
625 This is the maximum value that can be represented by a @code{char}.
626 It's equal to @code{SCHAR_MAX} if @code{char} is signed, or
627 @code{UCHAR_MAX} otherwise.
628
629 @comment limits.h
630 @comment ANSI
631 @item SHRT_MIN
632 This is the minimum value that can be represented by a @code{signed
633 short int}.  On most machines that the GNU C library runs on,
634 @code{short} integers are 16-bit quantities.
635
636 @comment limits.h
637 @comment ANSI
638 @item SHRT_MAX
639 @itemx USHRT_MAX
640 These are the maximum values that can be represented by a @code{signed
641 short int} and @code{unsigned short int}, respectively.
642
643 @comment limits.h
644 @comment ANSI
645 @item INT_MIN
646 This is the minimum value that can be represented by a @code{signed
647 int}.  On most machines that the GNU C system runs on, an @code{int} is
648 a 32-bit quantity.
649
650 @comment limits.h
651 @comment ANSI
652 @item INT_MAX
653 @itemx UINT_MAX
654 These are the maximum values that can be represented by a @code{signed
655 int} and @code{unsigned int}, respectively.
656
657 @comment limits.h
658 @comment ANSI
659 @item LONG_MIN
660 This is the minimum value that can be represented by a @code{signed long
661 int}.  On most machines that the GNU C system runs on, @code{long}
662 integers are 32-bit quantities, the same size as @code{int}.
663
664 @comment limits.h
665 @comment ANSI
666 @item LONG_MAX
667 @itemx ULONG_MAX
668 These are the maximum values that can be represented by a @code{signed
669 long int} and @code{unsigned long int}, respectively.
670
671 @comment limits.h
672 @comment GNU
673 @item LONG_LONG_MIN
674 This is the minimum value that can be represented by a @code{signed long
675 long int}.  On most machines that the GNU C system runs on, @code{long
676 long} integers are 64-bit quantities.
677
678 @comment limits.h
679 @comment GNU
680 @item LONG_LONG_MAX
681 @itemx ULONG_LONG_MAX
682 These are the maximum values that can be represented by a @code{signed
683 long long int} and @code{unsigned long long int}, respectively.
684 @end table
685
686 The header file @file{limits.h} also defines some additional constants
687 that parameterize various operating system and file system limits.  These
688 constants are described in @ref{System Configuration}.
689
690 @node Floating Type Macros
691 @subsection Floating Type Macros
692 @cindex floating type measurements
693 @cindex measurements of floating types
694 @cindex type measurements, floating
695 @cindex limits, floating types
696
697 The specific representation of floating point numbers varies from
698 machine to machine.  Because floating point numbers are represented
699 internally as approximate quantities, algorithms for manipulating
700 floating point data often need to take account of the precise details of
701 the machine's floating point representation.
702
703 Some of the functions in the C library itself need this information; for
704 example, the algorithms for printing and reading floating point numbers
705 (@pxref{I/O on Streams}) and for calculating trigonometric and
706 irrational functions (@pxref{Mathematics}) use it to avoid round-off
707 error and loss of accuracy.  User programs that implement numerical
708 analysis techniques also often need this information in order to
709 minimize or compute error bounds.
710
711 The header file @file{float.h} describes the format used by your
712 machine.
713
714 @menu
715 * Floating Point Concepts::     Definitions of terminology.
716 * Floating Point Parameters::   Details of specific macros.
717 * IEEE Floating Point::         The measurements for one common
718                                  representation. 
719 @end menu
720
721 @node Floating Point Concepts
722 @subsubsection Floating Point Representation Concepts
723
724 This section introduces the terminology for describing floating point
725 representations.
726
727 You are probably already familiar with most of these concepts in terms
728 of scientific or exponential notation for floating point numbers.  For
729 example, the number @code{123456.0} could be expressed in exponential
730 notation as @code{1.23456e+05}, a shorthand notation indicating that the
731 mantissa @code{1.23456} is multiplied by the base @code{10} raised to
732 power @code{5}.
733
734 More formally, the internal representation of a floating point number
735 can be characterized in terms of the following parameters:
736
737 @itemize @bullet
738 @item
739 @cindex sign (of floating point number)
740 The @dfn{sign} is either @code{-1} or @code{1}.
741
742 @item
743 @cindex base (of floating point number)
744 @cindex radix (of floating point number)
745 The @dfn{base} or @dfn{radix} for exponentiation, an integer greater
746 than @code{1}.  This is a constant for a particular representation.
747
748 @item
749 @cindex exponent (of floating point number)
750 The @dfn{exponent} to which the base is raised.  The upper and lower
751 bounds of the exponent value are constants for a particular
752 representation.
753
754 @cindex bias (of floating point number exponent)
755 Sometimes, in the actual bits representing the floating point number,
756 the exponent is @dfn{biased} by adding a constant to it, to make it
757 always be represented as an unsigned quantity.  This is only important
758 if you have some reason to pick apart the bit fields making up the
759 floating point number by hand, which is something for which the GNU
760 library provides no support.  So this is ignored in the discussion that
761 follows.
762
763 @item
764 @cindex mantissa (of floating point number)
765 @cindex significand (of floating point number)
766 The @dfn{mantissa} or @dfn{significand}, an unsigned integer which is a
767 part of each floating point number.
768
769 @item 
770 @cindex precision (of floating point number)
771 The @dfn{precision} of the mantissa.  If the base of the representation
772 is @var{b}, then the precision is the number of base-@var{b} digits in
773 the mantissa.  This is a constant for a particular representation.
774
775 @cindex hidden bit (of floating point number mantissa)
776 Many floating point representations have an implicit @dfn{hidden bit} in
777 the mantissa.  This is a bit which is present virtually in the mantissa,
778 but not stored in memory because its value is always 1 in a normalized
779 number.  The precision figure (see above) includes any hidden bits.
780
781 Again, the GNU library provides no facilities for dealing with such
782 low-level aspects of the representation.
783 @end itemize
784
785 The mantissa of a floating point number actually represents an implicit
786 fraction whose denominator is the base raised to the power of the
787 precision.  Since the largest representable mantissa is one less than
788 this denominator, the value of the fraction is always strictly less than
789 @code{1}.  The mathematical value of a floating point number is then the
790 product of this fraction, the sign, and the base raised to the exponent.
791
792 @cindex normalized floating point number
793 We say that the floating point number is @dfn{normalized} if the
794 fraction is at least @code{1/@var{b}}, where @var{b} is the base.  In
795 other words, the mantissa would be too large to fit if it were
796 multiplied by the base.  Non-normalized numbers are sometimes called
797 @dfn{denormal}; they contain less precision than the representation
798 normally can hold.
799
800 If the number is not normalized, then you can subtract @code{1} from the
801 exponent while multiplying the mantissa by the base, and get another
802 floating point number with the same value.  @dfn{Normalization} consists
803 of doing this repeatedly until the number is normalized.  Two distinct
804 normalized floating point numbers cannot be equal in value.
805
806 (There is an exception to this rule: if the mantissa is zero, it is
807 considered normalized.  Another exception happens on certain machines
808 where the exponent is as small as the representation can hold.  Then
809 it is impossible to subtract @code{1} from the exponent, so a number
810 may be normalized even if its fraction is less than @code{1/@var{b}}.)
811
812 @node Floating Point Parameters
813 @subsubsection Floating Point Parameters
814
815 @pindex float.h
816 These macro definitions can be accessed by including the header file
817 @file{float.h} in your program.
818
819 Macro names starting with @samp{FLT_} refer to the @code{float} type,
820 while names beginning with @samp{DBL_} refer to the @code{double} type
821 and names beginning with @samp{LDBL_} refer to the @code{long double}
822 type.  (Currently GCC does not support @code{long double} as a distinct
823 data type, so the values for the @samp{LDBL_} constants are equal to the
824 corresponding constants for the @code{double} type.)@refill
825
826 Of these macros, only @code{FLT_RADIX} is guaranteed to be a constant
827 expression.  The other macros listed here cannot be reliably used in
828 places that require constant expressions, such as @samp{#if}
829 preprocessing directives or in the dimensions of static arrays.
830
831 Although the ANSI C standard specifies minimum and maximum values for
832 most of these parameters, the GNU C implementation uses whatever values
833 describe the floating point representation of the target machine.  So in
834 principle GNU C actually satisfies the ANSI C requirements only if the
835 target machine is suitable.  In practice, all the machines currently
836 supported are suitable.
837
838 @table @code
839 @comment float.h
840 @comment ANSI
841 @item FLT_ROUNDS
842 This value characterizes the rounding mode for floating point addition.
843 The following values indicate standard rounding modes:
844
845 @table @code
846 @item -1
847 The mode is indeterminable.
848 @item 0
849 Rounding is towards zero.
850 @item 1
851 Rounding is to the nearest number.
852 @item 2
853 Rounding is towards positive infinity.
854 @item 3
855 Rounding is towards negative infinity.
856 @end table
857
858 @noindent
859 Any other value represents a machine-dependent nonstandard rounding
860 mode.
861
862 On most machines, the value is @code{1}, in accord with the IEEE
863 standard for floating point.
864
865 Here is a table showing how certain values round for each possible value
866 of @code{FLT_ROUNDS}, if the other aspects of the representation match
867 the IEEE single-precision standard.
868
869 @example
870                  0       1              2              3
871  1.00000003     1.0     1.0            1.00000012     1.0
872  1.00000007     1.0     1.00000012     1.00000012     1.0
873 -1.00000003    -1.0    -1.0           -1.0           -1.00000012
874 -1.00000007    -1.0    -1.00000012    -1.0           -1.00000012
875 @end example
876
877 @comment float.h
878 @comment ANSI
879 @item FLT_RADIX
880 This is the value of the base, or radix, of exponent representation.
881 This is guaranteed to be a constant expression, unlike the other macros
882 described in this section.  The value is 2 on all machines we know of
883 except the IBM 360 and derivatives.
884
885 @comment float.h
886 @comment ANSI
887 @item FLT_MANT_DIG
888 This is the number of base-@code{FLT_RADIX} digits in the floating point
889 mantissa for the @code{float} data type.  The following expression
890 yields @code{1.0} (even though mathematically it should not) due to the
891 limited number of mantissa digits:
892
893 @example
894 float radix = FLT_RADIX;
895
896 1.0f + 1.0f / radix / radix / @dots{} / radix
897 @end example
898
899 @noindent
900 where @code{radix} appears @code{FLT_MANT_DIG} times.
901
902 @comment float.h
903 @comment ANSI
904 @item DBL_MANT_DIG
905 @itemx LDBL_MANT_DIG
906 This is the number of base-@code{FLT_RADIX} digits in the floating point
907 mantissa for the data types @code{double} and @code{long double},
908 respectively.
909
910 @comment float.h
911 @comment ANSI
912 @item FLT_DIG
913 This is the number of decimal digits of precision for the @code{float}
914 data type.  Technically, if @var{p} and @var{b} are the precision and
915 base (respectively) for the representation, then the decimal precision
916 @var{q} is the maximum number of decimal digits such that any floating
917 point number with @var{q} base 10 digits can be rounded to a floating
918 point number with @var{p} base @var{b} digits and back again, without
919 change to the @var{q} decimal digits.
920
921 The value of this macro is supposed to be at least @code{6}, to satisfy
922 ANSI C.
923
924 @comment float.h
925 @comment ANSI
926 @item DBL_DIG
927 @itemx LDBL_DIG
928 These are similar to @code{FLT_DIG}, but for the data types
929 @code{double} and @code{long double}, respectively.  The values of these
930 macros are supposed to be at least @code{10}.
931
932 @comment float.h
933 @comment ANSI
934 @item FLT_MIN_EXP
935 This is the smallest possible exponent value for type @code{float}.
936 More precisely, is the minimum negative integer such that the value
937 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
938 normalized floating point number of type @code{float}.
939
940 @comment float.h
941 @comment ANSI
942 @item DBL_MIN_EXP
943 @itemx LDBL_MIN_EXP
944 These are similar to @code{FLT_MIN_EXP}, but for the data types
945 @code{double} and @code{long double}, respectively.
946
947 @comment float.h
948 @comment ANSI
949 @item FLT_MIN_10_EXP
950 This is the minimum negative integer such that @code{10} raised to this
951 power minus 1 can be represented as a normalized floating point number
952 of type @code{float}.  This is supposed to be @code{-37} or even less.
953
954 @comment float.h
955 @comment ANSI
956 @item DBL_MIN_10_EXP
957 These are similar to @code{FLT_MIN_10_EXP}, but for the data types
958 @code{double} and @code{long double}, respectively.
959
960 @comment float.h
961 @comment ANSI
962 @item FLT_MAX_EXP
963 This is the largest possible exponent value for type @code{float}.  More
964 precisely, this is the maximum negative integer such that value
965 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
966 floating point number of type @code{float}.
967
968 @comment float.h
969 @comment ANSI
970 @item DBL_MAX_EXP
971 @itemx LDBL_MAX_EXP
972 These are similar to @code{FLT_MAX_EXP}, but for the data types
973 @code{double} and @code{long double}, respectively.
974
975 @comment float.h
976 @comment ANSI
977 @item FLT_MAX_10_EXP
978 This is the maximum negative integer such that @code{10} raised to this
979 power minus 1 can be represented as a normalized floating point number
980 of type @code{float}.  This is supposed to be at least @code{37}.
981
982 @comment float.h
983 @comment ANSI
984 @item DBL_MAX_10_EXP
985 @itemx LDBL_MAX_10_EXP
986 These are similar to @code{FLT_MAX_10_EXP}, but for the data types
987 @code{double} and @code{long double}, respectively.
988
989 @comment float.h
990 @comment ANSI
991 @item FLT_MAX
992 The value of this macro is the maximum number representable in type
993 @code{float}.  It is supposed to be at least @code{1E+37}.  The value
994 has type @code{float}.
995
996 The smallest representable number is @code{- FLT_MAX}.
997
998 @comment float.h
999 @comment ANSI
1000 @item DBL_MAX
1001 @itemx LDBL_MAX
1002 These are similar to @code{FLT_MAX}, but for the data types
1003 @code{double} and @code{long double}, respectively.  The type of the
1004 macro's value is the same as the type it describes.
1005
1006 @comment float.h
1007 @comment ANSI
1008 @item FLT_MIN
1009 The value of this macro is the minimum normalized positive floating
1010 point number that is representable in type @code{float}.  It is supposed
1011 to be no more than @code{1E-37}.
1012
1013 @comment float.h
1014 @comment ANSI
1015 @item DBL_MIN
1016 @itemx LDBL_MIN
1017 These are similar to @code{FLT_MIN}, but for the data types
1018 @code{double} and @code{long double}, respectively.  The type of the
1019 macro's value is the same as the type it describes.
1020
1021 @comment float.h
1022 @comment ANSI
1023 @item FLT_EPSILON
1024 This is the minimum positive floating point number of type @code{float}
1025 such that @code{1.0 + FLT_EPSILON != 1.0} is true.  It's supposed to
1026 be no greater than @code{1E-5}.
1027
1028 @comment float.h
1029 @comment ANSI
1030 @item DBL_EPSILON
1031 @itemx LDBL_EPSILON
1032 These are similar to @code{FLT_MIN}, but for the data types
1033 @code{double} and @code{long double}, respectively.  The type of the
1034 macro's value is the same as the type it describes.  The values are not
1035 supposed to be greater than @code{1E-9}.
1036 @end table
1037
1038 @node IEEE Floating Point
1039 @subsubsection IEEE Floating Point
1040 @cindex IEEE floating point representation 
1041 @cindex floating point, IEEE
1042
1043 Here is an example showing how the floating type measurements come out
1044 for the most common floating point representation, specified by the
1045 @cite{IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std
1046 754-1985)}.  Nearly all computers designed since the 1980s use this
1047 format.
1048
1049 The IEEE single-precision float representation uses a base of 2.  There
1050 is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total
1051 precision is 24 base-2 digits), and an 8-bit exponent that can represent
1052 values in the range -125 to 128, inclusive.
1053
1054 So, for an implementation that uses this representation for the
1055 @code{float} data type, appropriate values for the corresponding
1056 parameters are:
1057
1058 @example
1059 FLT_RADIX                             2
1060 FLT_MANT_DIG                         24
1061 FLT_DIG                               6
1062 FLT_MIN_EXP                        -125
1063 FLT_MIN_10_EXP                      -37
1064 FLT_MAX_EXP                         128
1065 FLT_MAX_10_EXP                      +38
1066 FLT_MIN                 1.17549435E-38F
1067 FLT_MAX                 3.40282347E+38F
1068 FLT_EPSILON             1.19209290E-07F
1069 @end example
1070
1071 Here are the values for the @code{double} data type:
1072
1073 @example
1074 DBL_MANT_DIG                         53
1075 DBL_DIG                              15
1076 DBL_MIN_EXP                       -1021
1077 DBL_MIN_10_EXP                     -307
1078 DBL_MAX_EXP                        1024
1079 DBL_MAX_10_EXP                      308
1080 DBL_MAX         1.7976931348623157E+308
1081 DBL_MIN         2.2250738585072014E-308
1082 DBL_EPSILON     2.2204460492503131E-016
1083 @end example
1084
1085 @node Structure Measurement
1086 @subsection Structure Field Offset Measurement
1087
1088 You can use @code{offsetof} to measure the location within a structure
1089 type of a particular structure member.
1090
1091 @comment stddef.h
1092 @comment ANSI
1093 @deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
1094 This expands to a integer constant expression that is the offset of the
1095 structure member named @var{member} in a the structure type @var{type}.
1096 For example, @code{offsetof (struct s, elem)} is the offset, in bytes,
1097 of the member @code{elem} in a @code{struct s}.
1098
1099 This macro won't work if @var{member} is a bit field; you get an error
1100 from the C compiler in that case.
1101 @end deftypefn