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