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