Shorten the chapter title.
[kopensolaris-gnu/glibc.git] / manual / lang.texi
1 @node Language Features, Library Summary, System Configuration, Top
2 @appendix C Language Facilities Implemented By the Library
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 printed by the @code{assert}
86 macro is intended to help you, the programmer, track down the cause of a
87 bug, but is not really useful for telling a user of your program why his
88 or her input was invalid or why a command could not be carried out.  So
89 you can't use @code{assert} to print the error messages for these
90 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
135 @samp{foo} is declared with @code{int foo (int, char *);} then you must
136 call it with two arguments, a number (any kind will do) and a string
137 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 @w{@code{short int}}
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 (@pxref{Formatted Output Functions}).
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.)  The @code{execl} function works
330 in just this way; see @ref{Executing a File}.
331
332
333 @node Calling Variadics
334 @subsubsection Calling Variadic Functions
335 @cindex variadic functions, calling
336 @cindex calling variadic functions
337 @cindex declaring variadic functions
338
339 You don't have to write anything special when you call a variadic function.
340 Just write the arguments (required arguments, followed by optional ones)
341 inside parentheses, separated by commas, as usual.  But you should prepare
342 by declaring the function with a prototype, and you must know how the
343 argument values are converted.
344
345 In principle, functions that are @emph{defined} to be variadic must also
346 be @emph{declared} to be variadic using a function prototype whenever
347 you call them.  (@xref{Variadic Prototypes}, for how.)  This is because
348 some C compilers use a different calling convention to pass the same set
349 of argument values to a function depending on whether that function
350 takes variable arguments or fixed arguments.
351
352 In practice, the GNU C compiler always passes a given set of argument
353 types in the same way regardless of whether they are optional or
354 required.  So, as long as the argument types are self-promoting, you can
355 safely omit declaring them.  Usually it is a good idea to declare the
356 argument types for variadic functions, and indeed for all functions.
357 But there are a few functions which it is extremely convenient not to
358 have to declare as variadic---for example, @code{open} and
359 @code{printf}.
360
361 @cindex default argument promotions
362 @cindex argument promotion
363 Since the prototype doesn't specify types for optional arguments, in a
364 call to a variadic function the @dfn{default argument promotions} are
365 performed on the optional argument values.  This means the objects of
366 type @code{char} or @w{@code{short int}} (whether signed or not) are
367 promoted to either @code{int} or @w{@code{unsigned int}}, as
368 appropriate; and that objects of type @code{float} are promoted to type
369 @code{double}.  So, if the caller passes a @code{char} as an optional
370 argument, it is promoted to an @code{int}, and the function should get
371 it with @code{va_arg (@var{ap}, int)}.
372
373 Conversion of the required arguments is controlled by the function
374 prototype in the usual way: the argument expression is converted to the
375 declared argument type as if it were being assigned to a variable of
376 that type.
377
378 @node Argument Macros
379 @subsubsection Argument Access Macros
380
381 Here are descriptions of the macros used to retrieve variable arguments.
382 These macros are defined in the header file @file{stdarg.h}.
383 @pindex stdarg.h
384
385 @comment stdarg.h
386 @comment ANSI
387 @deftp {Data Type} va_list
388 The type @code{va_list} is used for argument pointer variables.
389 @end deftp
390
391 @comment stdarg.h
392 @comment ANSI
393 @deftypefn {Macro} void va_start (va_list @var{ap}, @var{last_required})
394 This macro initializes the argument pointer variable @var{ap} to point
395 to the first of the optional arguments of the current function;
396 @var{last_required} must be the last required argument to the function.
397 @end deftypefn
398
399 @comment stdarg.h
400 @comment ANSI
401 @deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type})
402 The @code{va_arg} macro returns the value of the next optional argument,
403 and modifies the value of @var{ap} to point to the subsequent argument.
404 Thus, successive uses of @code{va_arg} return successive optional 
405 arguments.
406
407 The type of the value returned by @code{va_arg} is @var{type} as
408 specified in the call.  @var{type} must be a self-promoting type (not
409 @code{char} or @code{short int} or @code{float}) that matches the type
410 of the actual argument.
411 @end deftypefn
412
413 @comment stdarg.h
414 @comment ANSI
415 @deftypefn {Macro} void va_end (va_list @var{ap})
416 This ends the use of @var{ap}.  After a @code{va_end} call, further
417 @code{va_arg} calls with the same @var{ap} may not work.  You should invoke
418 @code{va_end} before returning from the function in which @code{va_start}
419 was invoked with the same @var{ap} argument.
420
421 In the GNU C library, @code{va_end} does nothing, and you need not ever
422 use it except for reasons of portability.
423 @refill
424 @end deftypefn
425
426 @node Variadic Example
427 @subsection Example of a Variadic Function
428
429 Here is a complete sample function that accepts a variable number of
430 arguments.  The first argument to the function is the count of remaining
431 arguments, which are added up and the result returned.  While trivial,
432 this function is sufficient to illustrate how to use the variable
433 arguments facility.
434
435 @comment Yes, this example has been tested.
436 @example
437 @include add.c.texi
438 @end example
439
440 @node Null Pointer Constant
441 @section Null Pointer Constant
442 @cindex null pointer constant
443
444 The null pointer constant is guaranteed not to point to any real object.
445 You can assign it to any pointer variable since it has type @code{void
446 *}.  The preferred way to write a null pointer constant is with
447 @code{NULL}.
448
449 @comment stddef.h
450 @comment ANSI
451 @deftypevr Macro {void *} NULL
452 This is a null pointer constant.
453 @end deftypevr
454
455 You can also use @code{0} or @code{(void *)0} as a null pointer
456 constant, but using @code{NULL} is cleaner because it makes the purpose
457 of the constant more evident.
458
459 If you use the null pointer constant as a function argument, then for
460 complete portability you should make sure that the function has a
461 prototype declaration.  Otherwise, if the target machine has two
462 different pointer representations, the compiler won't know which
463 representation to use for that argument.  You can avoid the problem by
464 explicitly casting the constant to the proper pointer type, but we
465 recommend instead adding a prototype for the function you are calling.
466
467 @node Important Data Types
468 @section Important Data Types
469
470 The result of subtracting two pointers in C is always an integer, but the
471 precise data type varies from C compiler to C compiler.  Likewise, the
472 data type of the result of @code{sizeof} also varies between compilers.
473 ANSI defines standard aliases for these two types, so you can refer to
474 them in a portable fashion.  They are defined in the header file 
475 @file{stddef.h}.
476 @pindex stddef.h
477
478 @comment stddef.h
479 @comment ANSI
480 @deftp {Data Type} ptrdiff_t
481 This is the signed integer type of the result of subtracting two
482 pointers.  For example, with the declaration @code{char *p1, *p2;}, the
483 expression @code{p2 - p1} is of type @code{ptrdiff_t}.  This will
484 probably be one of the standard signed integer types (@w{@code{short
485 int}}, @code{int} or @w{@code{long int}}), but might be a nonstandard
486 type that exists only for this purpose.
487 @end deftp
488
489 @comment stddef.h
490 @comment ANSI
491 @deftp {Data Type} size_t
492 This is an unsigned integer type used to represent the sizes of objects.
493 The result of the @code{sizeof} operator is of this type, and functions
494 such as @code{malloc} (@pxref{Unconstrained Allocation}) and
495 @code{memcpy} (@pxref{Copying and Concatenation}) accept arguments of
496 this type to specify object sizes.
497
498 @strong{Usage Note:} @code{size_t} is the preferred way to declare any
499 arguments or variables that hold the size of an object.
500 @end deftp
501
502 In the GNU system @code{size_t} is equivalent to one of the types
503 @w{@code{unsigned int}} and @w{@code{unsigned long int}}.  These types
504 have identical properties on the GNU system, and for most purposes, you
505 can use them interchangeably.  However, they are distinct as data types,
506 which makes a difference in certain contexts.
507
508 For example, when you specify the type of a function argument in a
509 function prototype, it makes a difference which one you use.  If the
510 system header files declare @code{malloc} with an argument of type
511 @code{size_t} and you declare @code{malloc} with an argument of type
512 @code{unsigned int}, you will get a compilation error if @code{size_t}
513 happens to be @code{unsigned long int} on your system.  To avoid any
514 possibility of error, when a function argument or value is supposed to
515 have type @code{size_t}, never declare its type in any other way.
516
517 @strong{Compatibility Note:} Pre-ANSI C implementations generally used
518 @code{unsigned int} for representing object sizes and @code{int} for
519 pointer subtraction results.  They did not necessarily define either
520 @code{size_t} or @code{ptrdiff_t}.  Unix systems did define
521 @code{size_t}, in @file{sys/types.h}, but the definition was usually a
522 signed type.
523
524 @node Data Type Measurements
525 @section Data Type Measurements
526
527 Most of the time, if you choose the proper C data type for each object
528 in your program, you need not be concerned with just how it is
529 represented or how many bits it uses.  When you do need such
530 information, the C language itself does not provide a way to get it.
531 The header files @file{limits.h} and @file{float.h} contain macros
532 which give you this information in full detail.
533
534 @menu
535 * Width of Type::           How many bits does an integer type hold?
536 * Range of Type::           What are the largest and smallest values
537                              that an integer type can hold?
538 * Floating Type Macros::    Parameters that measure the floating point types. 
539 * Structure Measurement::   Getting measurements on structure types.
540 @end menu
541
542 @node Width of Type
543 @subsection Computing the Width of an Integer Data Type
544 @cindex integer type width
545 @cindex width of integer type
546 @cindex type measurements, integer
547
548 The most common reason that a program needs to know how many bits are in
549 an integer type is for using an array of @code{long int} as a bit vector.
550 You can access the bit at index @var{n} with
551
552 @example
553 vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
554 @end example
555
556 @noindent
557 provided you define @code{LONGBITS} as the number of bits in a
558 @code{long int}.
559
560 @pindex limits.h
561 There is no operator in the C language that can give you the number of
562 bits in an integer data type.  But you can compute it from the macro
563 @code{CHAR_BIT}, defined in the header file @file{limits.h}.
564
565 @table @code
566 @comment limits.h
567 @comment ANSI
568 @item CHAR_BIT
569 This is the number of bits in a @code{char}---eight, on most systems.
570 The value has type @code{int}.
571
572 You can compute the number of bits in any data type @var{type} like
573 this:
574
575 @example
576 sizeof (@var{type}) * CHAR_BIT
577 @end example
578 @end table
579
580 @node Range of Type
581 @subsection Range of an Integer Type
582 @cindex integer type range
583 @cindex range of integer type
584 @cindex limits, integer types
585
586 Suppose you need to store an integer value which can range from zero to
587 one million.  Which is the smallest type you can use?  There is no
588 general rule; it depends on the C compiler and target machine.  You can
589 use the @samp{MIN} and @samp{MAX} macros in @file{limits.h} to determine
590 which type will work.
591
592 Each signed integer type has a pair of macros which give the smallest
593 and largest values that it can hold.  Each unsigned integer type has one
594 such macro, for the maximum value; the minimum value is, of course,
595 zero.
596
597 The values of these macros are all integer constant expressions.  The
598 @samp{MAX} and @samp{MIN} macros for @code{char} and @w{@code{short
599 int}} types have values of type @code{int}.  The @samp{MAX} and
600 @samp{MIN} macros for the other types have values of the same type
601 described by the macro---thus, @code{ULONG_MAX} has type
602 @w{@code{unsigned long int}}.
603
604 @comment Extra blank lines make it look better.
605 @table @code
606 @comment limits.h
607 @comment ANSI
608 @item SCHAR_MIN
609
610 This is the minimum value that can be represented by a @w{@code{signed char}}.
611
612 @comment limits.h
613 @comment ANSI
614 @item SCHAR_MAX
615 @itemx UCHAR_MAX
616
617 These are the maximum values that can be represented by a
618 @w{@code{signed char}} and @w{@code{unsigned char}}, respectively.
619
620 @comment limits.h
621 @comment ANSI
622 @item CHAR_MIN
623
624 This is the minimum value that can be represented by a @code{char}.
625 It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero
626 otherwise.
627
628 @comment limits.h
629 @comment ANSI
630 @item CHAR_MAX
631
632 This is the maximum value that can be represented by a @code{char}.
633 It's equal to @code{SCHAR_MAX} if @code{char} is signed, or
634 @code{UCHAR_MAX} otherwise.
635
636 @comment limits.h
637 @comment ANSI
638 @item SHRT_MIN
639
640 This is the minimum value that can be represented by a @w{@code{signed
641 short int}}.  On most machines that the GNU C library runs on,
642 @code{short} integers are 16-bit quantities.
643
644 @comment limits.h
645 @comment ANSI
646 @item SHRT_MAX
647 @itemx USHRT_MAX
648
649 These are the maximum values that can be represented by a
650 @w{@code{signed short int}} and @w{@code{unsigned short int}},
651 respectively.
652
653 @comment limits.h
654 @comment ANSI
655 @item INT_MIN
656
657 This is the minimum value that can be represented by a @w{@code{signed
658 int}}.  On most machines that the GNU C system runs on, an @code{int} is
659 a 32-bit quantity.
660
661 @comment limits.h
662 @comment ANSI
663 @item INT_MAX
664 @itemx UINT_MAX
665
666 These are the maximum values that can be represented by a
667 @w{@code{signed int}} and @w{@code{unsigned int}}, respectively.
668
669 @comment limits.h
670 @comment ANSI
671 @item LONG_MIN
672
673 This is the minimum value that can be represented by a @w{@code{signed
674 long int}}.  On most machines that the GNU C system runs on, @code{long}
675 integers are 32-bit quantities, the same size as @code{int}.
676
677 @comment limits.h
678 @comment ANSI
679 @item LONG_MAX
680 @itemx ULONG_MAX
681
682 These are the maximum values that can be represented by a
683 @w{@code{signed long int}} and @code{unsigned long int}, respectively.
684
685 @comment limits.h
686 @comment GNU
687 @item LONG_LONG_MIN
688
689 This is the minimum value that can be represented by a @w{@code{signed
690 long long int}}.  On most machines that the GNU C system runs on,
691 @w{@code{long long}} integers are 64-bit quantities.
692
693 @comment limits.h
694 @comment GNU
695 @item LONG_LONG_MAX
696 @itemx ULONG_LONG_MAX
697
698 These are the maximum values that can be represented by a @code{signed
699 long long int} and @code{unsigned long long int}, respectively.
700 @end table
701
702 The header file @file{limits.h} also defines some additional constants
703 that parameterize various operating system and file system limits.  These
704 constants are described in @ref{System Configuration}.
705
706 @node Floating Type Macros
707 @subsection Floating Type Macros
708 @cindex floating type measurements
709 @cindex measurements of floating types
710 @cindex type measurements, floating
711 @cindex limits, floating types
712
713 The specific representation of floating point numbers varies from
714 machine to machine.  Because floating point numbers are represented
715 internally as approximate quantities, algorithms for manipulating
716 floating point data often need to take account of the precise details of
717 the machine's floating point representation.
718
719 Some of the functions in the C library itself need this information; for
720 example, the algorithms for printing and reading floating point numbers
721 (@pxref{I/O on Streams}) and for calculating trigonometric and
722 irrational functions (@pxref{Mathematics}) use it to avoid round-off
723 error and loss of accuracy.  User programs that implement numerical
724 analysis techniques also often need this information in order to
725 minimize or compute error bounds.
726
727 The header file @file{float.h} describes the format used by your
728 machine.
729
730 @menu
731 * Floating Point Concepts::     Definitions of terminology.
732 * Floating Point Parameters::   Details of specific macros.
733 * IEEE Floating Point::         The measurements for one common
734                                  representation. 
735 @end menu
736
737 @node Floating Point Concepts
738 @subsubsection Floating Point Representation Concepts
739
740 This section introduces the terminology for describing floating point
741 representations.
742
743 You are probably already familiar with most of these concepts in terms
744 of scientific or exponential notation for floating point numbers.  For
745 example, the number @code{123456.0} could be expressed in exponential
746 notation as @code{1.23456e+05}, a shorthand notation indicating that the
747 mantissa @code{1.23456} is multiplied by the base @code{10} raised to
748 power @code{5}.
749
750 More formally, the internal representation of a floating point number
751 can be characterized in terms of the following parameters:
752
753 @itemize @bullet
754 @item
755 @cindex sign (of floating point number)
756 The @dfn{sign} is either @code{-1} or @code{1}.
757
758 @item
759 @cindex base (of floating point number)
760 @cindex radix (of floating point number)
761 The @dfn{base} or @dfn{radix} for exponentiation, an integer greater
762 than @code{1}.  This is a constant for a particular representation.
763
764 @item
765 @cindex exponent (of floating point number)
766 The @dfn{exponent} to which the base is raised.  The upper and lower
767 bounds of the exponent value are constants for a particular
768 representation.
769
770 @cindex bias (of floating point number exponent)
771 Sometimes, in the actual bits representing the floating point number,
772 the exponent is @dfn{biased} by adding a constant to it, to make it
773 always be represented as an unsigned quantity.  This is only important
774 if you have some reason to pick apart the bit fields making up the
775 floating point number by hand, which is something for which the GNU
776 library provides no support.  So this is ignored in the discussion that
777 follows.
778
779 @item
780 @cindex mantissa (of floating point number)
781 @cindex significand (of floating point number)
782 The @dfn{mantissa} or @dfn{significand}, an unsigned integer which is a
783 part of each floating point number.
784
785 @item 
786 @cindex precision (of floating point number)
787 The @dfn{precision} of the mantissa.  If the base of the representation
788 is @var{b}, then the precision is the number of base-@var{b} digits in
789 the mantissa.  This is a constant for a particular representation.
790
791 @cindex hidden bit (of floating point number mantissa)
792 Many floating point representations have an implicit @dfn{hidden bit} in
793 the mantissa.  This is a bit which is present virtually in the mantissa,
794 but not stored in memory because its value is always 1 in a normalized
795 number.  The precision figure (see above) includes any hidden bits.
796
797 Again, the GNU library provides no facilities for dealing with such
798 low-level aspects of the representation.
799 @end itemize
800
801 The mantissa of a floating point number actually represents an implicit
802 fraction whose denominator is the base raised to the power of the
803 precision.  Since the largest representable mantissa is one less than
804 this denominator, the value of the fraction is always strictly less than
805 @code{1}.  The mathematical value of a floating point number is then the
806 product of this fraction, the sign, and the base raised to the exponent.
807
808 @cindex normalized floating point number
809 We say that the floating point number is @dfn{normalized} if the
810 fraction is at least @code{1/@var{b}}, where @var{b} is the base.  In
811 other words, the mantissa would be too large to fit if it were
812 multiplied by the base.  Non-normalized numbers are sometimes called
813 @dfn{denormal}; they contain less precision than the representation
814 normally can hold.
815
816 If the number is not normalized, then you can subtract @code{1} from the
817 exponent while multiplying the mantissa by the base, and get another
818 floating point number with the same value.  @dfn{Normalization} consists
819 of doing this repeatedly until the number is normalized.  Two distinct
820 normalized floating point numbers cannot be equal in value.
821
822 (There is an exception to this rule: if the mantissa is zero, it is
823 considered normalized.  Another exception happens on certain machines
824 where the exponent is as small as the representation can hold.  Then
825 it is impossible to subtract @code{1} from the exponent, so a number
826 may be normalized even if its fraction is less than @code{1/@var{b}}.)
827
828 @node Floating Point Parameters
829 @subsubsection Floating Point Parameters
830
831 @pindex float.h
832 These macro definitions can be accessed by including the header file
833 @file{float.h} in your program.
834
835 Macro names starting with @samp{FLT_} refer to the @code{float} type,
836 while names beginning with @samp{DBL_} refer to the @code{double} type
837 and names beginning with @samp{LDBL_} refer to the @code{long double}
838 type.  (Currently GCC does not support @code{long double} as a distinct
839 data type, so the values for the @samp{LDBL_} constants are equal to the
840 corresponding constants for the @code{double} type.)@refill
841
842 Of these macros, only @code{FLT_RADIX} is guaranteed to be a constant
843 expression.  The other macros listed here cannot be reliably used in
844 places that require constant expressions, such as @samp{#if}
845 preprocessing directives or in the dimensions of static arrays.
846
847 Although the ANSI C standard specifies minimum and maximum values for
848 most of these parameters, the GNU C implementation uses whatever values
849 describe the floating point representation of the target machine.  So in
850 principle GNU C actually satisfies the ANSI C requirements only if the
851 target machine is suitable.  In practice, all the machines currently
852 supported are suitable.
853
854 @table @code
855 @comment float.h
856 @comment ANSI
857 @item FLT_ROUNDS
858 This value characterizes the rounding mode for floating point addition.
859 The following values indicate standard rounding modes:
860
861 @table @code
862 @item -1
863 The mode is indeterminable.
864 @item 0
865 Rounding is towards zero.
866 @item 1
867 Rounding is to the nearest number.
868 @item 2
869 Rounding is towards positive infinity.
870 @item 3
871 Rounding is towards negative infinity.
872 @end table
873
874 @noindent
875 Any other value represents a machine-dependent nonstandard rounding
876 mode.
877
878 On most machines, the value is @code{1}, in accord with the IEEE
879 standard for floating point.
880
881 Here is a table showing how certain values round for each possible value
882 of @code{FLT_ROUNDS}, if the other aspects of the representation match
883 the IEEE single-precision standard.
884
885 @example
886                  0       1              2              3
887  1.00000003     1.0     1.0            1.00000012     1.0
888  1.00000007     1.0     1.00000012     1.00000012     1.0
889 -1.00000003    -1.0    -1.0           -1.0           -1.00000012
890 -1.00000007    -1.0    -1.00000012    -1.0           -1.00000012
891 @end example
892
893 @comment float.h
894 @comment ANSI
895 @item FLT_RADIX
896 This is the value of the base, or radix, of exponent representation.
897 This is guaranteed to be a constant expression, unlike the other macros
898 described in this section.  The value is 2 on all machines we know of
899 except the IBM 360 and derivatives.
900
901 @comment float.h
902 @comment ANSI
903 @item FLT_MANT_DIG
904 This is the number of base-@code{FLT_RADIX} digits in the floating point
905 mantissa for the @code{float} data type.  The following expression
906 yields @code{1.0} (even though mathematically it should not) due to the
907 limited number of mantissa digits:
908
909 @example
910 float radix = FLT_RADIX;
911
912 1.0f + 1.0f / radix / radix / @dots{} / radix
913 @end example
914
915 @noindent
916 where @code{radix} appears @code{FLT_MANT_DIG} times.
917
918 @comment float.h
919 @comment ANSI
920 @item DBL_MANT_DIG
921 @itemx LDBL_MANT_DIG
922 This is the number of base-@code{FLT_RADIX} digits in the floating point
923 mantissa for the data types @code{double} and @code{long double},
924 respectively.
925
926 @comment Extra blank lines make it look better.
927 @comment float.h
928 @comment ANSI
929 @item FLT_DIG
930
931 This is the number of decimal digits of precision for the @code{float}
932 data type.  Technically, if @var{p} and @var{b} are the precision and
933 base (respectively) for the representation, then the decimal precision
934 @var{q} is the maximum number of decimal digits such that any floating
935 point number with @var{q} base 10 digits can be rounded to a floating
936 point number with @var{p} base @var{b} digits and back again, without
937 change to the @var{q} decimal digits.
938
939 The value of this macro is supposed to be at least @code{6}, to satisfy
940 ANSI C.
941
942 @comment float.h
943 @comment ANSI
944 @item DBL_DIG
945 @itemx LDBL_DIG
946
947 These are similar to @code{FLT_DIG}, but for the data types
948 @code{double} and @code{long double}, respectively.  The values of these
949 macros are supposed to be at least @code{10}.
950
951 @comment float.h
952 @comment ANSI
953 @item FLT_MIN_EXP
954 This is the smallest possible exponent value for type @code{float}.
955 More precisely, is the minimum negative integer such that the value
956 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
957 normalized floating point number of type @code{float}.
958
959 @comment float.h
960 @comment ANSI
961 @item DBL_MIN_EXP
962 @itemx LDBL_MIN_EXP
963
964 These are similar to @code{FLT_MIN_EXP}, but for the data types
965 @code{double} and @code{long double}, respectively.
966
967 @comment float.h
968 @comment ANSI
969 @item FLT_MIN_10_EXP
970 This is the minimum negative integer such that @code{10} raised to this
971 power minus 1 can be represented as a normalized floating point number
972 of type @code{float}.  This is supposed to be @code{-37} or even less.
973
974 @comment float.h
975 @comment ANSI
976 @item DBL_MIN_10_EXP
977 @itemx LDBL_MIN_10_EXP
978 These are similar to @code{FLT_MIN_10_EXP}, but for the data types
979 @code{double} and @code{long double}, respectively.
980
981 @comment float.h
982 @comment ANSI
983 @item FLT_MAX_EXP
984 This is the largest possible exponent value for type @code{float}.  More
985 precisely, this is the maximum positive integer such that value
986 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
987 floating point number of type @code{float}.
988
989 @comment float.h
990 @comment ANSI
991 @item DBL_MAX_EXP
992 @itemx LDBL_MAX_EXP
993 These are similar to @code{FLT_MAX_EXP}, but for the data types
994 @code{double} and @code{long double}, respectively.
995
996 @comment float.h
997 @comment ANSI
998 @item FLT_MAX_10_EXP
999 This is the maximum positive integer such that @code{10} raised to this
1000 power minus 1 can be represented as a normalized floating point number
1001 of type @code{float}.  This is supposed to be at least @code{37}.
1002
1003 @comment float.h
1004 @comment ANSI
1005 @item DBL_MAX_10_EXP
1006 @itemx LDBL_MAX_10_EXP
1007 These are similar to @code{FLT_MAX_10_EXP}, but for the data types
1008 @code{double} and @code{long double}, respectively.
1009
1010 @comment float.h
1011 @comment ANSI
1012 @item FLT_MAX
1013
1014 The value of this macro is the maximum number representable in type
1015 @code{float}.  It is supposed to be at least @code{1E+37}.  The value
1016 has type @code{float}.
1017
1018 The smallest representable number is @code{- FLT_MAX}.
1019
1020 @comment float.h
1021 @comment ANSI
1022 @item DBL_MAX
1023 @itemx LDBL_MAX
1024
1025 These are similar to @code{FLT_MAX}, but for the data types
1026 @code{double} and @code{long double}, respectively.  The type of the
1027 macro's value is the same as the type it describes.
1028
1029 @comment float.h
1030 @comment ANSI
1031 @item FLT_MIN
1032
1033 The value of this macro is the minimum normalized positive floating
1034 point number that is representable in type @code{float}.  It is supposed
1035 to be no more than @code{1E-37}.
1036
1037 @comment float.h
1038 @comment ANSI
1039 @item DBL_MIN
1040 @itemx LDBL_MIN
1041
1042 These are similar to @code{FLT_MIN}, but for the data types
1043 @code{double} and @code{long double}, respectively.  The type of the
1044 macro's value is the same as the type it describes.
1045
1046 @comment float.h
1047 @comment ANSI
1048 @item FLT_EPSILON
1049
1050 This is the minimum positive floating point number of type @code{float}
1051 such that @code{1.0 + FLT_EPSILON != 1.0} is true.  It's supposed to
1052 be no greater than @code{1E-5}.
1053
1054 @comment float.h
1055 @comment ANSI
1056 @item DBL_EPSILON
1057 @itemx LDBL_EPSILON
1058
1059 These are similar to @code{FLT_EPSILON}, but for the data types
1060 @code{double} and @code{long double}, respectively.  The type of the
1061 macro's value is the same as the type it describes.  The values are not
1062 supposed to be greater than @code{1E-9}.
1063 @end table
1064
1065 @node IEEE Floating Point
1066 @subsubsection IEEE Floating Point
1067 @cindex IEEE floating point representation 
1068 @cindex floating point, IEEE
1069
1070 Here is an example showing how the floating type measurements come out
1071 for the most common floating point representation, specified by the
1072 @cite{IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std
1073 754-1985)}.  Nearly all computers designed since the 1980s use this
1074 format.
1075
1076 The IEEE single-precision float representation uses a base of 2.  There
1077 is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total
1078 precision is 24 base-2 digits), and an 8-bit exponent that can represent
1079 values in the range -125 to 128, inclusive.
1080
1081 So, for an implementation that uses this representation for the
1082 @code{float} data type, appropriate values for the corresponding
1083 parameters are:
1084
1085 @example
1086 FLT_RADIX                             2
1087 FLT_MANT_DIG                         24
1088 FLT_DIG                               6
1089 FLT_MIN_EXP                        -125
1090 FLT_MIN_10_EXP                      -37
1091 FLT_MAX_EXP                         128
1092 FLT_MAX_10_EXP                      +38
1093 FLT_MIN                 1.17549435E-38F
1094 FLT_MAX                 3.40282347E+38F
1095 FLT_EPSILON             1.19209290E-07F
1096 @end example
1097
1098 Here are the values for the @code{double} data type:
1099
1100 @example
1101 DBL_MANT_DIG                         53
1102 DBL_DIG                              15
1103 DBL_MIN_EXP                       -1021
1104 DBL_MIN_10_EXP                     -307
1105 DBL_MAX_EXP                        1024
1106 DBL_MAX_10_EXP                      308
1107 DBL_MAX         1.7976931348623157E+308
1108 DBL_MIN         2.2250738585072014E-308
1109 DBL_EPSILON     2.2204460492503131E-016
1110 @end example
1111
1112 @node Structure Measurement
1113 @subsection Structure Field Offset Measurement
1114
1115 You can use @code{offsetof} to measure the location within a structure
1116 type of a particular structure member.
1117
1118 @comment stddef.h
1119 @comment ANSI
1120 @deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
1121 This expands to a integer constant expression that is the offset of the
1122 structure member named @var{member} in a the structure type @var{type}.
1123 For example, @code{offsetof (struct s, elem)} is the offset, in bytes,
1124 of the member @code{elem} in a @code{struct s}.
1125
1126 This macro won't work if @var{member} is a bit field; you get an error
1127 from the C compiler in that case.
1128 @end deftypefn