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