Update.
[glibc.git] / manual / lang.texi
blob7520da2fbe32ec89b42528ceb92c40d793153b2e
1 @node Language Features, Library Summary, System Configuration, Top
2 @appendix C Language Facilities in the Library
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.
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
20 @node Consistency Checking
21 @section Explicitly Checking Internal Consistency
22 @cindex consistency checking
23 @cindex impossible events
24 @cindex assertions
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.
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.
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.
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.
48 @comment assert.h
49 @comment ISO
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.
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:
59 @smallexample
60 @file{@var{file}}:@var{linenum}: @var{function}: Assertion `@var{expression}' failed.
61 @end smallexample
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.
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.
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
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.
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.
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:
97 @smallexample
98 @file{@var{file}}:@var{linenum}: @var{function}: @var{error text}
99 @end smallexample
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}.
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}.
112 This macro is a GNU extension.
113 @end deftypefn
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.
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.
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.
132 @xref{Error Messages}, for information on printing error messages for
133 problems that @emph{do not} represent bugs in the program.
136 @node Variadic Functions
137 @section Variadic Functions
138 @cindex variable number of arguments
139 @cindex variadic functions
140 @cindex optional arguments
142 @w{ISO 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}.
149 This section describes how to declare variadic functions, how to write
150 them, and how to call them properly.
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}.
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
163 @node Why Variadic
164 @subsection Why Variadic Functions are Used
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.
174 But some functions perform operations that can meaningfully accept an
175 unlimited number of arguments.
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.
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.
190 These are good reasons to define a @dfn{variadic} function which can
191 handle as many arguments as the caller chooses to pass.
193 Some functions such as @code{open} take a fixed set of arguments, but
194 occasionally ignore the last few.  Strict adherence to @w{ISO 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!).
201 @node How Variadic
202 @subsection How Variadic Functions are Defined and Used
204 Defining and using a variadic function involves three steps:
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}.
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}.
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
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-ISO way of defining variadic functions.
233 @end menu
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
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 @w{ISO C} requires at least one fixed
245 argument before the @samp{@dots{}}.  For example,
247 @smallexample
249 func (const char *a, int b, @dots{})
251   @dots{}
253 @end smallexample
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.
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 @w{ISO C} requirement.
269 @node Receiving Arguments
270 @subsubsection Receiving the Argument Values
271 @cindex variadic function argument access
272 @cindex arguments (variadic functions)
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?
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:
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.
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.
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.
299 @item
300 You indicate that you are finished with the argument pointer variable by
301 calling @code{va_end}.
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
309 @xref{Argument Macros}, for the full definitions of @code{va_start},
310 @code{va_arg} and @code{va_end}.
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.
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.
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.
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 @w{ISO C} requirement, but most ANSI C compilers work happily
332 regardless.
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
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.
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.
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.
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}).
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}.
369 @node Calling Variadics
370 @subsubsection Calling Variadic Functions
371 @cindex variadic functions, calling
372 @cindex calling variadic functions
373 @cindex declaring variadic functions
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.
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.
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}.
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)}.
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.
414 @node Argument Macros
415 @subsubsection Argument Access Macros
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
421 @comment stdarg.h
422 @comment ISO
423 @deftp {Data Type} va_list
424 The type @code{va_list} is used for argument pointer variables.
425 @end deftp
427 @comment stdarg.h
428 @comment ISO
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.
434 @xref{Old Varargs}, for an alternate definition of @code{va_start}
435 found in the header file @file{varargs.h}.
436 @end deftypefn
438 @comment stdarg.h
439 @comment ISO
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.
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
452 @comment stdarg.h
453 @comment ISO
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.
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
465 Sometimes it is necessary to parse the list of parameters more than once
466 or one wants to remember a certain position in the parameter list.  To
467 do this one will have to make a copy of the current value of the
468 argument.  But @code{va_list} is an opaque type and it is not guaranteed
469 that one can simply assign the value of a variable to another one of
470 type @code{va_list}
472 @comment stdarg.h
473 @comment GNU
474 @deftypefn {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
475 The @code{__va_copy} macro allows copying of objects of type
476 @code{va_list} even if this is no integral type.  The argument pointer
477 in @var{dest} is initialized to point to the same argument as the
478 pointer in @var{src}.
480 This macro is a GNU extension but it will hopefully also be available in
481 the next update of the ISO C standard.
482 @end deftypefn
484 If you want to use @code{__va_copy} you should always be prepared that
485 this macro is not available.  On architectures where a simple assignment
486 is invalid it hopefully is and so one should always write something like
487 this:
489 @smallexample
491   va_list ap, save;
492   @dots{}
493 #ifdef __va_copy
494   __va_copy (save, ap);
495 #else
496   save = ap;
497 #endif
498   @dots{}
500 @end smallexample
503 @node Variadic Example
504 @subsection Example of a Variadic Function
506 Here is a complete sample function that accepts a variable number of
507 arguments.  The first argument to the function is the count of remaining
508 arguments, which are added up and the result returned.  While trivial,
509 this function is sufficient to illustrate how to use the variable
510 arguments facility.
512 @comment Yes, this example has been tested.
513 @smallexample
514 @include add.c.texi
515 @end smallexample
517 @node Old Varargs
518 @subsubsection Old-Style Variadic Functions
520 @pindex varargs.h
521 Before @w{ISO C}, programmers used a slightly different facility for
522 writing variadic functions.  The GNU C compiler still supports it;
523 currently, it is more portable than the @w{ISO C} facility, since support
524 for @w{ISO C} is still not universal.  The header file which defines the
525 old-fashioned variadic facility is called @file{varargs.h}.
527 Using @file{varargs.h} is almost the same as using @file{stdarg.h}.
528 There is no difference in how you call a variadic function;
529 @xref{Calling Variadics}.  The only difference is in how you define
530 them.  First of all, you must use old-style non-prototype syntax, like
531 this:
533 @smallexample
534 tree
535 build (va_alist)
536      va_dcl
538 @end smallexample
540 Secondly, you must give @code{va_start} just one argument, like this:
542 @smallexample
543   va_list p;
544   va_start (p);
545 @end smallexample
547 These are the special macros used for defining old-style variadic
548 functions:
550 @comment varargs.h
551 @comment Unix
552 @deffn Macro va_alist
553 This macro stands for the argument name list required in a variadic
554 function.
555 @end deffn
557 @comment varargs.h
558 @comment Unix
559 @deffn Macro va_dcl
560 This macro declares the implicit argument or arguments for a variadic
561 function.
562 @end deffn
564 @comment varargs.h
565 @comment Unix
566 @deftypefn {Macro} void va_start (va_list @var{ap})
567 This macro, as defined in @file{varargs.h}, initializes the argument
568 pointer variable @var{ap} to point to the first argument of the current
569 function.
570 @end deftypefn
572 The other argument macros, @code{va_arg} and @code{va_end}, are the same
573 in @file{varargs.h} as in @file{stdarg.h}; see @ref{Argument Macros} for
574 details.
576 It does not work to include both @file{varargs.h} and @file{stdarg.h} in
577 the same compilation; they define @code{va_start} in conflicting ways.
579 @node Null Pointer Constant
580 @section Null Pointer Constant
581 @cindex null pointer constant
583 The null pointer constant is guaranteed not to point to any real object.
584 You can assign it to any pointer variable since it has type @code{void
585 *}.  The preferred way to write a null pointer constant is with
586 @code{NULL}.
588 @comment stddef.h
589 @comment ISO
590 @deftypevr Macro {void *} NULL
591 This is a null pointer constant.
592 @end deftypevr
594 You can also use @code{0} or @code{(void *)0} as a null pointer
595 constant, but using @code{NULL} is cleaner because it makes the purpose
596 of the constant more evident.
598 If you use the null pointer constant as a function argument, then for
599 complete portability you should make sure that the function has a
600 prototype declaration.  Otherwise, if the target machine has two
601 different pointer representations, the compiler won't know which
602 representation to use for that argument.  You can avoid the problem by
603 explicitly casting the constant to the proper pointer type, but we
604 recommend instead adding a prototype for the function you are calling.
606 @node Important Data Types
607 @section Important Data Types
609 The result of subtracting two pointers in C is always an integer, but the
610 precise data type varies from C compiler to C compiler.  Likewise, the
611 data type of the result of @code{sizeof} also varies between compilers.
612 ISO defines standard aliases for these two types, so you can refer to
613 them in a portable fashion.  They are defined in the header file
614 @file{stddef.h}.
615 @pindex stddef.h
617 @comment stddef.h
618 @comment ISO
619 @deftp {Data Type} ptrdiff_t
620 This is the signed integer type of the result of subtracting two
621 pointers.  For example, with the declaration @code{char *p1, *p2;}, the
622 expression @code{p2 - p1} is of type @code{ptrdiff_t}.  This will
623 probably be one of the standard signed integer types (@w{@code{short
624 int}}, @code{int} or @w{@code{long int}}), but might be a nonstandard
625 type that exists only for this purpose.
626 @end deftp
628 @comment stddef.h
629 @comment ISO
630 @deftp {Data Type} size_t
631 This is an unsigned integer type used to represent the sizes of objects.
632 The result of the @code{sizeof} operator is of this type, and functions
633 such as @code{malloc} (@pxref{Unconstrained Allocation}) and
634 @code{memcpy} (@pxref{Copying and Concatenation}) accept arguments of
635 this type to specify object sizes.
637 @strong{Usage Note:} @code{size_t} is the preferred way to declare any
638 arguments or variables that hold the size of an object.
639 @end deftp
641 In the GNU system @code{size_t} is equivalent to either
642 @w{@code{unsigned int}} or @w{@code{unsigned long int}}.  These types
643 have identical properties on the GNU system, and for most purposes, you
644 can use them interchangeably.  However, they are distinct as data types,
645 which makes a difference in certain contexts.
647 For example, when you specify the type of a function argument in a
648 function prototype, it makes a difference which one you use.  If the
649 system header files declare @code{malloc} with an argument of type
650 @code{size_t} and you declare @code{malloc} with an argument of type
651 @code{unsigned int}, you will get a compilation error if @code{size_t}
652 happens to be @code{unsigned long int} on your system.  To avoid any
653 possibility of error, when a function argument or value is supposed to
654 have type @code{size_t}, never declare its type in any other way.
656 @strong{Compatibility Note:} Implementations of C before the advent of
657 @w{ISO C} generally used @code{unsigned int} for representing object sizes
658 and @code{int} for pointer subtraction results.  They did not
659 necessarily define either @code{size_t} or @code{ptrdiff_t}.  Unix
660 systems did define @code{size_t}, in @file{sys/types.h}, but the
661 definition was usually a signed type.
663 @node Data Type Measurements
664 @section Data Type Measurements
666 Most of the time, if you choose the proper C data type for each object
667 in your program, you need not be concerned with just how it is
668 represented or how many bits it uses.  When you do need such
669 information, the C language itself does not provide a way to get it.
670 The header files @file{limits.h} and @file{float.h} contain macros
671 which give you this information in full detail.
673 @menu
674 * Width of Type::           How many bits does an integer type hold?
675 * Range of Type::           What are the largest and smallest values
676                              that an integer type can hold?
677 * Floating Type Macros::    Parameters that measure the floating point types.
678 * Structure Measurement::   Getting measurements on structure types.
679 @end menu
681 @node Width of Type
682 @subsection Computing the Width of an Integer Data Type
683 @cindex integer type width
684 @cindex width of integer type
685 @cindex type measurements, integer
687 The most common reason that a program needs to know how many bits are in
688 an integer type is for using an array of @code{long int} as a bit vector.
689 You can access the bit at index @var{n} with
691 @smallexample
692 vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
693 @end smallexample
695 @noindent
696 provided you define @code{LONGBITS} as the number of bits in a
697 @code{long int}.
699 @pindex limits.h
700 There is no operator in the C language that can give you the number of
701 bits in an integer data type.  But you can compute it from the macro
702 @code{CHAR_BIT}, defined in the header file @file{limits.h}.
704 @table @code
705 @comment limits.h
706 @comment ISO
707 @item CHAR_BIT
708 This is the number of bits in a @code{char}---eight, on most systems.
709 The value has type @code{int}.
711 You can compute the number of bits in any data type @var{type} like
712 this:
714 @smallexample
715 sizeof (@var{type}) * CHAR_BIT
716 @end smallexample
717 @end table
719 @node Range of Type
720 @subsection Range of an Integer Type
721 @cindex integer type range
722 @cindex range of integer type
723 @cindex limits, integer types
725 Suppose you need to store an integer value which can range from zero to
726 one million.  Which is the smallest type you can use?  There is no
727 general rule; it depends on the C compiler and target machine.  You can
728 use the @samp{MIN} and @samp{MAX} macros in @file{limits.h} to determine
729 which type will work.
731 Each signed integer type has a pair of macros which give the smallest
732 and largest values that it can hold.  Each unsigned integer type has one
733 such macro, for the maximum value; the minimum value is, of course,
734 zero.
736 The values of these macros are all integer constant expressions.  The
737 @samp{MAX} and @samp{MIN} macros for @code{char} and @w{@code{short
738 int}} types have values of type @code{int}.  The @samp{MAX} and
739 @samp{MIN} macros for the other types have values of the same type
740 described by the macro---thus, @code{ULONG_MAX} has type
741 @w{@code{unsigned long int}}.
743 @comment Extra blank lines make it look better.
744 @table @code
745 @comment limits.h
746 @comment ISO
747 @item SCHAR_MIN
749 This is the minimum value that can be represented by a @w{@code{signed char}}.
751 @comment limits.h
752 @comment ISO
753 @item SCHAR_MAX
754 @comment limits.h
755 @comment ISO
756 @itemx UCHAR_MAX
758 These are the maximum values that can be represented by a
759 @w{@code{signed char}} and @w{@code{unsigned char}}, respectively.
761 @comment limits.h
762 @comment ISO
763 @item CHAR_MIN
765 This is the minimum value that can be represented by a @code{char}.
766 It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero
767 otherwise.
769 @comment limits.h
770 @comment ISO
771 @item CHAR_MAX
773 This is the maximum value that can be represented by a @code{char}.
774 It's equal to @code{SCHAR_MAX} if @code{char} is signed, or
775 @code{UCHAR_MAX} otherwise.
777 @comment limits.h
778 @comment ISO
779 @item SHRT_MIN
781 This is the minimum value that can be represented by a @w{@code{signed
782 short int}}.  On most machines that the GNU C library runs on,
783 @code{short} integers are 16-bit quantities.
785 @comment limits.h
786 @comment ISO
787 @item SHRT_MAX
788 @comment limits.h
789 @comment ISO
790 @itemx USHRT_MAX
792 These are the maximum values that can be represented by a
793 @w{@code{signed short int}} and @w{@code{unsigned short int}},
794 respectively.
796 @comment limits.h
797 @comment ISO
798 @item INT_MIN
800 This is the minimum value that can be represented by a @w{@code{signed
801 int}}.  On most machines that the GNU C system runs on, an @code{int} is
802 a 32-bit quantity.
804 @comment limits.h
805 @comment ISO
806 @item INT_MAX
807 @comment limits.h
808 @comment ISO
809 @itemx UINT_MAX
811 These are the maximum values that can be represented by, respectively,
812 the type @w{@code{signed int}} and the type @w{@code{unsigned int}}.
814 @comment limits.h
815 @comment ISO
816 @item LONG_MIN
818 This is the minimum value that can be represented by a @w{@code{signed
819 long int}}.  On most machines that the GNU C system runs on, @code{long}
820 integers are 32-bit quantities, the same size as @code{int}.
822 @comment limits.h
823 @comment ISO
824 @item LONG_MAX
825 @comment limits.h
826 @comment ISO
827 @itemx ULONG_MAX
829 These are the maximum values that can be represented by a
830 @w{@code{signed long int}} and @code{unsigned long int}, respectively.
832 @comment limits.h
833 @comment GNU
834 @item LONG_LONG_MIN
836 This is the minimum value that can be represented by a @w{@code{signed
837 long long int}}.  On most machines that the GNU C system runs on,
838 @w{@code{long long}} integers are 64-bit quantities.
840 @comment limits.h
841 @comment GNU
842 @item LONG_LONG_MAX
843 @comment limits.h
844 @comment ISO
845 @itemx ULONG_LONG_MAX
847 These are the maximum values that can be represented by a @code{signed
848 long long int} and @code{unsigned long long int}, respectively.
850 @comment limits.h
851 @comment GNU
852 @item WCHAR_MAX
854 This is the maximum value that can be represented by a @code{wchar_t}.
855 @xref{Wide Char Intro}.
856 @end table
858 The header file @file{limits.h} also defines some additional constants
859 that parameterize various operating system and file system limits.  These
860 constants are described in @ref{System Configuration}.
862 @node Floating Type Macros
863 @subsection Floating Type Macros
864 @cindex floating type measurements
865 @cindex measurements of floating types
866 @cindex type measurements, floating
867 @cindex limits, floating types
869 The specific representation of floating point numbers varies from
870 machine to machine.  Because floating point numbers are represented
871 internally as approximate quantities, algorithms for manipulating
872 floating point data often need to take account of the precise details of
873 the machine's floating point representation.
875 Some of the functions in the C library itself need this information; for
876 example, the algorithms for printing and reading floating point numbers
877 (@pxref{I/O on Streams}) and for calculating trigonometric and
878 irrational functions (@pxref{Mathematics}) use it to avoid round-off
879 error and loss of accuracy.  User programs that implement numerical
880 analysis techniques also often need this information in order to
881 minimize or compute error bounds.
883 The header file @file{float.h} describes the format used by your
884 machine.
886 @menu
887 * Floating Point Concepts::     Definitions of terminology.
888 * Floating Point Parameters::   Details of specific macros.
889 * IEEE Floating Point::         The measurements for one common
890                                  representation.
891 @end menu
893 @node Floating Point Concepts
894 @subsubsection Floating Point Representation Concepts
896 This section introduces the terminology for describing floating point
897 representations.
899 You are probably already familiar with most of these concepts in terms
900 of scientific or exponential notation for floating point numbers.  For
901 example, the number @code{123456.0} could be expressed in exponential
902 notation as @code{1.23456e+05}, a shorthand notation indicating that the
903 mantissa @code{1.23456} is multiplied by the base @code{10} raised to
904 power @code{5}.
906 More formally, the internal representation of a floating point number
907 can be characterized in terms of the following parameters:
909 @itemize @bullet
910 @item
911 @cindex sign (of floating point number)
912 The @dfn{sign} is either @code{-1} or @code{1}.
914 @item
915 @cindex base (of floating point number)
916 @cindex radix (of floating point number)
917 The @dfn{base} or @dfn{radix} for exponentiation, an integer greater
918 than @code{1}.  This is a constant for a particular representation.
920 @item
921 @cindex exponent (of floating point number)
922 The @dfn{exponent} to which the base is raised.  The upper and lower
923 bounds of the exponent value are constants for a particular
924 representation.
926 @cindex bias (of floating point number exponent)
927 Sometimes, in the actual bits representing the floating point number,
928 the exponent is @dfn{biased} by adding a constant to it, to make it
929 always be represented as an unsigned quantity.  This is only important
930 if you have some reason to pick apart the bit fields making up the
931 floating point number by hand, which is something for which the GNU
932 library provides no support.  So this is ignored in the discussion that
933 follows.
935 @item
936 @cindex mantissa (of floating point number)
937 @cindex significand (of floating point number)
938 The @dfn{mantissa} or @dfn{significand}, an unsigned integer which is a
939 part of each floating point number.
941 @item
942 @cindex precision (of floating point number)
943 The @dfn{precision} of the mantissa.  If the base of the representation
944 is @var{b}, then the precision is the number of base-@var{b} digits in
945 the mantissa.  This is a constant for a particular representation.
947 @cindex hidden bit (of floating point number mantissa)
948 Many floating point representations have an implicit @dfn{hidden bit} in
949 the mantissa.  This is a bit which is present virtually in the mantissa,
950 but not stored in memory because its value is always 1 in a normalized
951 number.  The precision figure (see above) includes any hidden bits.
953 Again, the GNU library provides no facilities for dealing with such
954 low-level aspects of the representation.
955 @end itemize
957 The mantissa of a floating point number actually represents an implicit
958 fraction whose denominator is the base raised to the power of the
959 precision.  Since the largest representable mantissa is one less than
960 this denominator, the value of the fraction is always strictly less than
961 @code{1}.  The mathematical value of a floating point number is then the
962 product of this fraction, the sign, and the base raised to the exponent.
964 @cindex normalized floating point number
965 We say that the floating point number is @dfn{normalized} if the
966 fraction is at least @code{1/@var{b}}, where @var{b} is the base.  In
967 other words, the mantissa would be too large to fit if it were
968 multiplied by the base.  Non-normalized numbers are sometimes called
969 @dfn{denormal}; they contain less precision than the representation
970 normally can hold.
972 If the number is not normalized, then you can subtract @code{1} from the
973 exponent while multiplying the mantissa by the base, and get another
974 floating point number with the same value.  @dfn{Normalization} consists
975 of doing this repeatedly until the number is normalized.  Two distinct
976 normalized floating point numbers cannot be equal in value.
978 (There is an exception to this rule: if the mantissa is zero, it is
979 considered normalized.  Another exception happens on certain machines
980 where the exponent is as small as the representation can hold.  Then
981 it is impossible to subtract @code{1} from the exponent, so a number
982 may be normalized even if its fraction is less than @code{1/@var{b}}.)
984 @node Floating Point Parameters
985 @subsubsection Floating Point Parameters
987 @pindex float.h
988 These macro definitions can be accessed by including the header file
989 @file{float.h} in your program.
991 Macro names starting with @samp{FLT_} refer to the @code{float} type,
992 while names beginning with @samp{DBL_} refer to the @code{double} type
993 and names beginning with @samp{LDBL_} refer to the @code{long double}
994 type.  (Currently GCC does not support @code{long double} as a distinct
995 data type, so the values for the @samp{LDBL_} constants are equal to the
996 corresponding constants for the @code{double} type.)@refill
998 Of these macros, only @code{FLT_RADIX} is guaranteed to be a constant
999 expression.  The other macros listed here cannot be reliably used in
1000 places that require constant expressions, such as @samp{#if}
1001 preprocessing directives or in the dimensions of static arrays.
1003 Although the @w{ISO C} standard specifies minimum and maximum values for
1004 most of these parameters, the GNU C implementation uses whatever values
1005 describe the floating point representation of the target machine.  So in
1006 principle GNU C actually satisfies the @w{ISO C} requirements only if the
1007 target machine is suitable.  In practice, all the machines currently
1008 supported are suitable.
1010 @table @code
1011 @comment float.h
1012 @comment ISO
1013 @item FLT_ROUNDS
1014 This value characterizes the rounding mode for floating point addition.
1015 The following values indicate standard rounding modes:
1017 @need 750
1019 @table @code
1020 @item -1
1021 The mode is indeterminable.
1022 @item 0
1023 Rounding is towards zero.
1024 @item 1
1025 Rounding is to the nearest number.
1026 @item 2
1027 Rounding is towards positive infinity.
1028 @item 3
1029 Rounding is towards negative infinity.
1030 @end table
1032 @noindent
1033 Any other value represents a machine-dependent nonstandard rounding
1034 mode.
1036 On most machines, the value is @code{1}, in accordance with the IEEE
1037 standard for floating point.
1039 Here is a table showing how certain values round for each possible value
1040 of @code{FLT_ROUNDS}, if the other aspects of the representation match
1041 the IEEE single-precision standard.
1043 @smallexample
1044                 0      1             2             3
1045  1.00000003    1.0    1.0           1.00000012    1.0
1046  1.00000007    1.0    1.00000012    1.00000012    1.0
1047 -1.00000003   -1.0   -1.0          -1.0          -1.00000012
1048 -1.00000007   -1.0   -1.00000012   -1.0          -1.00000012
1049 @end smallexample
1051 @comment float.h
1052 @comment ISO
1053 @item FLT_RADIX
1054 This is the value of the base, or radix, of exponent representation.
1055 This is guaranteed to be a constant expression, unlike the other macros
1056 described in this section.  The value is 2 on all machines we know of
1057 except the IBM 360 and derivatives.
1059 @comment float.h
1060 @comment ISO
1061 @item FLT_MANT_DIG
1062 This is the number of base-@code{FLT_RADIX} digits in the floating point
1063 mantissa for the @code{float} data type.  The following expression
1064 yields @code{1.0} (even though mathematically it should not) due to the
1065 limited number of mantissa digits:
1067 @smallexample
1068 float radix = FLT_RADIX;
1070 1.0f + 1.0f / radix / radix / @dots{} / radix
1071 @end smallexample
1073 @noindent
1074 where @code{radix} appears @code{FLT_MANT_DIG} times.
1076 @comment float.h
1077 @comment ISO
1078 @item DBL_MANT_DIG
1079 @itemx LDBL_MANT_DIG
1080 This is the number of base-@code{FLT_RADIX} digits in the floating point
1081 mantissa for the data types @code{double} and @code{long double},
1082 respectively.
1084 @comment Extra blank lines make it look better.
1085 @comment float.h
1086 @comment ISO
1087 @item FLT_DIG
1089 This is the number of decimal digits of precision for the @code{float}
1090 data type.  Technically, if @var{p} and @var{b} are the precision and
1091 base (respectively) for the representation, then the decimal precision
1092 @var{q} is the maximum number of decimal digits such that any floating
1093 point number with @var{q} base 10 digits can be rounded to a floating
1094 point number with @var{p} base @var{b} digits and back again, without
1095 change to the @var{q} decimal digits.
1097 The value of this macro is supposed to be at least @code{6}, to satisfy
1098 @w{ISO C}.
1100 @comment float.h
1101 @comment ISO
1102 @item DBL_DIG
1103 @itemx LDBL_DIG
1105 These are similar to @code{FLT_DIG}, but for the data types
1106 @code{double} and @code{long double}, respectively.  The values of these
1107 macros are supposed to be at least @code{10}.
1109 @comment float.h
1110 @comment ISO
1111 @item FLT_MIN_EXP
1112 This is the smallest possible exponent value for type @code{float}.
1113 More precisely, is the minimum negative integer such that the value
1114 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
1115 normalized floating point number of type @code{float}.
1117 @comment float.h
1118 @comment ISO
1119 @item DBL_MIN_EXP
1120 @itemx LDBL_MIN_EXP
1122 These are similar to @code{FLT_MIN_EXP}, but for the data types
1123 @code{double} and @code{long double}, respectively.
1125 @comment float.h
1126 @comment ISO
1127 @item FLT_MIN_10_EXP
1128 This is the minimum negative integer such that @code{10} raised to this
1129 power minus 1 can be represented as a normalized floating point number
1130 of type @code{float}.  This is supposed to be @code{-37} or even less.
1132 @comment float.h
1133 @comment ISO
1134 @item DBL_MIN_10_EXP
1135 @itemx LDBL_MIN_10_EXP
1136 These are similar to @code{FLT_MIN_10_EXP}, but for the data types
1137 @code{double} and @code{long double}, respectively.
1139 @comment float.h
1140 @comment ISO
1141 @item FLT_MAX_EXP
1142 This is the largest possible exponent value for type @code{float}.  More
1143 precisely, this is the maximum positive integer such that value
1144 @code{FLT_RADIX} raised to this power minus 1 can be represented as a
1145 floating point number of type @code{float}.
1147 @comment float.h
1148 @comment ISO
1149 @item DBL_MAX_EXP
1150 @itemx LDBL_MAX_EXP
1151 These are similar to @code{FLT_MAX_EXP}, but for the data types
1152 @code{double} and @code{long double}, respectively.
1154 @comment float.h
1155 @comment ISO
1156 @item FLT_MAX_10_EXP
1157 This is the maximum positive integer such that @code{10} raised to this
1158 power minus 1 can be represented as a normalized floating point number
1159 of type @code{float}.  This is supposed to be at least @code{37}.
1161 @comment float.h
1162 @comment ISO
1163 @item DBL_MAX_10_EXP
1164 @itemx LDBL_MAX_10_EXP
1165 These are similar to @code{FLT_MAX_10_EXP}, but for the data types
1166 @code{double} and @code{long double}, respectively.
1168 @comment float.h
1169 @comment ISO
1170 @item FLT_MAX
1172 The value of this macro is the maximum number representable in type
1173 @code{float}.  It is supposed to be at least @code{1E+37}.  The value
1174 has type @code{float}.
1176 The smallest representable number is @code{- FLT_MAX}.
1178 @comment float.h
1179 @comment ISO
1180 @item DBL_MAX
1181 @itemx LDBL_MAX
1183 These are similar to @code{FLT_MAX}, but for the data types
1184 @code{double} and @code{long double}, respectively.  The type of the
1185 macro's value is the same as the type it describes.
1187 @comment float.h
1188 @comment ISO
1189 @item FLT_MIN
1191 The value of this macro is the minimum normalized positive floating
1192 point number that is representable in type @code{float}.  It is supposed
1193 to be no more than @code{1E-37}.
1195 @comment float.h
1196 @comment ISO
1197 @item DBL_MIN
1198 @itemx LDBL_MIN
1200 These are similar to @code{FLT_MIN}, but for the data types
1201 @code{double} and @code{long double}, respectively.  The type of the
1202 macro's value is the same as the type it describes.
1204 @comment float.h
1205 @comment ISO
1206 @item FLT_EPSILON
1208 This is the minimum positive floating point number of type @code{float}
1209 such that @code{1.0 + FLT_EPSILON != 1.0} is true.  It's supposed to
1210 be no greater than @code{1E-5}.
1212 @comment float.h
1213 @comment ISO
1214 @item DBL_EPSILON
1215 @itemx LDBL_EPSILON
1217 These are similar to @code{FLT_EPSILON}, but for the data types
1218 @code{double} and @code{long double}, respectively.  The type of the
1219 macro's value is the same as the type it describes.  The values are not
1220 supposed to be greater than @code{1E-9}.
1221 @end table
1223 @node IEEE Floating Point
1224 @subsubsection IEEE Floating Point
1225 @cindex IEEE floating point representation
1226 @cindex floating point, IEEE
1228 Here is an example showing how the floating type measurements come out
1229 for the most common floating point representation, specified by the
1230 @cite{IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std
1231 754-1985)}.  Nearly all computers designed since the 1980s use this
1232 format.
1234 The IEEE single-precision float representation uses a base of 2.  There
1235 is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total
1236 precision is 24 base-2 digits), and an 8-bit exponent that can represent
1237 values in the range -125 to 128, inclusive.
1239 So, for an implementation that uses this representation for the
1240 @code{float} data type, appropriate values for the corresponding
1241 parameters are:
1243 @smallexample
1244 FLT_RADIX                             2
1245 FLT_MANT_DIG                         24
1246 FLT_DIG                               6
1247 FLT_MIN_EXP                        -125
1248 FLT_MIN_10_EXP                      -37
1249 FLT_MAX_EXP                         128
1250 FLT_MAX_10_EXP                      +38
1251 FLT_MIN                 1.17549435E-38F
1252 FLT_MAX                 3.40282347E+38F
1253 FLT_EPSILON             1.19209290E-07F
1254 @end smallexample
1256 Here are the values for the @code{double} data type:
1258 @smallexample
1259 DBL_MANT_DIG                         53
1260 DBL_DIG                              15
1261 DBL_MIN_EXP                       -1021
1262 DBL_MIN_10_EXP                     -307
1263 DBL_MAX_EXP                        1024
1264 DBL_MAX_10_EXP                      308
1265 DBL_MAX         1.7976931348623157E+308
1266 DBL_MIN         2.2250738585072014E-308
1267 DBL_EPSILON     2.2204460492503131E-016
1268 @end smallexample
1270 @node Structure Measurement
1271 @subsection Structure Field Offset Measurement
1273 You can use @code{offsetof} to measure the location within a structure
1274 type of a particular structure member.
1276 @comment stddef.h
1277 @comment ISO
1278 @deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
1279 This expands to a integer constant expression that is the offset of the
1280 structure member named @var{member} in a the structure type @var{type}.
1281 For example, @code{offsetof (struct s, elem)} is the offset, in bytes,
1282 of the member @code{elem} in a @code{struct s}.
1284 This macro won't work if @var{member} is a bit field; you get an error
1285 from the C compiler in that case.
1286 @end deftypefn