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