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