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