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