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