#ifdef __STDC_IEC_60559_DFP__
_Decimal32 acoshd32(_Decimal32 x);
_Decimal64 acoshd64(_Decimal64 x);
_Decimal128 acoshd128(_Decimal128 x);
#endif
Description
2 The acosh functions compute the (nonnegative) arc hyperbolic cosine of x. A domain error occurs
for arguments less than 1.
Returns
3 The acosh functions return arcosh x in the interval [0, +∞].
<IP_ADDRESS> [The asinh functions]
1 Synopsis
#include <math.h>
double asinh(double x);
float asinhf(float x);
long double asinhl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 asinhd32(_Decimal32 x);
_Decimal64 asinhd64(_Decimal64 x);
_Decimal128 asinhd128(_Decimal128 x);
#endif
Description
2 The asinh functions compute the arc hyperbolic sine of x. A range error occurs if nonzero x is too
close to zero.
Returns
3 The asinh functions return arsinh x.
<IP_ADDRESS> [The atanh functions]
1 Synopsis
#include <math.h>
double atanh(double x);
float atanhf(float x);
long double atanhl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 atanhd32(_Decimal32 x);
_Decimal64 atanhd64(_Decimal64 x);
_Decimal128 atanhd128(_Decimal128 x);
#endif
Description
2 The atanh functions compute the arc hyperbolic tangent of x. A domain error occurs for arguments
not in the interval [−1, +1]. A pole error may occur if the argument equals-1 or +1 . A range error
occurs if nonzero x is too close to zero.
Returns
3 The atanh functions return artanh x.
<IP_ADDRESS> [The cosh functions]
1 Synopsis
#include <math.h>
double cosh(double x);
float coshf(float x);
long double coshl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 coshd32(_Decimal32 x);
_Decimal64 coshd64(_Decimal64 x);
_Decimal128 coshd128(_Decimal128 x);
#endif
Description
2 The cosh functions compute the hyperbolic cosine of x. A range error occurs if the magnitude of
finite x is too large.
Returns
3 The cosh functions return cosh x.
<IP_ADDRESS> [The sinh functions]
1 Synopsis
#include <math.h>
double sinh(double x);
float sinhf(float x);
long double sinhl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 sinhd32(_Decimal32 x);
_Decimal64 sinhd64(_Decimal64 x);
_Decimal128 sinhd128(_Decimal128 x);
#endif
Description
2 The sinh functions compute the hyperbolic sine of x. A range error occurs if the magnitude of finite
x is too large or if nonzero x is too close to zero.
Returns
3 The sinh functions return sinh x.
<IP_ADDRESS> [The tanh functions]
1 Synopsis
#include <math.h>
double tanh(double x);
float tanhf(float x);
long double tanhl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 tanhd32(_Decimal32 x);
_Decimal64 tanhd64(_Decimal64 x);
_Decimal128 tanhd128(_Decimal128 x);
#endif
Description
2 The tanh functions compute the hyperbolic tangent of x. A range error occurs if nonzero x is too
close to zero.
Returns
3 The tanh functions return tanh x.
7.12.6 [Exponential and logarithmic functions]
<IP_ADDRESS> [The exp functions]
1 Synopsis
#include <math.h>
double exp(double x);
float expf(float x);
long double expl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 expd32(_Decimal32 x);
_Decimal64 expd64(_Decimal64 x);
_Decimal128 expd128(_Decimal128 x);
#endif
Description
2 The exp functions compute the base-e exponential of x. A range error occurs if the magnitude of
finite x is too large.
Returns
3 The exp functions return ex .
<IP_ADDRESS> [The exp10 functions]
1 Synopsis
#include <math.h>
double exp10(double x);
float exp10f(float x);
long double exp10l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 exp10d32(_Decimal32 x);
_Decimal64 exp10d64(_Decimal64 x);
_Decimal128 exp10d128(_Decimal128 x);
#endif
Description
2 The exp10 functions compute the base-10 exponential of x. A range error occurs if the magnitude of
finite x is too large.
Returns
3 The exp10 functions return 10x .
<IP_ADDRESS> [The exp10m1 functions]
1 Synopsis
#include <math.h>
double exp10m1(double x);
float exp10m1f(float x);
long double exp10m1l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 exp10m1d32(_Decimal32 x);
_Decimal64 exp10m1d64(_Decimal64 x);
_Decimal128 exp10m1d128(_Decimal128 x);
#endif
Description
2 The exp10m1 functions compute the base-10 exponential of the argument, minus 1. A range error
occurs if positive finite x is too large or if nonzero x is too close to zero.
Returns
3 The exp10m1 functions return 10x − 1.
<IP_ADDRESS> [The exp2 functions]
1 Synopsis
#include <math.h>
double exp2(double x);
float exp2f(float x);
long double exp2l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 exp2d32(_Decimal32 x);
_Decimal64 exp2d64(_Decimal64 x);
_Decimal128 exp2d128(_Decimal128 x);
#endif
Description
2 The exp2 functions compute the base-2 exponential of x. A range error occurs if the magnitude of
finite x is too large.
Returns
3 The exp2 functions return 2x .
<IP_ADDRESS> [The exp2m1 functions]
1 Synopsis
#include <math.h>
double exp2m1(double x);
float exp2m1f(float x);
long double exp2m1l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 exp2m1d32(_Decimal32 x);
_Decimal64 exp2m1d64(_Decimal64 x);
_Decimal128 exp2m1d128(_Decimal128 x);
#endif
Description
2 The exp2m1 functions compute the base-2 exponential of the argument, minus 1. A range error
occurs if positive finite x is too large or if nonzero x is too close to zero.
Returns
3 The exp2m1 functions return 2x − 1.
<IP_ADDRESS> [The expm1 functions]
1 Synopsis
#include <math.h>
double expm1(double x);
float expm1f(float x);
long double expm1l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 expm1d32(_Decimal32 x);
_Decimal64 expm1d64(_Decimal64 x);
_Decimal128 expm1d128(_Decimal128 x);
#endif
Description
2 The expm1 functions compute the base-e exponential of the argument, minus 1. A range error occurs
if positive finite x is too large or if nonzero x is too close to zero. [291]
Returns
Footnote 291) For small magnitude x , expm1(x) is expected to be more accurate than exp(x)-1.
3 The expm1 functions return ex − 1.
<IP_ADDRESS> [The frexp functions]
1 Synopsis
#include <math.h>
double frexp(double value, int *p);
float frexpf(float value, int *p);
long double frexpl(long double value, int *p);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 frexpd32(_Decimal32 value, int *p);
_Decimal64 frexpd64(_Decimal64 value, int *p);
_Decimal128 frexpd128(_Decimal128 value, int *p);
#endif
Description
2 The frexp functions break a floating-point number into a normalized fraction and an integer
exponent. They store the integer in the int object pointed to by p. If the type of the function is a
standard floating type, the exponent is an integral power of 2. If the type of the function is a decimal
floating type, the exponent is an integral power of 10.
Returns
3 If value is not a floating-point number or if the integral power is outside the range of int, the results
are unspecified. Otherwise, the frexp functions return the value x, such that x has a magnitude
in the interval [ 12 , [1] or zero, and value equals x × 2*p , when the type of the function is a standard
floating type; or x has a magnitude in the interval [1/10, [1] or zero, and value equals x × 10*p , when
the type of the function is a decimal floating type. If value is zero, both parts of the result are zero.
Footnote 1) This document is designed to promote the portability of C programs among a variety of data-processing systems. It is
intended for use by implementors and programmers. Annex J gives an overview of portability issues that a C program might
encounter.
Footnote 1) This document is designed to promote the portability of C programs among a variety of data-processing systems. It is
intended for use by implementors and programmers. Annex J gives an overview of portability issues that a C program might
encounter.
<IP_ADDRESS> [The ilogb functions]
1 Synopsis
#include <math.h>
int ilogb(double x);
int ilogbf(float x);
int ilogbl(long double x);
#ifdef __STDC_IEC_60559_DFP__
int ilogbd32(_Decimal32 x);
int ilogbd64(_Decimal64 x);
int ilogbd128(_Decimal128 x);
#endif
Description
2 The ilogb functions extract the exponent of x as a signed int value. If x is zero they compute the
value FP_ILOGB0; if x is infinite they compute the value INT_MAX; if x is a NaN they compute the
value FP_ILOGBNAN; otherwise, they are equivalent to calling the corresponding logb function and
converting the returned value to type int. A domain error or range error may occur if x is zero,
infinite, or NaN. If the correct value is outside the range of the return type, the numeric result is
unspecified and a domain error or range error may occur.
Returns
3 The ilogb functions return the exponent of x as a signed int value.
Forward references: the logb functions (<IP_ADDRESS>).
<IP_ADDRESS> [The ldexp functions]
1 Synopsis
#include <math.h>
double ldexp(double x, int p);
float ldexpf(float x, int p);
long double ldexpl(long double x, int p);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 ldexpd32(_Decimal32 x, int p);
_Decimal64 ldexpd64(_Decimal64 x, int p);
_Decimal128 ldexpd128(_Decimal128 x, int p);
#endif
Description
2 The ldexp functions multiply a floating-point number by an integral power of 2 when the type of
the function is a standard floating type, or by an integral power of 10 when the type of the function
is a decimal floating type. A range error occurs for some finite x, depending on p.
Returns
3 The ldexp functions return x × 2p when the type of the function is a standard floating type, or return
x × 10p when the type of the function is a decimal floating type.
<IP_ADDRESS> [The llogb functions]
1 Synopsis
#include <math.h>
long int llogb(double x);
long int llogbf(float x);
long int llogbl(long double x);
#ifdef __STDC_IEC_60559_DFP__
long int llogbd32(_Decimal32 x);
long int llogbd64(_Decimal64 x);
long int llogbd128(_Decimal128 x);
#endif
Description
2 The llogb functions extract the exponent of x as a signed long int value. If x is zero they compute
the value FP_LLOGB0; if x is infinite they compute the value LONG_MAX; if x is a NaN they compute
the value FP_LLOGBNAN; otherwise, they are equivalent to calling the corresponding logb function
and converting the returned value to type long int. A domain error or range error may occur if x is
zero, infinite, or NaN. If the correct value is outside the range of the return type, the numeric result
is unspecified.
Returns
3 The llogb functions return the exponent of x as a signed long int value.
Forward references: the logb functions (<IP_ADDRESS>).
<IP_ADDRESS> [The log functions]
1 Synopsis
#include <math.h>
double log(double x);
float logf(float x);
long double logl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 logd32(_Decimal32 x);
_Decimal64 logd64(_Decimal64 x);
_Decimal128 logd128(_Decimal128 x);
#endif
Description
2 The log functions compute the base-e (natural) logarithm of x. A domain error occurs if the
argument is less than zero. A pole error may occur if the argument is zero.
Returns
3 The log functions return loge x.
<IP_ADDRESS> [The log10 functions]
1 Synopsis
#include <math.h>
double log10(double x);
float log10f(float x);
long double log10l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 log10d32(_Decimal32 x);
_Decimal64 log10d64(_Decimal64 x);
_Decimal128 log10d128(_Decimal128 x);
#endif
Description
2 The log10 functions compute the base-10 (common) logarithm of x. A domain error occurs if the
argument is less than zero. A pole error may occur if the argument is zero.
Returns
3 The log10 functions return log10 x.
<IP_ADDRESS> [The log10p1 functions]
1 Synopsis
#include <math.h>
double log10p1(double x);
float log10p1f(float x);
long double log10p1l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 log10p1d32(_Decimal32 x);
_Decimal64 log10p1d64(_Decimal64 x);
_Decimal128 log10p1d128(_Decimal128 x);
#endif
Description
2 The log10p1 functions compute the base-10 logarithm of 1 plus the argument. A domain error
occurs if the argument is less than −1. A pole error may occur if the argument equals −1. A range
error occurs if nonzero x is too close to zero.
Returns
3 The log10p1 functions return log10 (1 + x).
<IP_ADDRESS> [The log1p and logp1 functions]
1 Synopsis
#include <math.h>
double log1p(double x);
float log1pf(float x);
long double log1pl(long double x);
double logp1(double x);
float logp1f(float x);
long double logp1l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 log1pd32(_Decimal32 x);
_Decimal64 log1pd64(_Decimal64 x);
_Decimal128 log1pd128(_Decimal128 x);
_Decimal32 logp1d32(_Decimal32 x);
_Decimal64 logp1d64(_Decimal64 x);
_Decimal128 logp1d128(_Decimal128 x);
#endif
Description
2 The log1p functions are equivalent to the logp1 functions.[292] These functions compute the base-e
(natural) logarithm of 1 plus the argument.[293] A domain error occurs if the argument is less than
−1. A pole error may occur if the argument equals −1. A range error occurs if nonzero x is too close
to zero.
Returns
Footnote 292) The logp1 functions are preferred for name consistency with the log10p1 and log2p1 functions.
Footnote 293) For small magnitude x , logp1(x) is expected to be more accurate than log(1 + x).
3 The log1p and logp1 functions return loge (1 + x).
<IP_ADDRESS> [The log2 functions]
1 Synopsis
#include <math.h>
double log2(double x);
float log2f(float x);
long double log2l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 log2d32(_Decimal32 x);
_Decimal64 log2d64(_Decimal64 x);
_Decimal128 log2d128(_Decimal128 x);
#endif
Description
2 The log2 functions compute the base-2 logarithm of x. A domain error occurs if the argument is less
than zero. A pole error may occur if the argument is zero.
Returns
3 The log2 functions return log2 x.
<IP_ADDRESS> [The log2p1 functions]
1 Synopsis
#include <math.h>
double log2p1(double x);
float log2p1f(float x);
long double log2p1l(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 log2p1d32(_Decimal32 x);
_Decimal64 log2p1d64(_Decimal64 x);
_Decimal128 log2p1d128(_Decimal128 x);
#endif
Description
2 The log2p1 functions compute the base-2 logarithm of 1 plus the argument. A domain error occurs
if the argument is less than −1. A pole error may occur if the argument equals −1. A range error
occurs if nonzero x is too close to zero.
Returns
3 The log2p1 functions return log2 (1+x).
<IP_ADDRESS> [The logb functions]
1 Synopsis
#include <math.h>
double logb(double x);
float logbf(float x);
long double logbl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 logbd32(_Decimal32 x);
_Decimal64 logbd64(_Decimal64 x);
_Decimal128 logbd128(_Decimal128 x);
#endif
Description
2 The logb functions extract the exponent of x, as a signed integer value in floating-point format. If x
is subnormal it is treated as though it were normalized; thus, for positive finite x,
1 ≤ x × b−logb(x) < b
where b = FLT_RADIX if the type of the function is a standard floating type, or b = 10 if the type of
the function is a decimal floating type. A domain error or pole error may occur if the argument is
zero.
Returns
3 The logb functions return the signed exponent of x.
<IP_ADDRESS> [The modf functions]
1 Synopsis
#include <math.h>
double modf(double value, double *iptr);
float modff(float value, float *iptr);
long double modfl(long double value, long double *iptr);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 modfd32(_Decimal32 x, _Decimal32 *iptr);
_Decimal64 modfd64(_Decimal64 x, _Decimal64 *iptr);
_Decimal128 modfd128(_Decimal128 x, _Decimal128 *iptr);
#endif
Description
2 The modf functions break the argument value into integral and fractional parts, each of which has
the same type and sign as the argument. They store the integral part (in floating-point format) in the
object pointed to by iptr.
Returns
3 The modf functions return the signed fractional part of value.
<IP_ADDRESS> [The scalbn and scalbln functions]
1 Synopsis
#include <math.h>
double scalbn(double x, int n);
float scalbnf(float x, int n);
long double scalbnl(long double x, int n);
double scalbln(double x, long int n);
float scalblnf(float x, long int n);
long double scalblnl(long double x, long int n);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 scalbnd32(_Decimal32 x, int n);
_Decimal64 scalbnd64(_Decimal64 x, int n);
_Decimal128 scalbnd128(_Decimal128 x, int n);
_Decimal32 scalblnd32(_Decimal32 x, long int n);
_Decimal64 scalblnd64(_Decimal64 x, long int n);
_Decimal128 scalblnd128(_Decimal128 x, long int n);
#endif
Description
2 The scalbn and scalbln functions compute x × bn , where b = FLT_RADIX if the type of the function
is a standard floating type, or b = 10 if the type of the function is a decimal floating type. A range
error occurs for some finite x, depending on n.
Returns
3 The scalbn and scalbln functions return x × bn .
7.12.7 [Power and absolute-value functions]
<IP_ADDRESS> [The cbrt functions]
1 Synopsis
#include <math.h>
double cbrt(double x);
float cbrtf(float x);
long double cbrtl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 cbrtd32(_Decimal32 x);
_Decimal64 cbrtd64(_Decimal64 x);
_Decimal128 cbrtd128(_Decimal128 x);
#endif
Description
2 The cbrt functions compute the real cube root of x.
Returns
1
3 The cbrt functions return x 3 .
<IP_ADDRESS> [The compoundn functions]
1 Synopsis
#include <stdint.h>
#include <math.h>
double compoundn(double x, long long int n);
float compoundnf(float x, long long int n);
long double compoundnl(long double x, long long int n);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 compoundnd32(_Decimal32 x, long long int n);
_Decimal64 compoundnd64(_Decimal64 x, long long int n);
_Decimal128 compoundnd128(_Decimal128 x, long long int n);
#endif
Description
2 The compoundn functions compute 1 plus x, raised to the power n. A domain error occurs if x < −1.
Depending on n, a range error occurs if either positive finite x is too large or if x is too near but not
equal to-1 . A pole error may occur if x equals −1 and n < 0.
Returns
3 The compoundn functions return (1 + x)n .
<IP_ADDRESS> [The fabs functions]
1 Synopsis
#include <math.h>
double fabs(double x);
float fabsf(float x);
long double fabsl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fabsd32(_Decimal32 x);
_Decimal64 fabsd64(_Decimal64 x);
_Decimal128 fabsd128(_Decimal128 x);
#endif
Description
2 The fabs functions compute the absolute value of x.
Returns
3 The fabs functions return |x|.
<IP_ADDRESS> [The hypot functions]
1 Synopsis
#include <math.h>
double hypot(double x, double y);
float hypotf(float x, float y);
long double hypotl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 hypotd32(_Decimal32 x, _Decimal32 y);
_Decimal64 hypotd64(_Decimal64 x, _Decimal64 y);
_Decimal128 hypotd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The hypot functions compute the square root of the sum of the squares of x and y, without undue
overflow or underflow. A range error occurs for some finite arguments.
3
Returns
p
4 The hypot functions return x 2 + y2 .
<IP_ADDRESS> [The pow functions]
1 Synopsis
#include <math.h>
double pow(double x, double y);
float powf(float x, float y);
long double powl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 powd32(_Decimal32 x, _Decimal32 y);
_Decimal64 powd64(_Decimal64 x, _Decimal64 y);
_Decimal128 powd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The pow functions compute x raised to the power y. A domain error occurs if x is finite and less than
zero and y is finite and not an integer value. A domain error may occur if x is zero and y is zero.
Depending on y, a range error occurs if either the magnitude of nonzero finite x is too large or too
near zero. A domain error or pole error may occur if x is zero and y is less than zero.
Returns
3 The pow functions return xy .
<IP_ADDRESS> [The pown functions]
1 Synopsis
#include <stdint.h>
#include <math.h>
double pown(double x, long long int n);
float pownf(float x, long long int n);
long double pownl(long double x, long long int n);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 pownd32(_Decimal32 x, long long int n);
_Decimal64 pownd64(_Decimal64 x, long long int n);
_Decimal128 pownd128(_Decimal128 x, long long int n);
#endif
Description
2 The pown functions compute x raised to the nth power. A pole error may occur if x equals 0 and
n < 0. Depending on n, a range error occurs if either the magnitude of nonzero finite x is too large
or too near zero.
Returns
3 The pown functions return xn .
<IP_ADDRESS> [The powr functions]
1 Synopsis
#include <math.h>
double powr(double y, double x);
float powrf(float y, float x);
long double powrl(long double y, long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 powrd32(_Decimal32 y, _Decimal32 x);
_Decimal64 powrd64(_Decimal64 y, _Decimal64 x);
_Decimal128 powrd128(_Decimal128 y, _Decimal128 x);
#endif
Description
2 The powr functions compute x raised to the power y as ey loge x .[294] A domain error occurs if x < 0
or if x and y are both zero. Depending on y, a range error occurs if either positive nonzero finite x is
too large or too near zero. A pole error may occur if x equals zero and finite y < 0.
Returns
Footnote 294) Restricting the domain to that of the formula ey loge x is intended to better meet expectations for a continuous power
function and to allow implementations with fewer tests for special cases.
3 The powr functions return ey loge x .
<IP_ADDRESS> [The rootn functions]
1 Synopsis
#include <stdint.h>
#include <math.h>
double rootn(double x, long long int n);
float rootnf(float x, long long int n);
long double rootnl(long double x, long long int n);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 rootnd32(_Decimal32 x, long long int n);
_Decimal64 rootnd64(_Decimal64 x, long long int n);
_Decimal128 rootnd128(_Decimal128 x, long long int n);
#endif
Description
2 The rootn functions compute the principal nth root of x. A domain error occurs if n is 0 or if x < 0
and n is even. If n is −1, a range error occurs if either the magnitude of nonzero finite x is too large
or too near zero. A pole error may occur if x equals zero and n < 0.
Returns
1
3 The rootn functions return x n .
<IP_ADDRESS> [The rsqrt functions]
1 Synopsis
#include <math.h>
double rsqrt(double x);
float rsqrtf(float x);
long double rsqrtl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 rsqrtd32(_Decimal32 x);
_Decimal64 rsqrtd64(_Decimal64 x);
_Decimal128 rsqrtd128(_Decimal128 x);
#endif
Description
2 The rsqrt functions compute the reciprocal of the nonnegative square root of the argument. A
domain error occurs if the argument is less than zero. A pole error may occur if the argument equals
zero.
Returns
3 The rsqrt functions return √1x .
<IP_ADDRESS> [The sqrt functions]
1 Synopsis
#include <math.h>
double sqrt(double x);
float sqrtf(float x);
long double sqrtl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 sqrtd32(_Decimal32 x);
_Decimal64 sqrtd64(_Decimal64 x);
_Decimal128 sqrtd128(_Decimal128 x);
#endif
Description
2 The sqrt functions compute the nonnegative square root of x. A domain error occurs if the argument
is less than zero.
Returns
√
3 The sqrt functions return x.
7.12.8 [Error and gamma functions]
<IP_ADDRESS> [The erf functions]
1 Synopsis
#include <math.h>
double erf(double x);
float erff(float x);
long double erfl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 erfd32(_Decimal32 x);
_Decimal64 erfd64(_Decimal64 x);
_Decimal128 erfd128(_Decimal128 x);
#endif
Description
2 The erf functions compute the error function of x. A range error occurs if nonzero x is too close to
zero.
Returns
Rx −t2
3 The erf functions return erf x = √2π e dt.
0
<IP_ADDRESS> [The erfc functions]
1 Synopsis
#include <math.h>
double erfc(double x);
float erfcf(float x);
long double erfcl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 erfcd32(_Decimal32 x);
_Decimal64 erfcd64(_Decimal64 x);
_Decimal128 erfcd128(_Decimal128 x);
#endif
Description
2 The erfc functions compute the complementary error function of x. A range error occurs if positive
finite x is too large.
Returns
R∞ −t2
3 The erfc functions return erfc x = 1 − erf x = √2π e dt.
x
<IP_ADDRESS> [The lgamma functions]
1 Synopsis
#include <math.h>
double lgamma(double x);
float lgammaf(float x);
long double lgammal(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 lgammad32(_Decimal32 x);
_Decimal64 lgammad64(_Decimal64 x);
_Decimal128 lgammad128(_Decimal128 x);
#endif
Description
2 The lgamma functions compute the natural logarithm of the absolute value of gamma of x. A range
error occurs if positive finite x is too large. A pole error may occur if x is a negative integer or zero.
Returns
3 The lgamma functions return loge |Γ(x)|.
<IP_ADDRESS> [The tgamma functions]
1 Synopsis
#include <math.h>
double tgamma(double x);
float tgammaf(float x);
long double tgammal(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 tgammad32(_Decimal32 x);
_Decimal64 tgammad64(_Decimal64 x);
_Decimal128 tgammad128(_Decimal128 x);
#endif
Description
2 The tgamma functions compute the gamma function of x. A domain error or pole error may occur
if x is a negative integer or zero. A range error occurs for some negative finite x less than zero, if
positive finite x is too large, or nonzero x is too close to zero.
Returns
3 The tgamma functions return Γ(x).
7.12.9 [Nearest integer functions]
<IP_ADDRESS> [The ceil functions]
1 Synopsis
#include <math.h>
double ceil(double x);
float ceilf(float x);
long double ceill(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 ceild32(_Decimal32 x);
_Decimal64 ceild64(_Decimal64 x);
_Decimal128 ceild128(_Decimal128 x);
#endif
Description
2 The ceil functions compute the smallest integer value not less than x.
Returns
3 The ceil functions return ⌈x⌉, expressed as a floating-point number.
<IP_ADDRESS> [The floor functions]
1 Synopsis
#include <math.h>
double floor(double x);
float floorf(float x);
long double floorl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 floord32(_Decimal32 x);
_Decimal64 floord64(_Decimal64 x);
_Decimal128 floord128(_Decimal128 x);
#endif
Description
2 The floor functions compute the largest integer value not greater than x.
Returns
3 The floor functions return ⌊x⌋, expressed as a floating-point number.
<IP_ADDRESS> [The nearbyint functions]
1 Synopsis
#include <math.h>
double nearbyint(double x);
float nearbyintf(float x);
long double nearbyintl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 nearbyintd32(_Decimal32 x);
_Decimal64 nearbyintd64(_Decimal64 x);
_Decimal128 nearbyintd128(_Decimal128 x);
#endif
Description
2 The nearbyint functions round their argument to an integer value in floating-point format, using
the current rounding direction and without raising the "inexact" floating-point exception.
Returns
3 The nearbyint functions return the rounded integer value.
<IP_ADDRESS> [The rint functions]
1 Synopsis
#include <math.h>
double rint(double x);
float rintf(float x);
long double rintl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 rintd32(_Decimal32 x);
_Decimal64 rintd64(_Decimal64 x);
_Decimal128 rintd128(_Decimal128 x);
#endif
Description
2 The rint functions differ from the nearbyint functions (<IP_ADDRESS>) only in that the rint functions
may raise the "inexact" floating-point exception if the result differs in value from the argument.
Returns
3 The rint functions return the rounded integer value.
<IP_ADDRESS> [The lrint and llrint functions]
1 Synopsis
#include <math.h>
long int lrint(double x);
long int lrintf(float x);
long int lrintl(long double x);
long long int llrint(double x);
long long int llrintf(float x);
long long int llrintl(long double x);
#ifdef __STDC_IEC_60559_DFP__
long int lrintd32(_Decimal32 x);
long int lrintd64(_Decimal64 x);
long int lrintd128(_Decimal128 x);
long long int llrintd32(_Decimal32 x);
long long int llrintd64(_Decimal64 x);
long long int llrintd128(_Decimal128 x);
#endif
Description
2 The lrint and llrint functions round their argument to the nearest integer value, rounding
according to the current rounding direction. If the rounded value is outside the range of the return
type, the numeric result is unspecified and a domain error or range error may occur.
Returns
3 The lrint and llrint functions return the rounded integer value.
<IP_ADDRESS> [The round functions]
1 Synopsis
#include <math.h>
double round(double x);
float roundf(float x);
long double roundl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 roundd32(_Decimal32 x);
_Decimal64 roundd64(_Decimal64 x);
_Decimal128 roundd128(_Decimal128 x);
#endif
Description
2 The round functions round their argument to the nearest integer value in floating-point format,
rounding halfway cases away from zero, regardless of the current rounding direction.
Returns
3 The round functions return the rounded integer value.
<IP_ADDRESS> [The lround and llround functions]
1 Synopsis
#include <math.h>
long int lround(double x);
long int lroundf(float x);
long int lroundl(long double x);
long long int llround(double x);
long long int llroundf(float x);
long long int llroundl(long double x);
#ifdef __STDC_IEC_60559_DFP__
long int lroundd32(_Decimal32 x);
long int lroundd64(_Decimal64 x);
long int lroundd128(_Decimal128 x);
long long int llroundd32(_Decimal32 x);
long long int llroundd64(_Decimal64 x);
long long int llroundd128(_Decimal128 x);
#endif
Description
2 The lround and llround functions round their argument to the nearest integer value, rounding
halfway cases away from zero, regardless of the current rounding direction. If the rounded value is
outside the range of the return type, the numeric result is unspecified and a domain error or range
error may occur.
Returns
3 The lround and llround functions return the rounded integer value.
<IP_ADDRESS> [The roundeven functions]
1 Synopsis
#include <math.h>
double roundeven(double x);
float roundevenf(float x);
long double roundevenl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 roundevend32(_Decimal32 x);
_Decimal64 roundevend64(_Decimal64 x);
_Decimal128 roundevend128(_Decimal128 x);
#endif
Description
2 The roundeven functions round their argument to the nearest integer value in floating-point format,
rounding halfway cases to even (that is, to the nearest value that is an even integer), regardless of
the current rounding direction.
Returns
3 The roundeven functions return the rounded integer value.
<IP_ADDRESS> [The trunc functions]
1 Synopsis
#include <math.h>
double trunc(double x);
float truncf(float x);
long double truncl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 truncd32(_Decimal32 x);
_Decimal64 truncd64(_Decimal64 x);
_Decimal128 truncd128(_Decimal128 x);
#endif
Description
2 The trunc functions round their argument to the integer value, in floating format, nearest to but no
larger in magnitude than the argument.
Returns
3 The trunc functions return the truncated integer value.
<IP_ADDRESS> [The fromfp and ufromfp functions]
1 Synopsis
#include <stdint.h>
#include <math.h>
double fromfp(double x, int rnd, unsigned int width);
float fromfpf(float x, int rnd, unsigned int width);
long double fromfpl(long double x, int rnd, unsigned int width);
double ufromfp(double x, int rnd, unsigned int width);
float ufromfpf(float x, int rnd, unsigned int width);
long double ufromfpl(long double x, int rnd, unsigned int width);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fromfpd32(_Decimal32 x, int rnd, unsigned int width);
_Decimal64 fromfpd64(_Decimal64 x, int rnd, unsigned int width);
_Decimal128 fromfpd128(_Decimal128 x, int rnd, unsigned int width);
_Decimal32 ufromfpd32(_Decimal32 x, int rnd, unsigned int width);
_Decimal64 ufromfpd64(_Decimal64 x, int rnd, unsigned int width);
_Decimal128 ufromfpd128(_Decimal128 x, int rnd, unsigned int width);
#endif
Description
2 The fromfp and ufromfp functions round x, using the math rounding direction indicated by rnd, to
a signed or unsigned integer, respectively. If width is nonzero and the resulting integer is within the
range
— [−2(width−1) , 2(width−1) − 1], for signed
— [0, 2width − 1], for unsigned
then the functions return the integer value (represented in floating type). Otherwise, if width is
zero or x does not round to an integer within the range, the functions return a NaN (of the type of
the x argument, if available), else the value of x, and a domain error occurs. If the value of the
rnd argument is not equal to the value of a math rounding direction macro (7.12), the direction of
rounding is unspecified. The fromfp and ufromfp functions do not raise the "inexact" floating-point
exception.
Returns
3 The fromfp and ufromfp functions return the rounded integer value.
4 EXAMPLE Upward rounding of double x to type int, without raising the "inexact" floating-point exception, is achieved by
(int)fromfp(x, FP_INT_UPWARD, INT_WIDTH)
5 EXAMPLE Unsigned integer wrapping is not performed in
ufromfp(-3.0, FP_INT_UPWARD, UINT_WIDTH) /* domain error */
<IP_ADDRESS> [The fromfpx and ufromfpx functions]
1 Synopsis
#include <stdint.h>
#include <math.h>
double fromfpx(double x, int rnd, unsigned int width);
float fromfpxf(float x, int rnd, unsigned int width);
long double fromfpxl(long double x, int rnd, unsigned int width);
double ufromfpx(double x, int rnd, unsigned int width);
float ufromfpxf(float x, int rnd, unsigned int width);
long double ufromfpxl(long double x, int rnd, unsigned int width);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fromfpxd32(_Decimal32 x, int rnd, unsigned int width);
_Decimal64 fromfpxd64(_Decimal64 x, int rnd, unsigned int width);
_Decimal128 fromfpxd128(_Decimal128 x, int rnd, unsigned int width);
_Decimal32 ufromfpxd32(_Decimal32 x, int rnd, unsigned int width);
_Decimal64 ufromfpxd64(_Decimal64 x, int rnd, unsigned int width);
_Decimal128 ufromfpxd128(_Decimal128 x, int rnd, unsigned int width);
#endif
Description
2 The fromfpx and ufromfpx functions differ from the fromfp and ufromfp functions, respectively,
only in that the fromfpx and ufromfpx functions raise the "inexact" floating-point exception if a
rounded result not exceeding the specified width differs in value from the argument x.
Returns
3 The fromfpx and ufromfpx functions return the rounded integer value.
4 NOTE Conversions to integer types that are not required to raise the inexact exception can be done simply by rounding to
integral value in floating type and then converting to the target integer type. For example, the conversion of long double x
to uint64_t, using upward rounding, is done by
(uint64_t)ceill(x)
7.12.10 [Remainder functions]
<IP_ADDRESS> [The fmod functions]
1 Synopsis
#include <math.h>
double fmod(double x, double y);
float fmodf(float x, float y);
long double fmodl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fmodd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fmodd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fmodd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fmod functions compute the floating-point remainder of x/y.
Returns
3 The fmod functions return the value x − ny, for some integer n such that, if y is nonzero, the result
has the same sign as x and magnitude less than the magnitude of y. If y is zero, whether a domain
error occurs or the fmod functions return zero is implementation-defined.
<IP_ADDRESS> [The remainder functions]
1 Synopsis
#include <math.h>
double remainder(double x, double y);
float remainderf(float x, float y);
long double remainderl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 remainderd32(_Decimal32 x, _Decimal32 y);
_Decimal64 remainderd64(_Decimal64 x, _Decimal64 y);
_Decimal128 remainderd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The remainder functions compute the remainder x REM y required by IEC 60559. [295]
Returns
Footnote 295) "When y ̸= 0, the remainder r = x REM y is defined regardless of the rounding mode by the mathematical relation
r = x − ny, where n is the integer nearest the exact value of xy
; whenever |n − x
y
| = 12 , then n is even. If r = 0, its sign shall
be that of x." This definition is applicable for all implementations.
3 The remainder functions return x REM y. If y is zero, whether a domain error occurs or the functions
return zero is implementation-defined.
<IP_ADDRESS> [The remquo functions]
1 Synopsis
#include <math.h>
double remquo(double x, double y, int *quo);
float remquof(float x, float y, int *quo);
long double remquol(long double x, long double y, int *quo);
Description
2 The remquo functions compute the same remainder as the remainder functions. In the object pointed
to by quo they store a value whose sign is the sign of x/y and whose magnitude is congruent modulo
2n to the magnitude of the integral quotient of x/y, where n is an implementation-defined integer
greater than or equal to 3.
Returns
3 The remquo functions return x REM y. If y is zero, the value stored in the object pointed to by quo
is unspecified and whether a domain error occurs or the functions return zero is implementation-
defined.
4 NOTE There are no decimal floating-point versions of the remquo functions.
7.12.11 [Manipulation functions]
<IP_ADDRESS> [The copysign functions]
1 Synopsis
#include <math.h>
double copysign(double x, double y);
float copysignf(float x, float y);
long double copysignl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 copysignd32(_Decimal32 x, _Decimal32 y);
_Decimal64 copysignd64(_Decimal64 x, _Decimal64 y);
_Decimal128 copysignd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The copysign functions produce a value with the magnitude of x and the sign of y. If x or y is an
unsigned value, the sign (if any) of the result is implementation-defined. On implementations that
represent a signed zero but do not treat negative zero consistently in arithmetic operations, the
copysign functions should regard the sign of zero as positive.
Returns
3 The copysign functions return a value with the magnitude of x and the sign of y.
<IP_ADDRESS> [The nan functions]
1 Synopsis
#include <math.h>
double nan(const char *tagp);
float nanf(const char *tagp);
long double nanl(const char *tagp);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 nand32(const char *tagp);
_Decimal64 nand64(const char *tagp);
_Decimal128 nand128(const char *tagp);
#endif
Description
2 The nan, nanf, and nanl functions convert the string pointed to by tagp according to the following
rules. The call nan("n-char-sequence") is equivalent to strtod("NAN(n-char-sequence)", nullptr);
the call nan("") is equivalent to strtod("NAN()", nullptr). If tagp does not point to an empty
string or an n-char sequence, the call is equivalent to strtod("NAN", nullptr). Calls to nanf and
nanl are equivalent to the corresponding calls to strtof and strtold.
Returns
3 The nan functions return a quiet NaN, if available, with content indicated through tagp. If the
implementation does not support quiet NaNs, the functions return zero.
Forward references: the strtod, strtof, and strtold functions (<IP_ADDRESS>).
<IP_ADDRESS> [The nextafter functions]
1 Synopsis
#include <math.h>
double nextafter(double x, double y);
float nextafterf(float x, float y);
long double nextafterl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 nextafterd32(_Decimal32 x, _Decimal32 y);
_Decimal64 nextafterd64(_Decimal64 x, _Decimal64 y);
_Decimal128 nextafterd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The nextafter functions determine the next representable value, in the type of the function, after x
in the direction of y, where x and y are first converted to the type of the function[296] . The nextafter
functions return y if x equals y.
A range error occurs if the magnitude of x is the largest finite value representable in the type and the
result is infinite or not representable in the type.
Returns
Footnote 296) The argument values are converted to the type of the function, even by a macro implementation of the function.
3 The nextafter functions return the next representable value in the specified format after x in the
direction of y.
<IP_ADDRESS> [The nexttoward functions]
1 Synopsis
#include <math.h>
double nexttoward(double x, long double y);
float nexttowardf(float x, long double y);
long double nexttowardl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 nexttowardd32(_Decimal32 x, _Decimal128 y);
_Decimal64 nexttowardd64(_Decimal64 x, _Decimal128 y);
_Decimal128 nexttowardd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The nexttoward functions are equivalent to the nextafter functions except that the second param-
eter has type long double or _Decimal128 and the functions return y converted to the type of the
function if x equals y.[297]
Footnote 297) The result of the nexttoward functions is determined in the type of the function, without loss of range or precision in a
floating second argument.
<IP_ADDRESS> [The nextup functions]
1 Synopsis
#include <math.h>
double nextup(double x);
float nextupf(float x);
long double nextupl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 nextupd32(_Decimal32 x);
_Decimal64 nextupd64(_Decimal64 x);
_Decimal128 nextupd128(_Decimal128 x);
#endif
Description
2 The nextup functions determine the next representable value, in the type of the function, greater
than x. If x is the negative number of least magnitude in the type of x, nextup(x) is −0 if the
type has signed zeros and is 0 otherwise. If x is zero, nextup(x) is the positive number of least
magnitude in the type of x. If x is the positive number (finite or infinite) or maximum magnitude in
the type, nextup(x) is x.
Returns
3 The nextup functions return the next representable value in the specified type greater than x.
<IP_ADDRESS> [The nextdown functions]
1 Synopsis
#include <math.h>
double nextdown(double x);
float nextdownf(float x);
long double nextdownl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 nextdownd32(_Decimal32 x);
_Decimal64 nextdownd64(_Decimal64 x);
_Decimal128 nextdownd128(_Decimal128 x);
#endif
Description
2 The nextdown functions determine the next representable value, in the type of the function, less than
x . If x is the positive number of least magnitude in the type of x , nextdown(x) is +0 if the type has
signed zeros and is 0 otherwise. If x is zero, nextdown(x) is the negative number of least magnitude
in the type of x. If x is the negative number (finite or infinite) of maximum magnitude in the type,
nextdown(x) is x .
Returns
3 The nextdown functions return the next representable value in the specified type less than x.
<IP_ADDRESS> [The canonicalize functions]
1 Synopsis
#include <math.h>
int canonicalize(double * cx, const double * x);
int canonicalizef(float * cx, const float * x);
int canonicalizel(long double * cx, const long double * x);
#ifdef __STDC_IEC_60559_DFP__
int canonicalized32(_Decimal32 cx, const _Decimal32 * x);
int canonicalized64(_Decimal64 cx, const _Decimal64 * x);
int canonicalized128(_Decimal128 cx, const _Decimal128 * x);
#endif
Description
2 The canonicalize functions attempt to produce a canonical version of the floating-point repre-
sentation in the object pointed to by the argument x, as if to a temporary object of the specified
type, and store the canonical result in the object pointed to by the argument cx.[298] If the input *x
is a signaling NaN, the canonicalize functions are intended to store a canonical quiet NaN. If a
canonical result is not produced the object pointed to by cx is unchanged.
Returns
Footnote 298) Arguments x and cx may point to the same object.
3 The canonicalize functions return zero if a canonical result is stored in the object pointed to by cx.
Otherwise they return a nonzero value.
7.12.12 [Maximum, minimum, and positive difference functions]
<IP_ADDRESS> [The fdim functions]
1 Synopsis
#include <math.h>
double fdim(double x, double y);
float fdimf(float x, float y);
long double fdiml(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fdimd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fdimd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fdimd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fdim functions determine the positive difference between their arguments:
(
x − y if x > y
+0 if x ≤ y
A range error may occur.
Returns
3 The fdim functions return the positive difference value.
<IP_ADDRESS> [The fmax functions]
1 Synopsis
#include <math.h>
double fmax(double x, double y);
float fmaxf(float x, float y);
long double fmaxl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fmaxd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fmaxd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fmaxd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fmax functions determine the maximum numeric value of their arguments.[299]
Returns
Footnote 299) Quiet NaN arguments are treated as missing data: if one argument is a quiet NaN and the other numeric, then the fmax
functions choose the numeric value. See F.10.9.2.
3 The fmax functions return the maximum numeric value of their arguments.
<IP_ADDRESS> [The fmin functions]
1 Synopsis
#include <math.h>
double fmin(double x, double y);
float fminf(float x, float y);
long double fminl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fmind32(_Decimal32 x, _Decimal32 y);
_Decimal64 fmind64(_Decimal64 x, _Decimal64 y);
_Decimal128 fmind128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fmin functions determine the minimum numeric value of their arguments. [300]
Returns
Footnote 300) The fmin functions are analogous to the fmax functions in their treatment of quiet NaNs.
3 The fmin functions return the minimum numeric value of their arguments.
4 NOTE 1 The fmax and fmin functions are similar to the fmaximum_num and fminimum_num functions, though may differ in
which signed zero is returned when the arguments are differently signed zeros and in their treatment of signaling NaNs
(see F.10.9.5).
<IP_ADDRESS> [The fmaximum functions]
1 Synopsis
#include <math.h>
double fmaximum(double x, double y);
float fmaximumf(float x, float y);
long double fmaximuml(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fmaximumd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fmaximumd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fmaximumd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fmaximum functions determine the maximum value of their arguments. For these functions, +0
is considered greater than −0. These functions differ from the fmaximum_num functions only in their
treatment of NaN arguments (see F.10.9.4, F.10.9.5).
Returns
3 The fmaximum functions return the maximum value of their arguments.
<IP_ADDRESS> [The fminimum functions]
1 Synopsis
#include <math.h>
double fminimum(double x, double y);
float fminimumf(float x, float y);
long double fminimuml(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fminimumd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fminimumd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fminimumd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fminimum functions determine the minimum value of their arguments. For these functions, −0
is considered less than +0. These functions differ from the fminimum_num functions only in their
treatment of NaN arguments (see F.10.9.4, F.10.9.5).
Returns
3 The fminimum functions return the minimum value of their arguments.
<IP_ADDRESS> [The fmaximum_mag functions]
1 Synopsis
#include <math.h>
double fmaximum_mag(double x, double y);
float fmaximum_magf(float x, float y);
long double fmaximum_magl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fmaximum_magd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fmaximum_magd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fmaximum_magd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fmaximum_mag functions determine the value of the argument of maximum magnitude:
x if |x | > |y|, y if |y| > |x |, and fmaximum(x, y) otherwise. These functions differ from the
fmaximum_mag_num functions only in their treatment of NaN arguments (see F.10.9.4, F.10.9.5).
Returns
3 The fmaximum_mag functions return the value of the argument of maximum magnitude.
<IP_ADDRESS> [The fminimum_mag functions]
1 Synopsis
#include <math.h>
double fminimum_mag(double x, double y);
float fminimum_magf(float x, float y);
long double fminimum_magl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fminimum_magd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fminimum_magd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fminimum_magd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fminimum_mag functions determine the value of the argument of minimum magnitude:
x if |x | < |y|, y if |y| < |x |, and fminimum(x, y) otherwise. These functions differ from the
fminimum_mag_num functions only in their treatment of NaN arguments (see F.10.9.4, F.10.9.5).
Returns
3 The fminimum_mag functions return the value of the argument of minimum magnitude.
<IP_ADDRESS> [The fmaximum_num functions]
1 Synopsis
#include <math.h>
double fmaximum_num(double x, double y);
float fmaximum_numf(float x, float y);
long double fmaximum_numl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fmaximum_numd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fmaximum_numd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fmaximum_numd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fmaximum_num functions determine the maximum value of their numeric arguments. They
determine the number if one argument is a number and the other is a NaN. These functions differ
from the fmaximum functions only in their treatment of NaN arguments (see F.10.9.4, F.10.9.5).
Returns
3 The fmaximum_num functions return the maximum value of their numeric arguments.
<IP_ADDRESS> [The fminimum_num functions]
1 Synopsis
#include <math.h>
double fminimum_num(double x, double y);
float fminimum_numf(float x, float y);
long double fminimum_numl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fminimum_numd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fminimum_numd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fminimum_numd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fminimum_num functions determine the minimum value of their numeric arguments. They
determine the number if one argument is a number and the other is a NaN. These functions differ
from the fminimum functions only in their treatment of NaN arguments (see F.10.9.4, F.10.9.5).
Returns
3 The fminimum_num functions return the minimum value of their numeric arguments.
<IP_ADDRESS> [The fmaximum_mag_num functions]
1 Synopsis
#include <math.h>
double fmaximum_mag_num(double x, double y);
float fmaximum_mag_numf(float x, float y);
long double fmaximum_mag_numl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fmaximum_mag_numd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fmaximum_mag_numd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fmaximum_mag_numd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fmaximum_mag_num functions determine the value of a numeric argument of maximum mag-
nitude. They determine the number if one argument is a number and the other is a NaN. These
functions differ from the fmaximum_mag functions only in their treatment of NaN arguments
(see F.10.9.4, F.10.9.5).
Returns
3 The fmaximum_mag_num functions return the value of a numeric argument of maximum magnitude.
<IP_ADDRESS> [The fminimum_mag_num functions]
1 Synopsis
#include <math.h>
double fminimum_mag_num(double x, double y);
float fminimum_mag_numf(float x, float y);
long double fminimum_mag_numl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fminimum_mag_numd32(_Decimal32 x, _Decimal32 y);
_Decimal64 fminimum_mag_numd64(_Decimal64 x, _Decimal64 y);
_Decimal128 fminimum_mag_numd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The fminimum_mag_num functions determine the value of a numeric argument of minimum mag-
nitude. They determine the number if one argument is a number and the other is a NaN. These
functions differ from the fminimum_mag functions only in their treatment of NaN arguments
(see F.10.9.4, F.10.9.5).
Returns
3 The fminimum_mag_num functions return the value of a numeric argument of mimum minagnitude.
7.12.13 [Fused multiply-add]
<IP_ADDRESS> [The fma functions]
1 Synopsis
#include <math.h>
double fma(double x, double y, double z);
float fmaf(float x, float y, float z);
long double fmal(long double x, long double y, long double z);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 fmad32(_Decimal32 x, _Decimal32 y, _Decimal32 z);
_Decimal64 fmad64(_Decimal64 x, _Decimal64 y, _Decimal64 z);
_Decimal128 fmad128(_Decimal128 x, _Decimal128 y, _Decimal128 z);
#endif
Description
2 The fma functions compute (x × y) + z, rounded as one ternary operation: they compute the value
(as if) to infinite precision and round once to the result format, according to the current rounding
mode. A range error occurs for some finite arguments.
Returns
3 The fma functions return (x × y) + z, rounded as one ternary operation.
7.12.14 [Functions that round result to narrower type]
1 The functions in this subclause round their results to a type typically narrower[301] than the parameter
types.
Footnote 301) In some cases the destination type might not be narrower than the parameter types. For example, double might not be
narrower than long double.
<IP_ADDRESS> [Add and round to narrower type]
1 Synopsis
#include <math.h>
float fadd(double x, double y);
float faddl(long double x, long double y);
double daddl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 d32addd64(_Decimal64 x, _Decimal64 y);
_Decimal32 d32addd128(_Decimal128 x, _Decimal128 y);
_Decimal64 d64addd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 These functions compute the sum of x + y, rounded to the type of the function. They compute
the sum (as if) to infinite precision and round once to the result format, according to the current
rounding mode. A range error occurs for some finite arguments. A domain error may occur for
infinite arguments.
Returns
3 These functions return the sum of x + y, rounded to the type of the function.
<IP_ADDRESS> [Subtract and round to narrower type]
1 Synopsis
#include <math.h>
float fsub(double x, double y);
float fsubl(long double x, long double y);
double dsubl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 d32subd64(_Decimal64 x, _Decimal64 y);
_Decimal32 d32subd128(_Decimal128 x, _Decimal128 y);
_Decimal64 d64subd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 These functions compute the difference of x − y, rounded to the type of the function. They compute
the difference (as if) to infinite precision and round once to the result format, according to the current
rounding mode. A range error occurs for some finite arguments. A domain error may occur for
infinite arguments.
Returns
3 These functions return the difference of x − y, rounded to the type of the function.
<IP_ADDRESS> [Multiply and round to narrower type]
1 Synopsis
#include <math.h>
float fmul(double x, double y);
float fmull(long double x, long double y);
double dmull(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 d32muld64(_Decimal64 x, _Decimal64 y);
_Decimal32 d32muld128(_Decimal128 x, _Decimal128 y);
_Decimal64 d64muld128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 These functions compute the product x × y, rounded to the type of the function. They compute the
product (as if) to infinite precision and round once to the result format, according to the current
rounding mode. A range error occurs for some finite arguments. A domain error occurs for one
infinite argument and one zero argument.
Returns
3 These functions return the product of x × y, rounded to the type of the function.
<IP_ADDRESS> [Divide and round to narrower type]
1 Synopsis
#include <math.h>
float fdiv(double x, double y);
float fdivl(long double x, long double y);
double ddivl(long double x, long double y);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 d32divd64(_Decimal64 x, _Decimal64 y);
_Decimal32 d32divd128(_Decimal128 x, _Decimal128 y);
_Decimal64 d64divd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 These functions compute the quotient x ÷ y, rounded to the type of the function. They compute the
quotient (as if) to infinite precision and round once to the result format, according to the current
rounding mode. A range error occurs for some finite arguments. A domain error occurs for either
both arguments infinite or both arguments zero. A pole error occurs for a finite x and a zero y.
Returns
3 These functions return the quotient x ÷ y, rounded to the type of the function.
<IP_ADDRESS> [Fused multiply-add and round to narrower type]
1 Synopsis
#include <math.h>
float ffma(double x, double y, double z);
float ffmal(long double x, long double y, long double z);
double dfmal(long double x, long double y, long double z);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 d32fmad64(_Decimal64 x, _Decimal64 y, _Decimal64 z);
_Decimal32 d32fmad128(_Decimal128 x, _Decimal128 y, _Decimal128 z);
_Decimal64 d64fmad128(_Decimal128 x, _Decimal128 y, _Decimal128 z);
#endif
Description
2 These functions compute (x × y) + z, rounded to the type of the function. They compute (x × y) + z
(as if) to infinite precision and round once to the result format, according to the current rounding
mode. A range error occurs for some finite arguments. A domain error may occur for an infinite
argument.
Returns
3 These functions return (x × y) + z, rounded to the type of the function.
<IP_ADDRESS> [Square root rounded to narrower type]
1 Synopsis
#include <math.h>
float fsqrt(double x);
float fsqrtl(long double x);
double dsqrtl(long double x);
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 d32sqrtd64(_Decimal64 x);
_Decimal32 d32sqrtd128(_Decimal128 x);
_Decimal64 d64sqrtd128(_Decimal128 x);
#endif
Description
2 These functions compute the square root of x, rounded to the type of the function. They compute the
square root (as if) to infinite precision and round once to the result format, according to the current
rounding mode. A range error occurs for some finite positive arguments. A domain error occurs if
the argument is less than zero.
Returns
3 These functions return the nonnegative square root of x, rounded to the type of the function.
7.12.15 [Quantum and quantum exponent functions]
<IP_ADDRESS> [The quantizedN functions]
1 Synopsis
#include <math.h>
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 quantized32(_Decimal32 x, _Decimal32 y);
_Decimal64 quantized64(_Decimal64 x, _Decimal64 y);
_Decimal128 quantized128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The quantizedN functions compute, if possible, a value with the numerical value of x and the
quantum exponent of y. If the quantum exponent is being increased, the value shall be correctly
rounded; if the result does not have the same value as x, the "inexact" floating-point exception shall
be raised. If the quantum exponent is being decreased and the significand of the result has more
digits than the type would allow, the result is NaN, the "invalid" floating-point exception is raised,
and a domain error occurs. If one or both operands are NaN the result is NaN. Otherwise if only one
operand is infinite, the result is NaN, the "invalid" floating-point exception is raised, and a domain
error occurs. If both operands are infinite, the result is DEC_INFINITY with the sign of x, converted
to the type of the function. The quantizedN functions do not raise the "overflow" and "underflow"
floating-point exceptions.
Returns
3 The quantizedN functions return a value with the numerical value of x (except for any rounding)
and the quantum exponent of y.
<IP_ADDRESS> [The samequantumdN functions]
1 Synopsis
#include <math.h>
#ifdef __STDC_IEC_60559_DFP__
bool samequantumd32(_Decimal32 x, _Decimal32 y);
bool samequantumd64(_Decimal64 x, _Decimal64 y);
bool samequantumd128(_Decimal128 x, _Decimal128 y);
#endif
Description
2 The samequantumdN functions determine if the quantum exponents of x and y are the same. If both
x and y are NaN, or both infinite, they have the same quantum exponents; if exactly one operand
is infinite or exactly one operand is NaN, they do not have the same quantum exponents. The
samequantumdN functions raise no floating-point exception.
Returns
3 The samequantumdN functions return nonzero (true) when x and y have the same quantum expo-
nents, zero (false) otherwise.
<IP_ADDRESS> [The quantumdN functions]
1 Synopsis
#include <math.h>
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 quantumd32(_Decimal32 x);
_Decimal64 quantumd64(_Decimal64 x);
_Decimal128 quantumd128(_Decimal128 x);
#endif
Description
2 The quantumdN functions compute the quantum (<IP_ADDRESS>.3) of a finite argument. If x is infinite, the
result is +∞.
Returns
3 The quantumdN functions return the quantum of x.
<IP_ADDRESS> [The llquantexpdN functions]
1 Synopsis
#include <math.h>
#ifdef __STDC_IEC_60559_DFP__
long long int llquantexpd32(_Decimal32 x);
long long int llquantexpd64(_Decimal64 x);
long long int llquantexpd128(_Decimal128 x);
#endif
Description
2 The llquantexpdN functions compute the quantum exponent (<IP_ADDRESS>.3) of a finite argument. If x is
infinite or NaN, they compute LLONG_MIN, the "invalid" floating-point exception is raised, and a
domain error occurs.
Returns
3 The llquantexpdN functions return the quantum exponent of x.
7.12.16 [Decimal re-encoding functions]
1 IEC 60559 specifies two different schemes to encode significands in the object representation of a
decimal floating-point object: one based on decimal encoding (which packs three decimal digits
into 10 bits), the other based on binary encoding (as a binary integer). An implementation may use
either of these encoding schemes for its decimal floating types. The re-encoding functions in this
subclause provide conversions between external decimal data with a given encoding scheme and
the implementation’s corresponding decimal floating type.
<IP_ADDRESS> [The encodedecdN functions]
1 Synopsis
#include <math.h>
#ifdef __STDC_IEC_60559_DFP__
void encodedecd32(unsigned char encptr[restrict static 4],
const _Decimal32*restrict xptr);
void encodedecd64(unsigned char encptr[restrict static 8],
const _Decimal64*restrict xptr);
void encodedecd128(unsigned char encptr[restrict static 16],
const _Decimal128*restrict xptr);
#endif
Description
2 The encodedecdN functions convert *xptr into an IEC 60559 decimalN encoding in the encoding
scheme based on decimal encoding of the significand and store the resulting encoding as an N/8
element array, with 8 bits per array element, in the object pointed to by encptr. The order of bytes
in the array is implementation-defined. These functions preserve the value of *xptr and raise no
floating-point exceptions. If *xptr is non-canonical, these functions may or may not produce a
canonical encoding.
Returns
3 The encodedecdN functions return no value.
<IP_ADDRESS> [The decodedecdN functions]
1 Synopsis
#include <math.h>
#ifdef __STDC_IEC_60559_DFP__
void decodedecd32(_Decimal32 * restrict xptr,
const unsigned char encptr[restrict static 4]);
void decodedecd64(_Decimal64 * restrict xptr,
const unsigned char encptr[restrict static 8]);
void decodedecd128(_Decimal128 * restrict xptr,
const unsigned char encptr[restrict static 16]);
#endif
Description
15
2 The decodedecdN functions interpret the N/8 element array pointed to by encptr as an IEC 60559
decimalN encoding, with 8 bits per array element, in the encoding scheme based on decimal
encoding of the significand. The order of bytes in the array is implementation-defined. These
functions convert the given encoding into a value of the decimal floating type, and store the result in
the object pointed to by xptr. These functions preserve the encoded value and raise no floating-point
exceptions. If the encoding is non-canonical, these functions may or may not produce a canonical
representation.
Returns
3 The decodedecdN functions return no value.
<IP_ADDRESS> [The encodebindN functions]
1 Synopsis
#include <math.h>
#ifdef __STDC_IEC_60559_DFP__
void encodebind32(unsigned char encptr[restrict static 4],
const _Decimal32 * restrict xptr);
void encodebind64(unsigned char encptr[restrict static 8],
const _Decimal64 * restrict xptr);
void encodebind128(unsigned char encptr[restrict static 16],
const _Decimal128 * restrict xptr);
#endif
Description
2 The encodebindN functions convert *xptr into an IEC 60559 decimalN encoding in the encoding
scheme based on binary encoding of the significand and store the resulting encoding as an N/8
element array, with 8 bits per array element, in the object pointed to by encptr. The order of bytes
in the array is implementation-defined. These functions preserve the value of *xptr and raise no
floating-point exceptions. If *xptr is non-canonical, these functions may or may not produce a
canonical encoding.
Returns
3 The encodebindN functions return no value.
<IP_ADDRESS> [The decodebindN functions]
1 Synopsis
#include <math.h>
#ifdef __STDC_IEC_60559_DFP__
void decodebind32(_Decimal32 * restrict xptr,
const unsigned char encptr[restrict static 4]);
void decodebind64(_Decimal64 * restrict xptr,
const unsigned char encptr[restrict static 8]);
void decodebind128(_Decimal128 * restrict xptr,
const unsigned char encptr[restrict static 16]);
#endif
Description
2 The decodebindN functions interpret the N/8 element array pointed to by encptr as an IEC 60559
decimalN encoding, with 8 bits per array element, in the encoding scheme based on binary encoding
of the significand. The order of bytes in the array is implementation-defined. These functions convert
the given encoding into a value of decimal floating type, and store the result in the object pointed to
by xptr. These functions preserve the encoded value and raise no floating-point exceptions. If the
encoding is non-canonical, these functions may or may not produce a canonical representation.
Returns
3 The decodebindN functions return no value.
7.12.17 [Comparison macros]
1 The relational and equality operators support the usual mathematical relationships between numeric
values. For any ordered pair of numeric values exactly one of the relationships — less, greater, and
equal — is true. Relational operators may raise the "invalid" floating-point exception when argument
values are NaNs. For a NaN and a numeric value, or for two NaNs, just the unordered relationship
is true.[302] Subclauses <IP_ADDRESS> through <IP_ADDRESS> provide macros that are quiet versions of the
relational operators: the macros do not raise the "invalid" floating-point exception as an effect
of quiet NaN arguments. The comparison macros facilitate writing efficient code that accounts
for quiet NaNs without suffering the "invalid" floating-point exception. In the synopses in this
subclause, real-floating indicates that the argument shall be an expression of real floating type[303]
(both arguments need not have the same type).[304] If either argument has decimal floating type, the
other argument shall have decimal floating type as well.
Footnote 302) IEC 60559 requires that the built-in relational operators raise the "invalid" floating-point exception if the operands
compare unordered, as an error indicator for programs written without consideration of NaNs; the result in these cases is
false.
Footnote 303) If any argument is of integer type, or any other type that is not a real floating type, the behavior is undefined.
Footnote 304) Whether an argument represented in a format wider than its semantic type is converted to the semantic type is unspecified.
<IP_ADDRESS> [The isgreater macro]
1 Synopsis
#include <math.h>
int isgreater(real-floating x, real-floating y);
Description
2 The isgreater macro determines whether its first argument is greater than its second argu-
ment. The value of isgreater(x,y) is always equal to (x)> (y) ; however, unlike (x)> (y) ,
isgreater(x,y) does not raise the "invalid" floating-point exception when x and y are unordered
and neither is a signaling NaN.
Returns
3 The isgreater macro returns the value of (x)> (y) .
<IP_ADDRESS> [The isgreaterequal macro]
1 Synopsis
#include <math.h>
int isgreaterequal(real-floating x, real-floating y);
Description
2 The isgreaterequal macro determines whether its first argument is greater than or equal to its
second argument. The value of isgreaterequal(x,y) is always equal to (x)>= (y) ; however,
unlike (x)>= (y) , isgreaterequal(x,y) does not raise the "invalid" floating-point exception
when x and y are unordered and neither is a signaling NaN.
Returns
3 The isgreaterequal macro returns the value of (x)>= (y) .
<IP_ADDRESS> [The isless macro]
1 Synopsis
#include <math.h>
int isless(real-floating x, real-floating y);
Description
2 The isless macro determines whether its first argument is less than its second argument. The value
of isless(x,y) is always equal to (x)< (y) ; however, unlike (x)< (y) , isless(x,y) does not
raise the "invalid" floating-point exception when x and y are unordered and neither is a signaling
NaN.
Returns
3 The isless macro returns the value of (x) < (y).
<IP_ADDRESS> [The islessequal macro]
1 Synopsis
#include <math.h>
int islessequal(real-floating x, real-floating y);
Description
2 The islessequal macro determines whether its first argument is less than or equal to its sec-
ond argument. The value of islessequal(x,y) is always equal to (x)<= (y) ; however, unlike
(x)<= (y) , islessequal(x,y) does not raise the "invalid" floating-point exception when x and y
are unordered and neither is a signaling NaN.
Returns
3 The islessequal macro returns the value of (x)<= (y) .
<IP_ADDRESS> [The islessgreater macro]
1 Synopsis
#include <math.h>
int islessgreater(real-floating x, real-floating y);
Description
2 The islessgreater macro determines whether its first argument is less than or greater than its
second argument. The islessgreater(x,y) macro is similar to (x)< (y)|| (x)> (y) ; however,
islessgreater(x,y) does not raise the "invalid" floating-point exception when x and y are un-
ordered and neither is a signaling NaN (nor does it evaluate x and y twice).
Returns
3 The islessgreater macro returns the value of (x)< (y)|| (x)> (y) .
<IP_ADDRESS> [The isunordered macro]
1 Synopsis
#include <math.h>
int isunordered(real-floating x, real-floating y);
Description
2 The isunordered macro determines whether its arguments are unordered. It raises no floating-point
exceptions if neither argument is a signaling NaN.
Returns
3 The isunordered macro returns 1 if its arguments are unordered and 0 otherwise.
<IP_ADDRESS> [The iseqsig macro]
1 Synopsis
#include <math.h>
int iseqsig(real-floating x, real-floating y);
Description
2 The iseqsig macro determines whether its arguments are equal. If an argument is a NaN, a domain
error occurs for the macro, as if a domain error occurred for a function (7.12.1).
Returns
3 The iseqsig macro returns 1 if its arguments are equal and 0 otherwise.
7.13 [Non-local jumps <setjmp.h>]
1 The header <setjmp.h> defines the macro setjmp, and declares one function and one type, for
bypassing the normal function call and return discipline.[305]
Footnote 305) These functions are useful for dealing with unusual conditions encountered in a low-level function of a program.
2 The type declared is
jmp_buf
which is an array type suitable for holding the information needed to restore a calling environment.
The environment of a call to the setjmp macro consists of information sufficient for a call to the
longjmp function to return execution to the correct block and invocation of that block, were it called
recursively. It does not include the state of the floating-point status flags, of open files, or of any
other component of the abstract machine.
3 It is unspecified whether setjmp is a macro or an identifier declared with external linkage. If a
macro definition is suppressed in order to access an actual function, or a program defines an external
identifier with the name setjmp, the behavior is undefined.
7.13.1 [Save calling environment]
<IP_ADDRESS> [The setjmp macro]
1 Synopsis
#include <setjmp.h>
int setjmp(jmp_buf env);
Description
2 The setjmp macro saves its calling environment in its jmp_buf argument for later use by the
longjmp function.
Returns
3 If the return is from a direct invocation, the setjmp macro returns the value zero. If the return is
from a call to the longjmp function, the setjmp macro returns a nonzero value.
Environmental limits
4 An invocation of the setjmp macro shall appear only in one of the following contexts:
— the entire controlling expression of a selection or iteration statement;
— one operand of a relational or equality operator with the other operand an integer constant
expression, with the resulting expression being the entire controlling expression of a selection
or iteration statement;
— the operand of a unary ! operator with the resulting expression being the entire controlling
expression of a selection or iteration statement; or
— the entire expression of an expression statement (possibly cast to void).
5 If the invocation appears in any other context, the behavior is undefined.
7.13.2 [Restore calling environment]
<IP_ADDRESS> [The longjmp function]
1 Synopsis
#include <setjmp.h>
[[noreturn]] void longjmp(jmp_buf env, int val);
Description
2 The longjmp function restores the environment saved by the most recent invocation of the setjmp
macro in the same invocation of the program with the corresponding jmp_buf argument. If there
has been no such invocation, or if the invocation was from another thread of execution, or if the
function containing the invocation of the setjmp macro has terminated execution[306] in the interim,
or if the invocation of the setjmp macro was within the scope of an identifier with variably modified
type and execution has left that scope in the interim, the behavior is undefined.
Footnote 306) For example, by executing a return statement or because another longjmp call has caused a transfer to a setjmp
invocation in a function earlier in the set of nested calls.
3 All accessible objects have values, and all other components of the abstract machine[307] have state,
as of the time the longjmp function was called, except that the representation of objects of automatic
storage duration that are local to the function containing the invocation of the corresponding
setjmp macro that do not have volatile-qualified type and have been changed between the setjmp
invocation and longjmp call is indeterminate.
Returns
Footnote 307) This includes, but is not limited to, the floating-point status flags and the state of open files.
4 After longjmp is completed, thread execution continues as if the corresponding invocation of the
setjmp macro had just returned the value specified by val. The longjmp function cannot cause the
setjmp macro to return the value 0; if val is 0, the setjmp macro returns the value 1.
5 EXAMPLE The longjmp function that returns control back to the point of the setjmp invocation might cause memory
associated with a variable length array object to be squandered.
#include <setjmp.h>
jmp_buf buf;
void g(int n);
void h(int n);
int n = 6;
void f(void)
{
int x[n]; // valid: f is not terminated
setjmp(buf);
g(n);
}
void g(int n)
{
int a[n]; // a may remain allocated
h(n);
}
void h(int n)
{
int b[n]; // b may remain allocated
longjmp(buf, 2); // might cause memory loss
}
7.14 [Signal handling <signal.h>]
1 The header <signal.h> declares a type and two functions and defines several macros, for handling
various signals (conditions that may be reported during program execution).
2 The type defined is
sig_atomic_t
which is the (possibly volatile-qualified) integer type of an object that can be accessed as an atomic
entity, even in the presence of asynchronous interrupts.
3 The macros defined are
SIG_DFL
SIG_ERR
SIG_IGN
which expand to constant expressions with distinct values that have type compatible with the second
argument to, and the return value of, the signal function, and whose values compare unequal to
the address of any declarable function; and the following, which expand to positive integer constant
expressions with type int and distinct values that are the signal numbers, each corresponding to
the specified condition:
SIGABRT abnormal termination, such as is initiated by the abort function
SIGFPE an erroneous arithmetic operation, such as zero divide or an operation resulting in
overflow
SIGILL detection of an invalid function image, such as an invalid instruction
SIGINT receipt of an interactive attention signal
SIGSEGV an invalid access to storage
SIGTERM a termination request sent to the program
4 An implementation need not generate any of these signals, except as a result of explicit calls to the
raise function. Additional signals and pointers to undeclarable functions, with macro definitions
beginning, respectively, with the letters SIG and an uppercase letter or with SIG_ and an uppercase
letter,[308] may also be specified by the implementation. The complete set of signals, their semantics,
and their default handling is implementation-defined; all signal numbers shall be positive.
Footnote 308) See "future library directions" (7.33.9). The names of the signal numbers reflect the following terms (respectively): abort,
floating-point exception, illegal instruction, interrupt, segmentation violation, and termination.
7.14.1 [Specify signal handling]
<IP_ADDRESS> [The signal function]
1 Synopsis
#include <signal.h>
void (*signal(int sig, void (*func)(int)))(int);
Description
2 The signal function chooses one of three ways in which receipt of the signal number sig is to
be subsequently handled. If the value of func is SIG_DFL, default handling for that signal will
occur. If the value of func is SIG_IGN, the signal will be ignored. Otherwise, func shall point to a
function to be called when that signal occurs. An invocation of such a function because of a signal, or
(recursively) of any further functions called by that invocation (other than functions in the standard
library),[309] is called a signal handler.
Footnote 309) This includes functions called indirectly via standard library functions (e.g., a SIGABRT handler called via the abort
function).
3 When a signal occurs and func points to a function, it is implementation-defined whether the equiva-
lent of signal(sig, SIG_DFL); is executed or the implementation prevents some implementation-
defined set of signals (at least including sig) from occurring until the current signal handling has
completed; in the case of SIGILL, the implementation may alternatively define that no action is taken.
Then the equivalent of (*func)(sig); is executed. If and when the function returns, if the value
of sig is SIGFPE, SIGILL, SIGSEGV, or any other implementation-defined value corresponding to a
computational exception, the behavior is undefined; otherwise the program will resume execution
at the point it was interrupted.
4 If the signal occurs as the result of calling the abort or raise function, the signal handler shall not
call the raise function.
5 If the signal occurs other than as the result of calling the abort or raise function, the behavior is
undefined if the signal handler refers to any object with static or thread storage duration that is
not a lock-free atomic object other than by assigning a value to an object declared as volatile
sig_atomic_t, or the signal handler calls any function in the standard library other than
— the abort function,
— the _Exit function,
— the quick_exit function,
— the functions in <stdatomic.h> (except where explicitly stated otherwise) when the atomic
arguments are lock-free,
— the atomic_is_lock_free function with any atomic argument, or
— the signal function with the first argument equal to the signal number corresponding to the
signal that caused the invocation of the handler. Furthermore, if such a call to the signal
function results in a SIG_ERR return, the object designated by errno has an indeterminate
representation[310] .
Footnote 310) If any signal is generated by an asynchronous signal handler, the behavior is undefined.
6 At program startup, the equivalent of
signal(sig, SIG_IGN);
may be executed for some signals selected in an implementation-defined manner; the equivalent of
signal(sig, SIG_DFL);
is executed for all other signals defined by the implementation.
7 Use of this function in a multi-threaded program results in undefined behavior. The implementation
shall behave as if no library function calls the signal function.
Returns
8 If the request can be honored, the signal function returns the value of func for the most recent
successful call to signal for the specified signal sig. Otherwise, a value of SIG_ERR is returned and
a positive value is stored in errno.
Forward references: the abort function (<IP_ADDRESS>), the exit function (<IP_ADDRESS>), the _Exit function
(<IP_ADDRESS>), the quick_exit function (<IP_ADDRESS>).
7.14.2 [Send signal]
<IP_ADDRESS> [The raise function]
1 Synopsis
#include <signal.h>
int raise(int sig);
Description
2 The raise function carries out the actions described in <IP_ADDRESS> for the signal sig. If a signal handler
is called, the raise function shall not return until after the signal handler does.
Returns
3 The raise function returns zero if successful, nonzero if unsuccessful.
7.15 [Alignment <stdalign.h>]
1 The header <stdalign.h> provides no content.
7.16 [Variable arguments <stdarg.h>]
1 The header <stdarg.h> declares a type and defines four macros, for advancing through a list of
arguments whose number and types are not known to the called function when it is translated.
2 A function may be called with a variable number of arguments of varying types if its parameter
type list ends with an ellipsis.
3 The type declared is
va_list
which is a complete object type suitable for holding information needed by the macros va_start,
va_arg, va_end, and va_copy . If access to the varying arguments is desired, the called function
shall declare an object (generally referred to as ap in this subclause) having type va_list. The object
ap may be passed as an argument to another function; if that function invokes the va_arg macro
with parameter ap, the representation of ap in the calling function is indeterminate and shall be
passed to the va_end macro prior to any further reference to ap[311] .
Footnote 311) It is permitted to create a pointer to a va_list and pass that pointer to another function, in which case the original
function can make further use of the original list after the other function returns.
7.16.1 [Variable argument list access macros]
1 The va_start and va_arg macros described in this subclause shall be implemented as macros,
not functions. It is unspecified whether va_copy and va_end are macros or identifiers declared
with external linkage. If a macro definition is suppressed in order to access an actual function,
or a program defines an external identifier with the same name, the behavior is undefined. Each
invocation of the va_start and va_copy macros shall be matched by a corresponding invocation of
the va_end macro in the same function.
<IP_ADDRESS> [The va_arg macro]
1 Synopsis
#include <stdarg.h>
type va_arg(va_list ap, type);
Description
2 The va_arg macro expands to an expression that has the specified type and the value of the next
argument in the call. The parameter ap shall have been initialized by the va_start or va_copy
macro (without an intervening invocation of the va_end macro for the same ap). Each invocation
of the va_arg macro modifies ap so that the values of successive arguments are returned in turn.
The behavior is undefined if there is no actual next argument. The parameter type shall be a type
name specified such that the type of a pointer to an object that has the specified type can be obtained
simply by postfixing a * to type. If type is not compatible with the type of the actual next argument
(as promoted according to the default argument promotions), the behavior is undefined, except for
the following cases:
— both types are pointers to qualified or unqualified versions of compatible types;
— one type is a signed integer type, the other type is the corresponding unsigned integer type,
and the value is representable in both types;
— one type is pointer to qualified or unqualified void and the other is a pointer to a qualified or
unqualified character type;
— or, the type of the next argument is nullptr_t and type is a pointer type that has the same
representation and alignment requirements as a pointer to a character type[312] .
Returns
Footnote 312) Such types are in particular pointers to qualified or unqualified versions of void .
3 The first invocation of the va_arg macro after that of the va_start macro returns the value of
the first argument without an explicitly parameter, which matches the position of the ... in the
parameter list. Successive invocations return the values of the remaining arguments in succession.
<IP_ADDRESS> [The va_copy macro]
1 Synopsis
#include <stdarg.h>
void va_copy(va_list dest, va_list src);
Description
2 The va_copy macro initializes dest as a copy of src, as if the va_start macro had been applied
to dest followed by the same sequence of uses of the va_arg macro as had previously been used
to reach the present state of src. Neither the va_copy nor va_start macro shall be invoked to
reinitialize dest without an intervening invocation of the va_end macro for the same dest.
Returns
3 The va_copy macro returns no value.
<IP_ADDRESS> [The va_end macro]
1 Synopsis
#include <stdarg.h>
void va_end(va_list ap);
Description
2 The va_end macro facilitates a normal return from the function whose variable argument list was
referred to by the expansion of the va_start macro, or the function containing the expansion of
the va_copy macro, that initialized the va_list ap. The va_end macro may modify ap so that it
is no longer usable (without being reinitialized by the va_start or va_copy macro). If there is no
corresponding invocation of the va_start or va_copy macro, or if the va_end macro is not invoked
before the return, the behavior is undefined.
Returns
3 The va_end macro returns no value.
<IP_ADDRESS> [The va_start macro]
1 Synopsis
#include <stdarg.h>
void va_start(va_list ap, ...);
Description
2 The va_start macro shall be invoked before any access to the unnamed arguments.
3 The va_start macro initializes ap for subsequent use by the va_arg and va_end macros. Neither the
va_start nor va_copy macro shall be invoked to reinitialize ap without an intervening invocation
of the va_end macro for the same ap.
4 Only the first argument passed to va_start is evaluated. Any additional arguments are not used by
the macro and will not be expanded or evaluated for any reason.
5 NOTE The macro allows additional arguments to be passed for va_start for compatibility with older versions of the library
only.
Returns
6 The va_start macro returns no value.
7 EXAMPLE 1 The function f1 gathers into an array a list of arguments that are pointers to strings (but not more than MAXARGS
arguments), then passes the array as a single argument to function f2. The number of pointers is specified by the first
argument to f1.
#include <stdarg.h>
#define MAXARGS 31
void f1(int n_ptrs, ...)
{
va_list ap;
char *array[MAXARGS];
int ptr_no = 0;
if (n_ptrs > MAXARGS)
n_ptrs = MAXARGS;
va_start(ap);
while (ptr_no < n_ptrs)
array[ptr_no++] = va_arg(ap, char *);
va_end(ap);
f2(n_ptrs, array);
}
Each call to f1 is required to have visible the definition of the function or a declaration such as
void f1(int, ...);
8 EXAMPLE 2 The function f3 is similar, but saves the status of the variable argument list after the indicated number of
arguments; after f2 has been called once with the whole list, the trailing part of the list is gathered again and passed to
function f4.
#include <stdarg.h>
#define MAXARGS 31
void f3(int n_ptrs, int f4_after, ...)
{
va_list ap, ap_save;
char *array[MAXARGS];
int ptr_no = 0;
if (n_ptrs > MAXARGS)
n_ptrs = MAXARGS;
_
va start(ap);
while (ptr_no < n_ptrs) {
array[ptr_no++] = va_arg(ap, char *);
if (ptr_no == f4_after)
va_copy(ap_save, ap);
}
va_end(ap);
f2(n_ptrs, array);
// Now process the saved copy.
n_ptrs -= f4_after;
ptr_no = 0;
while (ptr_no < n_ptrs)
array[ptr_no++] = va_arg(ap_save, char *);
va end(ap_save);
_
f4(n_ptrs, array);
}
9 EXAMPLE 3 The function f5 is similar to f1, but instead of passing an explicit number of strings as the first argument, the
argument list is terminated with a null pointer.
#include <stdarg.h>
#define MAXARGS 31
void f5(...)
{
va_list ap;
char *array[MAXARGS];
int ptr_no = 0;
va_start(ap);
while (ptr_no < MAXARGS)
{
char *ptr = va_arg(ap, char *);
if (!ptr)
break;
array[ptr_no++] = ptr;
}
va_end(ap);
f6(ptr_no, array);
}
Each call to f5 is required to have visible the definition of the function or a declaration such as
void f5(...);
and implicitly requires the last argument to be a null pointer.
7.17 [Atomics <stdatomic.h>]
7.17.1 [Introduction]
1 The header <stdatomic.h> defines several macros and declares several types and functions for
performing atomic operations on data shared between threads.[313]
Footnote 313) See "future library directions" (7.33.10).
2 Implementations that define the macro __STDC_NO_ATOMICS__ need not provide this header nor
support any of its facilities.
3 The macros defined are the atomic lock-free macros
ATOMIC_BOOL_LOCK_FREE
ATOMIC_CHAR_LOCK_FREE
ATOMIC_CHAR8_T_LOCK_FREE
ATOMIC_CHAR16_T_LOCK_FREE
ATOMIC_CHAR32_T_LOCK_FREE
ATOMIC_WCHAR_T_LOCK_FREE
ATOMIC_SHORT_LOCK_FREE
ATOMIC_INT_LOCK_FREE
ATOMIC_LONG_LOCK_FREE
ATOMIC_LLONG_LOCK_FREE
ATOMIC_POINTER_LOCK_FREE
which expand to constant expressions suitable for use in #if preprocessing directives and which
indicate the lock-free property of the corresponding atomic types (both signed and unsigned); and
ATOMIC_FLAG_INIT
which expands to an initializer for an object of type atomic_flag.
4 The types include
memory_order
which is an enumerated type whose enumerators identify memory ordering constraints;
atomic_flag
which is a structure type representing a lock-free, primitive atomic flag; and several atomic analogs
of integer types.
5 In the following synopses:
— An A refers to an atomic type.
— A C refers to its corresponding non-atomic type.
— An M refers to the type of the other argument for arithmetic operations. For atomic integer
types, M is C. For atomic pointer types, M is ptrdiff_t.
— The functions not ending in _explicit have the same semantics as the corresponding
_explicit function with memory_order_seq_cst for the memory_order argument.
6 It is unspecified whether any generic function declared in <stdatomic.h> is a macro or an identifier
declared with external linkage. If a macro definition is suppressed in order to access an actual
function, or a program defines an external identifier with the name of a generic function, the
behavior is undefined.
7 NOTE Many operations are volatile-qualified. The "volatile as device register" semantics have not changed in the standard.
This qualification means that volatility is preserved when applying these operations to volatile objects.
7.17.2 [Initialization]
1 An atomic object with automatic storage duration that is not initialized or such an object with
allocated storage duration initially has an indeterminate representation; equally, a non-atomic store
to any byte of the representation (either directly or, for example, by calls to memcpy or memset) makes
any atomic object have an indeterminate representation. Explicit or default initialization for atomic
objects with static or thread storage duration that do not have the type atomic_flag is guaranteed
to produce a valid state.[314] .
Footnote 314) See "future library directions" (7.33.10).
2 Concurrent access to an atomic object before it is set to a valid state, even via an atomic operation,
constitutes a data race. If a signal occurs other than as the result of calling the abort or raise
functions, the behavior is undefined if the signal handler reads or modifies an atomic object that has
an indeterminate representation.
3 EXAMPLE The following definition ensure valid states for guide and head regardless if these are found in file scope or
block scope. Thus any atomic operation that is performed on them after their initialization has been met is well defined.
_Atomic int guide = 42;
static _Atomic(void*) head;
<IP_ADDRESS> [The atomic_init generic function]
1 Synopsis
#include <stdatomic.h>
void atomic_init(volatile A *obj, C value);
Description
2 The atomic_init generic function initializes the atomic object pointed to by obj to the value value,
while also initializing any additional state that the implementation might need to carry for the
atomic object. If the object has no declared type, after the call the effective type is the atomic type A.
3 Although this function initializes an atomic object, it does not avoid data races; concurrent access to
the variable being initialized, even via an atomic operation, constitutes a data race.
4 If a signal occurs other than as the result of calling the abort or raise functions, the behavior is
undefined if the signal handler calls the atomic_init generic function.
Returns
5 The atomic_init generic function returns no value.
6 EXAMPLE
atomic_int guide;
atomic_init(&guide, 42);
7.17.3 [Order and consistency]
1 The enumerated type memory_order specifies the detailed regular (non-atomic) memory synchro-
nization operations as defined in <IP_ADDRESS> and may provide for operation ordering. Its enumeration
constants are as follows:[315]
memory_order_relaxed
memory_order_consume
memory_order_acquire
memory_order_release
memory_order_acq_rel
memory_order_seq_cst
Footnote 315) See "future library directions" (7.33.10).
2 For memory_order_relaxed, no operation orders memory.
3 For memory_order_release, memory_order_acq_rel, and memory_order_seq_cst, a store opera-
tion performs a release operation on the affected memory location.
4 For memory_order_acquire, memory_order_acq_rel, and memory_order_seq_cst, a load opera-
tion performs an acquire operation on the affected memory location.
5 For memory_order_consume, a load operation performs a consume operation on the affected mem-
ory location.
6 There shall be a single total order S on all memory_order_seq_cst operations, consistent with the
"happens before" order and modification orders for all affected locations, such that each
memory_order_seq_cst operation B that loads a value from an atomic object M observes one of
the following values:
— the result of the last modification A of M that precedes B in S, if it exists, or
— if A exists, the result of some modification of M that is not memory_order_seq_cst and that
does not happen before A, or
— if A does not exist, the result of some modification of M that is not memory_order_seq_cst.
7 NOTE 1 Although it is not explicitly required that S include lock operations, it can always be extended to an order that does
include lock and unlock operations, since the ordering between those is already included in the "happens before" ordering.
8 NOTE 2 Atomic operations specifying memory_order_relaxed are relaxed only with respect to memory ordering. Imple-
mentations still guarantee that any given atomic access to a particular atomic object is indivisible with respect to all other
atomic accesses to that object.
9 For an atomic operation B that reads the value of an atomic object M , if there is a
memory_order_seq_cst fence X sequenced before B, then B observes either the last
memory_order_seq_cst modification of M preceding X in the total order S or a later mod-
ification of M in its modification order.
10 For atomic operations A and B on an atomic object M , where A modifies M and B takes its value, if
there is a memory_order_seq_cst fence X such that A is sequenced before X and B follows X in S,
then B observes either the effects of A or a later modification of M in its modification order.
11 For atomic modifications A and B of an atomic object M , B occurs later than A in the modification
order of M if:
— there is a memory_order_seq_cst fence X such that A is sequenced before X, and X precedes
B in S, or
— there is a memory_order_seq_cst fence Y such that Y is sequenced before B, and A precedes
Y in S, or
— there are memory_order_seq_cst fences X and Y such that A is sequenced before X, Y is
sequenced before B, and X precedes Y in S.
12 Atomic read-modify-write operations shall always read the last value (in the modification order)
stored before the write associated with the read-modify-write operation.
13 An atomic store shall only store a value that has been computed from constants and program input
values by a finite sequence of program evaluations, such that each evaluation observes the values of
variables as computed by the last prior assignment in the sequence. The ordering of evaluations in
this sequence shall be such that
— If an evaluation B observes a value computed by A in a different thread, then B does not
happen before A.
— If an evaluation A is included in the sequence, then all evaluations that assign to the same
variable and happen before A are also included.
14 NOTE 3 The second requirement disallows "out-of-thin-air", or "speculative" stores of atomics when relaxed atomics are
used. Since unordered operations are involved, evaluations can appear in this sequence out of thread order. For example,
with x and y initially zero,
// Thread 1:
r1 = atomic_load_explicit(&y, memory_order_relaxed);
atomic_store_explicit(&x, r1, memory_order_relaxed);
// Thread 2:
r2 = atomic_load_explicit(&x, memory_order_relaxed);
atomic_store_explicit(&y, 42, memory_order_relaxed);
is allowed to produce r1 == 42 && r2 == 42. The sequence of evaluations justifying this consists of:
atomic_store_explicit(&y, 42, memory_order_relaxed);
r1 = atomic_load_explicit(&y, memory_order_relaxed);
atomic_store_explicit(&x, r1, memory_order_relaxed);
r2 = atomic_load_explicit(&x, memory_order_relaxed);
On the other hand,
// Thread 1:
r1 = atomic_load_explicit(&y, memory_order_relaxed);
atomic_store_explicit(&x, r1, memory_order_relaxed);
// Thread 2:
r2 = atomic_load_explicit(&x, memory_order_relaxed);
atomic_store_explicit(&y, r2, memory_order_relaxed);
is not allowed to produce r1 == 42 && r2 == 42, since there is no sequence of evaluations that results in the computation
of 42. In the absence of "relaxed" operations and read-modify-write operations with weaker than memory_order_acq_rel
ordering, the second requirement has no impact.
Recommended practice
15 The requirements do not forbid r1 == 42 && r2 == 42 in the following example, with x and y
initially zero:
// Thread 1:
r1 = atomic_load_explicit(&x, memory_order_relaxed);
if (r1 == 42)
atomic_store_explicit(&y, r1, memory_order_relaxed);
// Thread 2:
r2 = atomic_load_explicit(&y, memory_order_relaxed);
if (r2 == 42)
atomic_store_explicit(&x, 42, memory_order_relaxed);
However, this is not useful behavior, and implementations should not allow it.
16 Implementations should make atomic stores visible to atomic loads within a reasonable amount of
time.
<IP_ADDRESS> [The kill_dependency macro]
1 Synopsis
#include <stdatomic.h>
type kill_dependency(type y);
Description
2 The kill_dependency macro terminates a dependency chain; the argument does not carry a depen-
dency to the return value.
Returns
3 The kill_dependency macro returns the value of y.
7.17.4 [Fences]
1 This subclause introduces synchronization primitives called fences. Fences can have acquire seman-
tics, release semantics, or both. A fence with acquire semantics is called an acquire fence; a fence with
release semantics is called a release fence.
2 A release fence A synchronizes with an acquire fence B if there exist atomic operations X and Y ,
both operating on some atomic object M , such that A is sequenced before X, X modifies M , Y is
sequenced before B, and Y reads the value written by X or a value written by any side effect in the
hypothetical release sequence X would head if it were a release operation.
3 A release fence A synchronizes with an atomic operation B that performs an acquire operation on an
atomic object M if there exists an atomic operation X such that A is sequenced before X, X modifies
M , and B reads the value written by X or a value written by any side effect in the hypothetical
release sequence X would head if it were a release operation.
4 An atomic operation A that is a release operation on an atomic object M synchronizes with an
acquire fence B if there exists some atomic operation X on M such that X is sequenced before B
and reads the value written by A or a value written by any side effect in the release sequence headed
by A.
<IP_ADDRESS> [The atomic_thread_fence function]
1 Synopsis
#include <stdatomic.h>
void atomic_thread_fence(memory_order order);
Description
2 Depending on the value of order, this operation:
— has no effects, if order == memory_order_relaxed;
— is an acquire fence, if order == memory_order_acquire or order == memory_order_consume;
— is a release fence, if order == memory_order_release;
— is both an acquire fence and a release fence, if order == memory_order_acq_rel;
— is a sequentially consistent acquire and release fence, if order == memory_order_seq_cst.
Returns
3 The atomic_thread_fence function returns no value.
<IP_ADDRESS> [The atomic_signal_fence function]
1 Synopsis
#include <stdatomic.h>
void atomic_signal_fence(memory_order order);
Description
2 Equivalent to atomic_thread_fence(order), except that the resulting ordering constraints are
established only between a thread and a signal handler executed in the same thread.
3 NOTE 1 The atomic_signal_fence function can be used to specify the order in which actions performed by the thread
become visible to the signal handler.
4 NOTE 2 Compiler optimizations and reorderings of loads and stores are inhibited in the same way as with
atomic_thread_fence, but the hardware fence instructions that atomic_thread_fence would have inserted are not
emitted.
Returns
5 The atomic_signal_fence function returns no value.
7.17.5 [Lock-free property]
1 The atomic lock-free macros indicate the lock-free property of integer and address atomic types. A
value of 0 indicates that the type is never lock-free; a value of 1 indicates that the type is sometimes
lock-free; a value of 2 indicates that the type is always lock-free.
Recommended practice
2 Operations that are lock-free should also be address-free. That is, atomic operations on the same
memory location via two different addresses will communicate atomically. The implementation
should not depend on any per-process state. This restriction enables communication via memory
mapped into a process more than once and memory shared between two processes.
<IP_ADDRESS> [The atomic_is_lock_free generic function]
1 Synopsis
#include <stdatomic.h>
bool atomic_is_lock_free(const volatile A *obj);
Description
2 The atomic_is_lock_free generic function indicates whether or not atomic operations on objects
of the type pointed to by obj are lock-free.
Returns
3 The atomic_is_lock_free generic function returns nonzero (true) if and only if atomic operations
on objects of the type pointed to by the argument are lock-free. In any given program execution, the
result of the lock-free query shall be consistent for all pointers of the same type.[316]
Footnote 316) obj can be a null pointer.
7.17.6 [Atomic integer types]
1 For each line in the following table,[317] the atomic type name is declared as a type that has the same
representation and alignment requirements as the corresponding direct type.[318]
Atomic type name Direct type
atomic_bool _Atomic bool
atomic_char _Atomic char
atomic_schar _Atomic signed char
atomic_uchar _Atomic unsigned char
atomic_short _Atomic short
atomic_ushort _Atomic unsigned short
atomic_int _Atomic int
atomic_uint _Atomic unsigned int
atomic_long _Atomic long
atomic_ulong _Atomic unsigned long
atomic_llong _Atomic long long
atomic_ullong _Atomic unsigned long long
atomic_char8_t _Atomic char8_t
atomic_char16_t _Atomic char16_t
atomic_char32_t _Atomic char32_t
atomic_wchar_t _Atomic wchar_t
atomic_int_least8_t _Atomic int_least8_t
atomic_uint_least8_t _Atomic uint_least8_t
atomic_int_least16_t _Atomic int_least16_t
atomic_uint_least16_t _Atomic uint_least16_t
atomic_int_least32_t _Atomic int_least32_t
Atomic type name Direct type
atomic_uint_least32_t _Atomic uint_least32_t
atomic_int_least64_t _Atomic int_least64_t
atomic_uint_least64_t _Atomic uint_least64_t
atomic_int_fast8_t _Atomic int_fast8_t
atomic_uint_fast8_t _Atomic uint_fast8_t
atomic_int_fast16_t _Atomic int_fast16_t
atomic_uint_fast16_t _Atomic uint_fast16_t
atomic_int_fast32_t _Atomic int_fast32_t
atomic_uint_fast32_t _Atomic uint_fast32_t
atomic_int_fast64_t _Atomic int_fast64_t
atomic_uint_fast64_t _Atomic uint_fast64_t
atomic_intptr_t _Atomic intptr_t
atomic_uintptr_t _Atomic uintptr_t
atomic_size_t _Atomic size_t
atomic_ptrdiff_t _Atomic ptrdiff_t
atomic_intmax_t _Atomic intmax_t
atomic_uintmax_t _Atomic uintmax_t
Recommended practice
Footnote 317) See "future library directions" (7.33.10).
Footnote 318) The same representation and alignment requirements are meant to imply interchangeability as arguments to functions,
return values from functions, and members of unions.
2 The representation of an atomic integer type is not required to have the same size as the correspond-
ing regular type but it should have the same size whenever possible, as it eases effort required to
port existing code.
7.17.7 [Operations on atomic types]
1 There are only a few kinds of operations on atomic types, though there are many instances of those
kinds. This subclause specifies each general kind.
<IP_ADDRESS> [The atomic_store generic functions]
1 Synopsis
#include <stdatomic.h>
void atomic_store(volatile A *object, C desired);
void atomic_store_explicit(volatile A *object, C desired, memory_order order);
Description
2 The order argument shall not be memory_order_acquire, memory_order_consume, nor
memory_order_acq_rel. Atomically replace the value pointed to by object with the value of
desired. Memory is affected according to the value of order.
Returns
3 The atomic_store generic functions return no value.
<IP_ADDRESS> [The atomic_load generic functions]
1 Synopsis
#include <stdatomic.h>
C atomic_load(const volatile A *object);
C atomic_load_explicit(const volatile A *object, memory_order order);
Description
2 The order argument shall not be memory_order_release nor memory_order_acq_rel. Memory is
affected according to the value of order.
Returns
3 Atomically returns the value pointed to by object.
<IP_ADDRESS> [The atomic_exchange generic functions]
1 Synopsis
#include <stdatomic.h>
C atomic_exchange(volatile A *object, C desired);
C atomic_exchange_explicit(volatile A *object, C desired, memory_order order);
Description
2 Atomically replace the value pointed to by object with desired. Memory is affected according to
the value of order. These operations are read-modify-write operations (<IP_ADDRESS>).
Returns
3 Atomically returns the value pointed to by object immediately before the effects.
<IP_ADDRESS> [The atomic_compare_exchange generic functions]
1 Synopsis
#include <stdatomic.h>
bool atomic_compare_exchange_strong(volatile A *object, C *expected, C desired);
bool atomic_compare_exchange_strong_explicit(volatile A *object, C *expected,
C desired, memory_order success, memory_order failure);
bool atomic_compare_exchange_weak(volatile A *object, C *expected, C desired);
bool atomic_compare_exchange_weak_explicit(volatile A *object, C *expected,
C desired, memory_order success, memory_order failure);
Description
2 The failure argument shall not be memory_order_release nor memory_order_acq_rel. The
failure argument shall be no stronger than the success argument.
3 Atomically, compares the contents of the memory pointed to by object for equality with that
pointed to by expected, and if true, replaces the contents of the memory pointed to by object
with desired, and if false, updates the contents of the memory pointed to by expected with that
pointed to by object. Further, if the comparison is true, memory is affected according to the value
of success, and if the comparison is false, memory is affected according to the value of failure.
These operations are atomic read-modify-write operations (<IP_ADDRESS>).
4 NOTE 1 For example, the effect of atomic_compare_exchange_strong is
if (memcmp(object, expected, sizeof (*object)) == 0)
memcpy(object, &desired, sizeof (*object));
else
memcpy(expected, object, sizeof (*object));
5 A weak compare-and-exchange operation may fail spuriously. That is, even when the contents
of memory referred to by expected and object are equal, it may return zero and store back to
expected the same memory contents that were originally there.
6 NOTE 2 This spurious failure enables implementation of compare-and-exchange on a broader class of machines, e.g.
load-locked store-conditional machines.
7 EXAMPLE A consequence of spurious failure is that nearly all uses of weak compare-and-exchange will be in a loop.
exp = atomic_load(&cur);
do {
des = function(exp);
} while (!atomic_compare_exchange_weak(&cur, &exp, des));
When a compare-and-exchange is in a loop, the weak version will yield better performance on some platforms. When a weak
compare-and-exchange would require a loop and a strong one would not, the strong one is preferable.
Returns
8 The result of the comparison.
<IP_ADDRESS> [The atomic_fetch and modify generic functions]
1 The following operations perform arithmetic and bitwise computations. All of these operations
are applicable to an object of any atomic integer type. None of these operations is applicable to
atomic_bool. The key, operator, and computation correspondence is:
key op computation
add + addition
sub - subtraction
or | bitwise inclusive or
xor ^ bitwise exclusive or
and & bitwise and
Synopsis
2 #include <stdatomic.h>
C atomic_fetch_key(volatile A *object, M operand);
C atomic_fetch_key_explicit(volatile A *object, M operand, memory_order order);
Description
3 Atomically replaces the value pointed to by object with the result of the computation applied to
the value pointed to by object and the given operand. Memory is affected according to the value
of order. These operations are atomic read-modify-write operations (<IP_ADDRESS>). For signed integer
types, arithmetic performs silent wraparound on integer overflow; there are no undefined results.
For address types, the result may be an undefined address, but the operations otherwise have no
undefined behavior.
Returns
4 Atomically, the value pointed to by object immediately before the effects.
5 NOTE The operation of the atomic_fetch and modify generic functions are nearly equivalent to the operation of the
corresponding op= compound assignment operators. The only differences are that the compound assignment operators are
not guaranteed to operate atomically, and the value yielded by a compound assignment operator is the updated value of the
object, whereas the value returned by the atomic_fetch and modify generic functions is the previous value of the atomic
object.
7.17.8 [Atomic flag type and operations]
1 The atomic_flag type provides the classic test-and-set functionality. It has two states, set and clear.
2 Operations on an object of type atomic_flag shall be lock free.
3 NOTE Hence, as per 7.17.5, the operations should also be address-free. No other type requires lock-free operations, so the
atomic_flag type is the minimum hardware-implemented type needed to conform to this document. The remaining types
can be emulated with atomic_flag, though with less than ideal properties.
4 The macro ATOMIC_FLAG_INIT may be used to initialize an atomic_flag to the clear state. An
atomic_flag that is not explicitly initialized with ATOMIC_FLAG_INIT has initially an indeterminate
representation.
5 EXAMPLE
atomic_flag guard = ATOMIC_FLAG_INIT;
<IP_ADDRESS> [The atomic_flag_test_and_set functions]
1 Synopsis
#include <stdatomic.h>
bool atomic_flag_test_and_set(volatile atomic_flag *object);
bool atomic_flag_test_and_set_explicit(volatile atomic_flag *object,
memory_order order);
Description
2 Atomically places the atomic flag pointed to by object in the set state and returns the value
corresponding to the immediately preceding state. Memory is affected according to the value of
order. These operations are atomic read-modify-write operations (<IP_ADDRESS>).
Returns
3 The atomic_flag_test_and_set functions return the value that corresponds to the state of the
atomic flag immediately before the effects. The return value true corresponds to the set state and the
return value false corresponds to the clear state.
<IP_ADDRESS> [The atomic_flag_clear functions]
1 Synopsis
#include <stdatomic.h>
void atomic_flag_clear(volatile atomic_flag *object);
void atomic_flag_clear_explicit(volatile atomic_flag *object,
memory_order order);
Description
2 The order argument shall not be memory_order_acquire nor memory_order_acq_rel. Atomically
places the atomic flag pointed to by object into the clear state. Memory is affected according to the
value of order.
Returns
3 The atomic_flag_clear functions return no value.
7.18 [Bit and byte utilities <stdbit.h>]
7.18.1 [General]
1 The header <stdbit.h> defines the following macros, types, and functions, to work with the byte
and bit representation of many types, typically integer types. This header makes available the
size_t type name (7.21) and any uintN_t, intN_t, uint_leastN_t, or int_leastN_t type names
defined by the implementation (7.22).
2 The most significant index is the 0-based index counting from the most significant bit, 0, to the
least significant bit, w − 1, where w is the width of the type that is having its most significant index
computed.
3 The least significant index is the 0-based index counting from the least significant bit, 0, to the
most significant bit, w − 1, where w is the width of the type that is having its least significant index
computed.
4 It is unspecified whether any generic function declared in <stdbit.h> is a macro or an identifier
declared with external linkage. If a macro definition is suppressed in order to access an actual
function, or a program defines an external identifier with the name of a generic function, the
behavior is unspecified.
7.18.2 [Endian]
1 Two common methods of byte ordering in multi-byte scalar types are little-endian and big-endian.
Little-endian is a format for storage of binary data in which the least significant byte is placed
first, with the rest in ascending order. Or, that the least significant byte is stored at the smallest
memory address. Big-endian is a format for storage or transmission of binary data in which the
most significant byte is placed first, with the rest in descending order. Or, that the most significant
byte is stored at the smallest memory address. Other byte orderings are also possible.
2 The macros are:
__STDC_ENDIAN_LITTLE__
which represents a method of byte order storage least significant byte is placed first and the rest are
in ascending order, and is an integer constant expression;
__STDC_ENDIAN_BIG__
which represents a method of byte order storage most significant byte is placed first and the rest are
in descending order, and is an integer constant expression;
__STDC_ENDIAN_NATIVE__ /* see below */
which represents the method of byte order storage for the execution environment and is an integer
constant expression.
3 __STDC_ENDIAN_NATIVE__ shall expand to an integer constant expression whose value is equiv-
alent to the value of __STDC_ENDIAN_LITTLE__ if the execution environment is little-endian.
Otherwise, __STDC_ENDIAN_NATIVE__ shall expand to an integer constant expression whose
value is equivalent to the value of __STDC_ENDIAN_BIG__ if the execution environment is big-
endian. If __STDC_ENDIAN_NATIVE__ is not equivalent to either, then the byte order for the exe-
cution environment is implementation-defined. The value of the integer constant expression for
__STDC_ENDIAN_LITTLE__ and __STDC_ENDIAN_BIG__ are not equal.
7.18.3 [Count Leading Zeros]
1 Synopsis
#include <stdbit.h>
int stdc_leading_zerosuc(unsigned char value);
int stdc_leading_zerosus(unsigned short value);
int stdc_leading_zerosui(unsigned int value);
int stdc_leading_zerosul(unsigned long value);
int stdc_leading_zerosull(unsigned long long value);
generic_return_type stdc_leading_zeros(generic_value_type value);
Returns
Returns the number of consecutive 0 bits in value, starting from the most significant bit.
The type-generic function (marked by its generic_value_type argument) returns the appropriate
value based on the type of the input value, so long as it is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type shall be a suitably large signed integer type capable of representing
the computed result.
7.18.4 [Count Leading Ones]
1 Synopsis
#include <stdbit.h>
int stdc_leading_onesuc(unsigned char value);
int stdc_leading_onesus(unsigned short value);
int stdc_leading_onesui(unsigned int value);
int stdc_leading_onesul(unsigned long value);
int stdc_leading_onesull(unsigned long long value);
generic_return_type stdc_leading_ones(generic_value_type value);
Returns
Returns the number of consecutive 1 bits in value, starting from the most significant bit.
The type-generic function (marked by its generic_value_type argument) returns the appropriate
value based on the type of the input value, so long as it is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type shall be a suitably large signed integer type capable of representing
the computed result.
7.18.5 [Count Trailing Zeros]
1 Synopsis
#include <stdbit.h>
int stdc_trailing_zerosuc(unsigned char value);
int stdc_trailing_zerosus(unsigned short value);
int stdc_trailing_zerosui(unsigned int value);
int stdc_trailing_zerosul(unsigned long value);
int stdc_trailing_zerosull(unsigned long long value);
generic_return_type stdc_trailing_zeros(generic_value_type value);
Returns
Returns the number of consecutive 0 bits in value, starting from the least significant bit.
The type-generic function (marked by its generic_value_type argument) returns the appropriate
value based on the type of the input value, so long as it is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type shall be a suitably large signed integer type capable of representing
the computed result.
7.18.6 [Count Trailing Ones]
1 Synopsis
#include <stdbit.h>
int stdc_trailing_onesuc(unsigned char value);
int stdc_trailing_onesus(unsigned short value);
int stdc_trailing_onesui(unsigned int value);
int stdc_trailing_onesul(unsigned long value);
int stdc_trailing_onesull(unsigned long long value);
generic_return_type stdc_trailing_ones(generic_value_type value);
Returns
Returns the number of consecutive 1 bits in value, starting from the least significant bit.
The type-generic function (marked by its generic_value_type argument) returns the appropriate
value based on the type of the input value, so long as it is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type shall be a suitably large signed integer type capable of representing
the computed result.
7.18.7 [First Leading Zero]
1 Synopsis
#include <stdbit.h>
int stdc_first_leading_zerouc(unsigned char value);
int stdc_first_leading_zerous(unsigned short value);
int stdc_first_leading_zeroui(unsigned int value);
int stdc_first_leading_zeroul(unsigned long value);
int stdc_first_leading_zeroull(unsigned long long value);
generic_return_type stdc_first_leading_zero(generic_value_type value);
Returns
Returns the most significant index of the first 0 bit in value, plus 1. If it is not found, this function
returns 0.
The type-generic function (marked by its generic_value_type argument) returns the appropriate
value based on the type of the input value, so long as it is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type shall be a suitably large signed integer type capable of representing
the computed result.
7.18.8 [First Leading One]
1 Synopsis
#include <stdbit.h>
int stdc_first_leading_oneuc(unsigned char value);
int stdc_first_leading_oneus(unsigned short value);
int stdc_first_leading_oneui(unsigned int value);
int stdc_first_leading_oneul(unsigned long value);
int stdc_first_leading_oneull(unsigned long long value);
generic_return_type stdc_first_leading_one(generic_value_type value);
Returns
Returns the most significant index of the first 1 bit in value, plus 1. If it is not found, this function
returns 0.
The type-generic function (marked by its generic_value_type argument) returns the appropriate
value based on the type of the input value, so long as it is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type shall be a suitably large signed integer type capable of representing
the computed result.
7.18.9 [First Trailing Zero]
1 Synopsis
#include <stdbit.h>
int stdc_first_trailing_zerouc(unsigned char value);
int stdc_first_trailing_zerous(unsigned short value);
int stdc_first_trailing_zeroui(unsigned int value);
int stdc_first_trailing_zeroul(unsigned long value);
int stdc_first_trailing_zeroull(unsigned long long value);
generic_return_type stdc_first_trailing_zero(generic_value_type value);
Returns
Returns the least significant index of the first 0 bit in value, plus 1. If it is not found, this function
returns 0.
The type-generic function (marked by its generic_value_type argument) returns the appropriate
value based on the type of the input value, so long as it is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type shall be a suitably large signed integer type capable of representing
the computed result.
7.18.10 [First Trailing One]
1 Synopsis
#include <stdbit.h>
int stdc_first_trailing_oneuc(unsigned char value);
int stdc_first_trailing_oneus(unsigned short value);
int stdc_first_trailing_oneui(unsigned int value);
int stdc_first_trailing_oneul(unsigned long value);
int stdc_first_trailing_oneull(unsigned long long value);
generic_return_type stdc_first_trailing_one(generic_value_type value);
Returns
Returns the least significant index of the first 1 bit in value, plus 1. If it is not found, this function
returns 0.
The type-generic function (marked by its generic_value_type argument) returns the appropriate
value based on the type of the input value, so long as it is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type shall be a suitably large signed integer type capable of representing
the computed result.
7.18.11 [Count Ones]
1 Synopsis
#include <stdbit.h>
int stdc_count_onesuc(unsigned char value);
int stdc_count_onesus(unsigned short value);
int stdc_count_onesui(unsigned int value);
int stdc_count_onesul(unsigned long value);
int stdc_count_onesull(unsigned long long value);
generic_return_type stdc_count_ones(generic_value_type value);
Returns
Returns the total number of 1 bits within the given value.
The type-generic function (marked by its generic_value_type argument) returns the previously
described result for a given input value so long as the generic_value_type is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type shall be a suitably large signed integer type capable of representing
the computed result.
7.18.12 [Count Zeros]
1 Synopsis
#include <stdbit.h>
int stdc_count_zerosuc(unsigned char value);
int stdc_count_zerosus(unsigned short value);
int stdc_count_zerosui(unsigned int value);
int stdc_count_zerosul(unsigned long value);
int stdc_count_zerosull(unsigned long long value);
generic_return_type stdc_count_zeros(generic_value_type value);
Returns
Returns the total number of 0 bits within the given value.
The type-generic function (marked by its generic_value_type argument) returns the previously
described result for a given input value so long as the generic_value_type is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type for the type-generic function need not be the same as the type of
value. It shall be suitably large unsigned integer type capable of representing the computed result.
7.18.13 [Single-bit Check]
1 Synopsis
#include <stdbit.h>
bool stdc_has_single_bituc(unsigned char value);
bool stdc_has_single_bitus(unsigned short value);
bool stdc_has_single_bitui(unsigned int value);
bool stdc_has_single_bitul(unsigned long value);
bool stdc_has_single_bitull(unsigned long long value);
bool stdc_has_single_bit(generic_value_type value);
Returns
The stdc_has_single_bit functions returns true if and only if there is a single 1 bit in value.
The type-generic function (marked by its generic_value_type argument) returns the previously
described result for a given input value so long as the generic_value_type is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
7.18.14 [Bit Width]
1 Synopsis
#include <stdbit.h>
int stdc_bit_widthuc(unsigned char value);
int stdc_bit_widthus(unsigned short value);
int stdc_bit_widthui(unsigned int value);
int stdc_bit_widthul(unsigned long value);
int stdc_bit_widthull(unsigned long long value);
generic_return_type stdc_bit_width(generic_value_type value);
Description
The stdc_bit_width functions compute the smallest number of bits needed to store value.
Returns
The stdc_bit_width functions return 0 if value is 0. Otherwise, they return 1 + ⌊log2(value)⌋.
The type-generic function (marked by its generic_value_type argument) returns the previously
described result for a given input value so long as the generic_value_type is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
The generic_return_type type for the type-generic function need not be the same as the type of
value. It shall be suitably large signed integer type capable of representing the computed result.
7.18.15 [Bit Floor]
1 Synopsis
#include <stdbit.h>