-@node Language Features, Library Summary, System Configuration, Top
+@c This node must have no pointers.
+@node Language Features
+@c @node Language Features, Library Summary, , Top
+@c %MENU% C language features provided by the library
@appendix C Language Facilities in the Library
Some of the facilities implemented by the C library really should be
would rather have a program crash, visibly, than have it return nonsense
without indicating anything might be wrong.
-@comment assert.h
-@comment ISO
@deftypefn Macro void assert (int @var{expression})
-Verify the programmer's belief that @var{expression} should be nonzero
-at this point in the program.
+@standards{ISO, assert.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c assert_fail_base calls asprintf, and fflushes stderr.
+Verify the programmer's belief that @var{expression} is nonzero at
+this point in the program.
If @code{NDEBUG} is not defined, @code{assert} tests the value of
@var{expression}. If it is false (zero), @code{assert} aborts the
on the standard error stream @code{stderr} (@pxref{Standard Streams}).
The filename and line number are taken from the C preprocessor macros
@code{__FILE__} and @code{__LINE__} and specify where the call to
-@code{assert} was written. When using the GNU C compiler, the name of
+@code{assert} was made. When using the GNU C compiler, the name of
the function which calls @code{assert} is taken from the built-in
variable @code{__PRETTY_FUNCTION__}; with older compilers, the function
name and following colon are omitted.
not only where the program crashes, but also what error was returned.
The @code{assert_perror} macro makes this easy.
-@comment assert.h
-@comment GNU
@deftypefn Macro void assert_perror (int @var{errnum})
+@standards{GNU, assert.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c assert_fail_base calls asprintf, and fflushes stderr.
Similar to @code{assert}, but verifies that @var{errnum} is zero.
-If @code{NDEBUG} is defined, @code{assert_perror} tests the value of
+If @code{NDEBUG} is not defined, @code{assert_perror} tests the value of
@var{errnum}. If it is nonzero, @code{assert_perror} aborts the program
-after a printing a message of the form:
+after printing a message of the form:
@smallexample
@file{@var{file}}:@var{linenum}: @var{function}: @var{error text}
Like @code{assert}, if @code{NDEBUG} is defined before @file{assert.h}
is included, the @code{assert_perror} macro does absolutely nothing. It
does not evaluate the argument, so @var{errnum} should not have any side
-effects. It is best for @var{errnum} to be a just simple variable
+effects. It is best for @var{errnum} to be just a simple variable
reference; often it will be @code{errno}.
This macro is a GNU extension.
@strong{Usage note:} The @code{assert} facility is designed for
detecting @emph{internal inconsistency}; it is not suitable for
-reporting invalid input or improper usage by @emph{the user} of the
+reporting invalid input or improper usage by the @emph{user} of the
program.
The information in the diagnostic messages printed by the @code{assert}
-macro is intended to help you, the programmer, track down the cause of a
-bug, but is not really useful for telling a user of your program why his
-or her input was invalid or why a command could not be carried out. So
-you can't use @code{assert} or @code{assert_perror} to print the error
-messages for these eventualities.
-
-What's more, your program should not abort when given invalid input, as
-@code{assert} would do---it should exit with nonzero status (@pxref{Exit
-Status}) after printing its error messages, or perhaps read another
-command or move on to the next input file.
+and @code{assert_perror} macro is intended to help you, the programmer,
+track down the cause of a bug, but is not really useful for telling a user
+of your program why his or her input was invalid or why a command could not
+be carried out. What's more, your program should not abort when given
+invalid input, as @code{assert} would do---it should exit with nonzero
+status (@pxref{Exit Status}) after printing its error messages, or perhaps
+read another command or move on to the next input file.
@xref{Error Messages}, for information on printing error messages for
problems that @emph{do not} represent bugs in the program.
variable arguments functions.
* Argument Macros:: Detailed specification of the macros
for accessing variable arguments.
-* Old Varargs:: The pre-ISO way of defining variadic functions.
@end menu
@node Variadic Prototypes
@end smallexample
@noindent
-outlines a definition of a function @code{func} which returns an
-@code{int} and takes two required arguments, a @code{const char *} and
-an @code{int}. These are followed by any number of anonymous
-arguments.
+defines a function @code{func} which returns an @code{int} and takes two
+required arguments, a @code{const char *} and an @code{int}. These are
+followed by any number of anonymous arguments.
@strong{Portability note:} For some C compilers, the last required
argument must not be declared @code{register} in the function
You indicate that you are finished with the argument pointer variable by
calling @code{va_end}.
-(In practice, with most C compilers, calling @code{va_end} does nothing
-and you do not really need to call it. This is always true in the GNU C
-compiler. But you might as well call @code{va_end} just in case your
-program is someday compiled with a peculiar compiler.)
+(In practice, with most C compilers, calling @code{va_end} does nothing.
+This is always true in the GNU C compiler. But you might as well call
+@code{va_end} just in case your program is someday compiled with a peculiar
+compiler.)
@end enumerate
@xref{Argument Macros}, for the full definitions of @code{va_start},
as an argument to another function and perform all or part of step 2
there.
-You can perform the entire sequence of the three steps multiple times
+You can perform the entire sequence of three steps multiple times
within a single function invocation. If you want to ignore the optional
arguments, you can do these steps zero times.
There is no general way for a function to determine the number and type
of the optional arguments it was called with. So whoever designs the
-function typically designs a convention for the caller to tell it how
-many arguments it has, and what kind. It is up to you to define an
-appropriate calling convention for each variadic function, and write all
-calls accordingly.
+function typically designs a convention for the caller to specify the number
+and type of arguments. It is up to you to define an appropriate calling
+convention for each variadic function, and write all calls accordingly.
One kind of calling convention is to pass the number of optional
arguments as one of the fixed arguments. This convention works provided
@cindex calling variadic functions
@cindex declaring variadic functions
-You don't have to write anything special when you call a variadic function.
-Just write the arguments (required arguments, followed by optional ones)
-inside parentheses, separated by commas, as usual. But you should prepare
-by declaring the function with a prototype, and you must know how the
-argument values are converted.
+You don't have to do anything special to call a variadic function.
+Just put the arguments (required arguments, followed by optional ones)
+inside parentheses, separated by commas, as usual. But you must declare
+the function with a prototype and know how the argument values are converted.
In principle, functions that are @emph{defined} to be variadic must also
be @emph{declared} to be variadic using a function prototype whenever
promoted to either @code{int} or @w{@code{unsigned int}}, as
appropriate; and that objects of type @code{float} are promoted to type
@code{double}. So, if the caller passes a @code{char} as an optional
-argument, it is promoted to an @code{int}, and the function should get
+argument, it is promoted to an @code{int}, and the function can access
it with @code{va_arg (@var{ap}, int)}.
Conversion of the required arguments is controlled by the function
These macros are defined in the header file @file{stdarg.h}.
@pindex stdarg.h
-@comment stdarg.h
-@comment ISO
@deftp {Data Type} va_list
+@standards{ISO, stdarg.h}
The type @code{va_list} is used for argument pointer variables.
@end deftp
-@comment stdarg.h
-@comment ISO
@deftypefn {Macro} void va_start (va_list @var{ap}, @var{last-required})
+@standards{ISO, stdarg.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is no longer provided by glibc, but rather by the compiler.
This macro initializes the argument pointer variable @var{ap} to point
to the first of the optional arguments of the current function;
@var{last-required} must be the last required argument to the function.
-
-@xref{Old Varargs}, for an alternate definition of @code{va_start}
-found in the header file @file{varargs.h}.
@end deftypefn
-@comment stdarg.h
-@comment ISO
@deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type})
+@standards{ISO, stdarg.h}
+@safety{@prelim{}@mtsafe{@mtsrace{:ap}}@assafe{}@acunsafe{@acucorrupt{}}}
+@c This is no longer provided by glibc, but rather by the compiler.
+@c Unlike the other va_ macros, that either start/end the lifetime of
+@c the va_list object or don't modify it, this one modifies ap, and it
+@c may leave it in a partially updated state.
The @code{va_arg} macro returns the value of the next optional argument,
and modifies the value of @var{ap} to point to the subsequent argument.
Thus, successive uses of @code{va_arg} return successive optional
of the actual argument.
@end deftypefn
-@comment stdarg.h
-@comment ISO
@deftypefn {Macro} void va_end (va_list @var{ap})
+@standards{ISO, stdarg.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is no longer provided by glibc, but rather by the compiler.
This ends the use of @var{ap}. After a @code{va_end} call, further
@code{va_arg} calls with the same @var{ap} may not work. You should invoke
@code{va_end} before returning from the function in which @code{va_start}
was invoked with the same @var{ap} argument.
-In the GNU C library, @code{va_end} does nothing, and you need not ever
+In @theglibc{}, @code{va_end} does nothing, and you need not ever
use it except for reasons of portability.
@refill
@end deftypefn
+Sometimes it is necessary to parse the list of parameters more than once
+or one wants to remember a certain position in the parameter list. To
+do this, one will have to make a copy of the current value of the
+argument. But @code{va_list} is an opaque type and one cannot necessarily
+assign the value of one variable of type @code{va_list} to another variable
+of the same type.
+
+@deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
+@deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
+@standardsx{va_copy, C99, stdarg.h}
+@standardsx{__va_copy, GNU, stdarg.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{va_copy} macro allows copying of objects of type
+@code{va_list} even if this is not an integral type. The argument pointer
+in @var{dest} is initialized to point to the same argument as the
+pointer in @var{src}.
+
+@code{va_copy} was added in ISO C99. When building for strict
+conformance to ISO C90 (@samp{gcc -std=c90}), it is not available.
+GCC provides @code{__va_copy}, as an extension, in any standards mode;
+before GCC 3.0, it was the only macro for this functionality.
+
+These macros are no longer provided by @theglibc{}, but rather by the
+compiler.
+@end deftypefn
+
+If you want to use @code{va_copy} and be portable to pre-C99 systems,
+you should always be prepared for the
+possibility that this macro will not be available. On architectures where a
+simple assignment is invalid, hopefully @code{va_copy} @emph{will} be available,
+so one should always write something like this if concerned about
+pre-C99 portability:
+
+@smallexample
+@{
+ va_list ap, save;
+ @dots{}
+#ifdef va_copy
+ va_copy (save, ap);
+#else
+ save = ap;
+#endif
+ @dots{}
+@}
+@end smallexample
+
+
@node Variadic Example
@subsection Example of a Variadic Function
@include add.c.texi
@end smallexample
-@node Old Varargs
-@subsubsection Old-Style Variadic Functions
-
-@pindex varargs.h
-Before @w{ISO C}, programmers used a slightly different facility for
-writing variadic functions. The GNU C compiler still supports it;
-currently, it is more portable than the @w{ISO C} facility, since support
-for @w{ISO C} is still not universal. The header file which defines the
-old-fashioned variadic facility is called @file{varargs.h}.
-
-Using @file{varargs.h} is almost the same as using @file{stdarg.h}.
-There is no difference in how you call a variadic function;
-@xref{Calling Variadics}. The only difference is in how you define
-them. First of all, you must use old-style non-prototype syntax, like
-this:
-
-@smallexample
-tree
-build (va_alist)
- va_dcl
-@{
-@end smallexample
-
-Secondly, you must give @code{va_start} just one argument, like this:
-
-@smallexample
- va_list p;
- va_start (p);
-@end smallexample
-
-These are the special macros used for defining old-style variadic
-functions:
-
-@comment varargs.h
-@comment Unix
-@deffn Macro va_alist
-This macro stands for the argument name list required in a variadic
-function.
-@end deffn
-
-@comment varargs.h
-@comment Unix
-@deffn Macro va_dcl
-This macro declares the implicit argument or arguments for a variadic
-function.
-@end deffn
-
-@comment varargs.h
-@comment Unix
-@deftypefn {Macro} void va_start (va_list @var{ap})
-This macro, as defined in @file{varargs.h}, initializes the argument
-pointer variable @var{ap} to point to the first argument of the current
-function.
-@end deftypefn
-
-The other argument macros, @code{va_arg} and @code{va_end}, are the same
-in @file{varargs.h} as in @file{stdarg.h}; see @ref{Argument Macros} for
-details.
-
-It does not work to include both @file{varargs.h} and @file{stdarg.h} in
-the same compilation; they define @code{va_start} in conflicting ways.
-
@node Null Pointer Constant
@section Null Pointer Constant
@cindex null pointer constant
*}. The preferred way to write a null pointer constant is with
@code{NULL}.
-@comment stddef.h
-@comment ISO
@deftypevr Macro {void *} NULL
+@standards{ISO, stddef.h}
This is a null pointer constant.
@end deftypevr
The result of subtracting two pointers in C is always an integer, but the
precise data type varies from C compiler to C compiler. Likewise, the
data type of the result of @code{sizeof} also varies between compilers.
-ISO defines standard aliases for these two types, so you can refer to
+ISO C defines standard aliases for these two types, so you can refer to
them in a portable fashion. They are defined in the header file
@file{stddef.h}.
@pindex stddef.h
-@comment stddef.h
-@comment ISO
@deftp {Data Type} ptrdiff_t
+@standards{ISO, stddef.h}
This is the signed integer type of the result of subtracting two
pointers. For example, with the declaration @code{char *p1, *p2;}, the
expression @code{p2 - p1} is of type @code{ptrdiff_t}. This will
type that exists only for this purpose.
@end deftp
-@comment stddef.h
-@comment ISO
@deftp {Data Type} size_t
+@standards{ISO, stddef.h}
This is an unsigned integer type used to represent the sizes of objects.
The result of the @code{sizeof} operator is of this type, and functions
such as @code{malloc} (@pxref{Unconstrained Allocation}) and
-@code{memcpy} (@pxref{Copying and Concatenation}) accept arguments of
-this type to specify object sizes.
+@code{memcpy} (@pxref{Copying Strings and Arrays}) accept arguments of
+this type to specify object sizes. On systems using @theglibc{}, this
+will be @w{@code{unsigned int}} or @w{@code{unsigned long int}}.
@strong{Usage Note:} @code{size_t} is the preferred way to declare any
arguments or variables that hold the size of an object.
@end deftp
-In the GNU system @code{size_t} is equivalent to either
-@w{@code{unsigned int}} or @w{@code{unsigned long int}}. These types
-have identical properties on the GNU system, and for most purposes, you
-can use them interchangeably. However, they are distinct as data types,
-which makes a difference in certain contexts.
-
-For example, when you specify the type of a function argument in a
-function prototype, it makes a difference which one you use. If the
-system header files declare @code{malloc} with an argument of type
-@code{size_t} and you declare @code{malloc} with an argument of type
-@code{unsigned int}, you will get a compilation error if @code{size_t}
-happens to be @code{unsigned long int} on your system. To avoid any
-possibility of error, when a function argument or value is supposed to
-have type @code{size_t}, never declare its type in any other way.
-
@strong{Compatibility Note:} Implementations of C before the advent of
@w{ISO C} generally used @code{unsigned int} for representing object sizes
and @code{int} for pointer subtraction results. They did not
@end menu
@node Width of Type
-@subsection Computing the Width of an Integer Data Type
+@subsection Width of an Integer Type
@cindex integer type width
@cindex width of integer type
@cindex type measurements, integer
+@pindex limits.h
-The most common reason that a program needs to know how many bits are in
-an integer type is for using an array of @code{long int} as a bit vector.
-You can access the bit at index @var{n} with
+TS 18661-1:2014 defines macros for the width of integer types (the
+number of value and sign bits). One benefit of these macros is they
+can be used in @code{#if} preprocessor directives, whereas
+@code{sizeof} cannot. The following macros are defined in
+@file{limits.h}.
+
+@vtable @code
+@item CHAR_WIDTH
+@itemx SCHAR_WIDTH
+@itemx UCHAR_WIDTH
+@itemx SHRT_WIDTH
+@itemx USHRT_WIDTH
+@itemx INT_WIDTH
+@itemx UINT_WIDTH
+@itemx LONG_WIDTH
+@itemx ULONG_WIDTH
+@itemx LLONG_WIDTH
+@itemx ULLONG_WIDTH
+@standards{ISO, limits.h}
+These are the widths of the types @code{char}, @code{signed char},
+@code{unsigned char}, @code{short int}, @code{unsigned short int},
+@code{int}, @code{unsigned int}, @code{long int}, @code{unsigned long
+int}, @code{long long int} and @code{unsigned long long int},
+respectively.
+@end vtable
+
+Further such macros are defined in @file{stdint.h}. Apart from those
+for types specified by width (@pxref{Integers}), the following are
+defined:
+
+@vtable @code
+@item INTPTR_WIDTH
+@itemx UINTPTR_WIDTH
+@itemx PTRDIFF_WIDTH
+@itemx SIG_ATOMIC_WIDTH
+@itemx SIZE_WIDTH
+@itemx WCHAR_WIDTH
+@itemx WINT_WIDTH
+@standards{ISO, stdint.h}
+These are the widths of the types @code{intptr_t}, @code{uintptr_t},
+@code{ptrdiff_t}, @code{sig_atomic_t}, @code{size_t}, @code{wchar_t}
+and @code{wint_t}, respectively.
+@end vtable
+
+A common reason that a program needs to know how many bits are in an
+integer type is for using an array of @code{unsigned long int} as a
+bit vector. You can access the bit at index @var{n} with:
@smallexample
-vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
+vector[@var{n} / ULONG_WIDTH] & (1UL << (@var{n} % ULONG_WIDTH))
@end smallexample
-@noindent
-provided you define @code{LONGBITS} as the number of bits in a
-@code{long int}.
-
-@pindex limits.h
-There is no operator in the C language that can give you the number of
-bits in an integer data type. But you can compute it from the macro
-@code{CHAR_BIT}, defined in the header file @file{limits.h}.
+Before @code{ULONG_WIDTH} was a part of the C language,
+@code{CHAR_BIT} was used to compute the number of bits in an integer
+data type.
-@table @code
-@comment limits.h
-@comment ISO
-@item CHAR_BIT
-This is the number of bits in a @code{char}---eight, on most systems.
-The value has type @code{int}.
+@deftypevr Macro int CHAR_BIT
+@standards{C90, limits.h}
+This is the number of bits in a @code{char}. POSIX.1-2001 requires
+this to be 8.
+@end deftypevr
-You can compute the number of bits in any data type @var{type} like
+The number of bits in any data type @var{type} can be computed like
this:
@smallexample
sizeof (@var{type}) * CHAR_BIT
@end smallexample
-@end table
+
+That expression includes padding bits as well as value and sign bits.
+On all systems supported by @theglibc{}, standard integer types other
+than @code{_Bool} do not have any padding bits.
+
+@strong{Portability Note:} One cannot actually easily compute the
+number of usable bits in a portable manner.
@node Range of Type
@subsection Range of an Integer Type
@w{@code{unsigned long int}}.
@comment Extra blank lines make it look better.
-@table @code
-@comment limits.h
-@comment ISO
+@vtable @code
@item SCHAR_MIN
+@standards{ISO, limits.h}
This is the minimum value that can be represented by a @w{@code{signed char}}.
-@comment limits.h
-@comment ISO
@item SCHAR_MAX
-@comment limits.h
-@comment ISO
@itemx UCHAR_MAX
+@standards{ISO, limits.h}
These are the maximum values that can be represented by a
@w{@code{signed char}} and @w{@code{unsigned char}}, respectively.
-@comment limits.h
-@comment ISO
@item CHAR_MIN
+@standards{ISO, limits.h}
This is the minimum value that can be represented by a @code{char}.
It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero
otherwise.
-@comment limits.h
-@comment ISO
@item CHAR_MAX
+@standards{ISO, limits.h}
This is the maximum value that can be represented by a @code{char}.
It's equal to @code{SCHAR_MAX} if @code{char} is signed, or
@code{UCHAR_MAX} otherwise.
-@comment limits.h
-@comment ISO
@item SHRT_MIN
+@standards{ISO, limits.h}
This is the minimum value that can be represented by a @w{@code{signed
-short int}}. On most machines that the GNU C library runs on,
+short int}}. On most machines that @theglibc{} runs on,
@code{short} integers are 16-bit quantities.
-@comment limits.h
-@comment ISO
@item SHRT_MAX
-@comment limits.h
-@comment ISO
@itemx USHRT_MAX
+@standards{ISO, limits.h}
These are the maximum values that can be represented by a
@w{@code{signed short int}} and @w{@code{unsigned short int}},
respectively.
-@comment limits.h
-@comment ISO
@item INT_MIN
+@standards{ISO, limits.h}
This is the minimum value that can be represented by a @w{@code{signed
-int}}. On most machines that the GNU C system runs on, an @code{int} is
+int}}. On most machines that @theglibc{} runs on, an @code{int} is
a 32-bit quantity.
-@comment limits.h
-@comment ISO
@item INT_MAX
-@comment limits.h
-@comment ISO
@itemx UINT_MAX
+@standards{ISO, limits.h}
These are the maximum values that can be represented by, respectively,
the type @w{@code{signed int}} and the type @w{@code{unsigned int}}.
-@comment limits.h
-@comment ISO
@item LONG_MIN
+@standards{ISO, limits.h}
This is the minimum value that can be represented by a @w{@code{signed
-long int}}. On most machines that the GNU C system runs on, @code{long}
+long int}}. On most machines that @theglibc{} runs on, @code{long}
integers are 32-bit quantities, the same size as @code{int}.
-@comment limits.h
-@comment ISO
@item LONG_MAX
-@comment limits.h
-@comment ISO
@itemx ULONG_MAX
+@standards{ISO, limits.h}
These are the maximum values that can be represented by a
@w{@code{signed long int}} and @code{unsigned long int}, respectively.
-@comment limits.h
-@comment GNU
-@item LONG_LONG_MIN
+@item LLONG_MIN
+@standards{ISO, limits.h}
This is the minimum value that can be represented by a @w{@code{signed
-long long int}}. On most machines that the GNU C system runs on,
+long long int}}. On most machines that @theglibc{} runs on,
@w{@code{long long}} integers are 64-bit quantities.
-@comment limits.h
-@comment GNU
-@item LONG_LONG_MAX
-@comment limits.h
-@comment ISO
-@itemx ULONG_LONG_MAX
+@item LLONG_MAX
+@itemx ULLONG_MAX
+@standards{ISO, limits.h}
These are the maximum values that can be represented by a @code{signed
long long int} and @code{unsigned long long int}, respectively.
-@comment limits.h
-@comment GNU
+@item LONG_LONG_MIN
+@itemx LONG_LONG_MAX
+@itemx ULONG_LONG_MAX
+@standards{GNU, limits.h}
+These are obsolete names for @code{LLONG_MIN}, @code{LLONG_MAX}, and
+@code{ULLONG_MAX}. They are only available if @code{_GNU_SOURCE} is
+defined (@pxref{Feature Test Macros}). In GCC versions prior to 3.0,
+these were the only names available.
+
@item WCHAR_MAX
+@standards{GNU, limits.h}
This is the maximum value that can be represented by a @code{wchar_t}.
-@xref{Wide Char Intro}.
-@end table
+@xref{Extended Char Intro}.
+@end vtable
The header file @file{limits.h} also defines some additional constants
that parameterize various operating system and file system limits. These
the exponent is @dfn{biased} by adding a constant to it, to make it
always be represented as an unsigned quantity. This is only important
if you have some reason to pick apart the bit fields making up the
-floating point number by hand, which is something for which the GNU
-library provides no support. So this is ignored in the discussion that
+floating point number by hand, which is something for which @theglibc{}
+provides no support. So this is ignored in the discussion that
follows.
@item
@cindex mantissa (of floating point number)
@cindex significand (of floating point number)
-The @dfn{mantissa} or @dfn{significand}, an unsigned integer which is a
+The @dfn{mantissa} or @dfn{significand} is an unsigned integer which is a
part of each floating point number.
@item
but not stored in memory because its value is always 1 in a normalized
number. The precision figure (see above) includes any hidden bits.
-Again, the GNU library provides no facilities for dealing with such
+Again, @theglibc{} provides no facilities for dealing with such
low-level aspects of the representation.
@end itemize
-The mantissa of a floating point number actually represents an implicit
-fraction whose denominator is the base raised to the power of the
-precision. Since the largest representable mantissa is one less than
-this denominator, the value of the fraction is always strictly less than
-@code{1}. The mathematical value of a floating point number is then the
-product of this fraction, the sign, and the base raised to the exponent.
+The mantissa of a floating point number represents an implicit fraction
+whose denominator is the base raised to the power of the precision. Since
+the largest representable mantissa is one less than this denominator, the
+value of the fraction is always strictly less than @code{1}. The
+mathematical value of a floating point number is then the product of this
+fraction, the sign, and the base raised to the exponent.
@cindex normalized floating point number
We say that the floating point number is @dfn{normalized} if the
Macro names starting with @samp{FLT_} refer to the @code{float} type,
while names beginning with @samp{DBL_} refer to the @code{double} type
and names beginning with @samp{LDBL_} refer to the @code{long double}
-type. (Currently GCC does not support @code{long double} as a distinct
-data type, so the values for the @samp{LDBL_} constants are equal to the
-corresponding constants for the @code{double} type.)@refill
+type. (If GCC does not support @code{long double} as a distinct data
+type on a target machine then the values for the @samp{LDBL_} constants
+are equal to the corresponding constants for the @code{double} type.)
Of these macros, only @code{FLT_RADIX} is guaranteed to be a constant
expression. The other macros listed here cannot be reliably used in
target machine is suitable. In practice, all the machines currently
supported are suitable.
-@table @code
-@comment float.h
-@comment ISO
+@vtable @code
@item FLT_ROUNDS
+@standards{C90, float.h}
This value characterizes the rounding mode for floating point addition.
The following values indicate standard rounding modes:
-1.00000007 -1.0 -1.00000012 -1.0 -1.00000012
@end smallexample
-@comment float.h
-@comment ISO
@item FLT_RADIX
-This is the value of the base, or radix, of exponent representation.
+@standards{C90, float.h}
+This is the value of the base, or radix, of the exponent representation.
This is guaranteed to be a constant expression, unlike the other macros
described in this section. The value is 2 on all machines we know of
except the IBM 360 and derivatives.
-@comment float.h
-@comment ISO
@item FLT_MANT_DIG
+@standards{C90, float.h}
This is the number of base-@code{FLT_RADIX} digits in the floating point
mantissa for the @code{float} data type. The following expression
yields @code{1.0} (even though mathematically it should not) due to the
@noindent
where @code{radix} appears @code{FLT_MANT_DIG} times.
-@comment float.h
-@comment ISO
@item DBL_MANT_DIG
@itemx LDBL_MANT_DIG
+@standards{C90, float.h}
This is the number of base-@code{FLT_RADIX} digits in the floating point
mantissa for the data types @code{double} and @code{long double},
respectively.
@comment Extra blank lines make it look better.
-@comment float.h
-@comment ISO
@item FLT_DIG
+@standards{C90, float.h}
This is the number of decimal digits of precision for the @code{float}
data type. Technically, if @var{p} and @var{b} are the precision and
The value of this macro is supposed to be at least @code{6}, to satisfy
@w{ISO C}.
-@comment float.h
-@comment ISO
@item DBL_DIG
@itemx LDBL_DIG
+@standards{C90, float.h}
These are similar to @code{FLT_DIG}, but for the data types
@code{double} and @code{long double}, respectively. The values of these
macros are supposed to be at least @code{10}.
-@comment float.h
-@comment ISO
@item FLT_MIN_EXP
+@standards{C90, float.h}
This is the smallest possible exponent value for type @code{float}.
-More precisely, is the minimum negative integer such that the value
+More precisely, it is the minimum negative integer such that the value
@code{FLT_RADIX} raised to this power minus 1 can be represented as a
normalized floating point number of type @code{float}.
-@comment float.h
-@comment ISO
@item DBL_MIN_EXP
@itemx LDBL_MIN_EXP
+@standards{C90, float.h}
These are similar to @code{FLT_MIN_EXP}, but for the data types
@code{double} and @code{long double}, respectively.
-@comment float.h
-@comment ISO
@item FLT_MIN_10_EXP
+@standards{C90, float.h}
This is the minimum negative integer such that @code{10} raised to this
power minus 1 can be represented as a normalized floating point number
of type @code{float}. This is supposed to be @code{-37} or even less.
-@comment float.h
-@comment ISO
@item DBL_MIN_10_EXP
@itemx LDBL_MIN_10_EXP
+@standards{C90, float.h}
These are similar to @code{FLT_MIN_10_EXP}, but for the data types
@code{double} and @code{long double}, respectively.
-@comment float.h
-@comment ISO
@item FLT_MAX_EXP
+@standards{C90, float.h}
This is the largest possible exponent value for type @code{float}. More
precisely, this is the maximum positive integer such that value
@code{FLT_RADIX} raised to this power minus 1 can be represented as a
floating point number of type @code{float}.
-@comment float.h
-@comment ISO
@item DBL_MAX_EXP
@itemx LDBL_MAX_EXP
+@standards{C90, float.h}
These are similar to @code{FLT_MAX_EXP}, but for the data types
@code{double} and @code{long double}, respectively.
-@comment float.h
-@comment ISO
@item FLT_MAX_10_EXP
+@standards{C90, float.h}
This is the maximum positive integer such that @code{10} raised to this
power minus 1 can be represented as a normalized floating point number
of type @code{float}. This is supposed to be at least @code{37}.
-@comment float.h
-@comment ISO
@item DBL_MAX_10_EXP
@itemx LDBL_MAX_10_EXP
+@standards{C90, float.h}
These are similar to @code{FLT_MAX_10_EXP}, but for the data types
@code{double} and @code{long double}, respectively.
-@comment float.h
-@comment ISO
@item FLT_MAX
+@standards{C90, float.h}
The value of this macro is the maximum number representable in type
@code{float}. It is supposed to be at least @code{1E+37}. The value
The smallest representable number is @code{- FLT_MAX}.
-@comment float.h
-@comment ISO
@item DBL_MAX
@itemx LDBL_MAX
+@standards{C90, float.h}
These are similar to @code{FLT_MAX}, but for the data types
@code{double} and @code{long double}, respectively. The type of the
macro's value is the same as the type it describes.
-@comment float.h
-@comment ISO
@item FLT_MIN
+@standards{C90, float.h}
The value of this macro is the minimum normalized positive floating
point number that is representable in type @code{float}. It is supposed
to be no more than @code{1E-37}.
-@comment float.h
-@comment ISO
@item DBL_MIN
@itemx LDBL_MIN
+@standards{C90, float.h}
These are similar to @code{FLT_MIN}, but for the data types
@code{double} and @code{long double}, respectively. The type of the
macro's value is the same as the type it describes.
-@comment float.h
-@comment ISO
@item FLT_EPSILON
+@standards{C90, float.h}
-This is the minimum positive floating point number of type @code{float}
-such that @code{1.0 + FLT_EPSILON != 1.0} is true. It's supposed to
+This is the difference between 1 and the smallest floating point
+number of type @code{float} that is greater than 1. It's supposed to
be no greater than @code{1E-5}.
-@comment float.h
-@comment ISO
@item DBL_EPSILON
@itemx LDBL_EPSILON
+@standards{C90, float.h}
These are similar to @code{FLT_EPSILON}, but for the data types
@code{double} and @code{long double}, respectively. The type of the
macro's value is the same as the type it describes. The values are not
supposed to be greater than @code{1E-9}.
-@end table
+@end vtable
@node IEEE Floating Point
@subsubsection IEEE Floating Point
You can use @code{offsetof} to measure the location within a structure
type of a particular structure member.
-@comment stddef.h
-@comment ISO
@deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
-This expands to a integer constant expression that is the offset of the
-structure member named @var{member} in a the structure type @var{type}.
+@standards{ISO, stddef.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is no longer provided by glibc, but rather by the compiler.
+This expands to an integer constant expression that is the offset of the
+structure member named @var{member} in the structure type @var{type}.
For example, @code{offsetof (struct s, elem)} is the offset, in bytes,
of the member @code{elem} in a @code{struct s}.
projects / thirdparty / glibc.git / blobdiff