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