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