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})
+@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.
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 not defined, @code{assert_perror} tests the value of
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
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}
assign the value of one variable of type @code{va_list} to another variable
of the same type.
-@comment stdarg.h
-@comment GNU
-@deftypefn {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
-The @code{__va_copy} macro allows copying of objects of 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}.
-This macro is a GNU extension but it will hopefully also be available in
-the next update of the ISO C standard.
+@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} you should always be prepared for the
+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:
+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);
+#ifdef va_copy
+ va_copy (save, ap);
#else
save = ap;
#endif
@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;
-see @ref{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} only 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
+@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}}.
@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
+
+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
-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
+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}.
+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.
-@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}.
-
-@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
@comment Extra blank lines make it look better.
@vtable @code
-@comment limits.h
-@comment ISO
@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 @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 @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 @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 ISO
@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 @theglibc{} runs on,
@w{@code{long long}} integers are 64-bit quantities.
-@comment limits.h
-@comment ISO
@item LLONG_MAX
-@comment limits.h
-@comment ISO
@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
-@comment limits.h
-@comment GNU
@itemx LONG_LONG_MAX
-@comment limits.h
-@comment GNU
@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.
-@comment limits.h
-@comment GNU
@item WCHAR_MAX
+@standards{GNU, limits.h}
This is the maximum value that can be represented by a @code{wchar_t}.
@xref{Extended Char Intro}.
supported are suitable.
@vtable @code
-@comment float.h
-@comment ISO
@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
+@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 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
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
+@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