Programming languages — C (INTERNATIONAL STANDARD ISO/IEC 9899:TC3) - page 9

7.8 Format conversion of integer types

<inttypes.h>

1

The header

<inttypes.h>

includes the header

<stdint.h>

and extends it with

additional facilities provided by hosted implementations.

2

It declares functions for manipulating greatest-width integers and converting numeric
character strings to greatest-width integers, and it declares the type

imaxdiv_t

which is a structure type that is the type of the value returned by the

imaxdiv

function.

For each type declared in

<stdint.h>

, it defines corresponding macros for conversion

specifiers for use with the formatted input/output functions.

190)

Forward references:

integer types

<stdint.h>

(7.18), formatted input/output

functions (7.19.6), formatted wide character input/output functions (7.24.2).

7.8.1 Macros for format specifiers

1

Each of the following object-like macros

191)

expands to a character string literal

containing a conversion specifier, possibly modified by a length modifier, suitable for use
within the format argument of a formatted input/output function when converting the
corresponding integer type. These macro names have the general form of

PRI

(character

string literals for the

fprintf

and

fwprintf

family) or

SCN

(character string literals

for the

fscanf

and

fwscanf

family),

192)

followed by the conversion specifier,

followed by a name corresponding to a similar type name in 7.18.1. In these names, N
represents the width of the type as described in 7.18.1. For example,

PRIdFAST32

can

be used in a format string to print the value of an integer of type

int_fast32_t

.

2

The

fprintf

macros for signed integers are:

PRId

N

PRIdLEAST

N

PRIdFAST

N

PRIdMAX PRIdPTR

PRIi

N

PRIiLEAST

N

PRIiFAST

N

PRIiMAX PRIiPTR

190) See ‘‘future library directions’’ (7.26.4).

191) C++ implementations should define these macros only when

_ _STDC_FORMAT_MACROS

is defined

before

<inttypes.h>

is included.

192) Separate macros are given for use with

fprintf

and

fscanf

functions because, in the general case,

different format specifiers may be required for

fprintf

and

fscanf

, even when the type is the

same.

198 Library

§7.8.1

3

The

fprintf

macros for unsigned integers are:

PRIo

N

PRIoLEAST

N

PRIoFAST

N

PRIoMAX PRIoPTR

PRIu

N

PRIuLEAST

N

PRIuFAST

N

PRIuMAX PRIuPTR

PRIx

N

PRIxLEAST

N

PRIxFAST

N

PRIxMAX PRIxPTR

PRIX

N

PRIXLEAST

N

PRIXFAST

N

PRIXMAX PRIXPTR

4

The

fscanf

macros for signed integers are:

SCNd

N

SCNdLEAST

N

SCNdFAST

N

SCNdMAX SCNdPTR

SCNi

N

SCNiLEAST

N

SCNiFAST

N

SCNiMAX SCNiPTR

5

The

fscanf

macros for unsigned integers are:

SCNo

N

SCNoLEAST

N

SCNoFAST

N

SCNoMAX SCNoPTR

SCNu

N

SCNuLEAST

N

SCNuFAST

N

SCNuMAX SCNuPTR

SCNx

N

SCNxLEAST

N

SCNxFAST

N

SCNxMAX SCNxPTR

6

For each type that the implementation provides in

<stdint.h>

, the corresponding

fprintf

macros shall be defined and the corresponding

fscanf

macros shall be

defined unless the implementation does not have a suitable

fscanf

length modifier for

the type.

7

EXAMPLE

#include <inttypes.h>

#include <wchar.h>

int main(void)

{

uintmax_t i = UINTMAX_MAX;

//

this type always exists

wprintf(L"The largest integer value is %020"

PRIxMAX "\n", i);

return 0;

}

7.8.2 Functions for greatest-width integer types

7.8.2.1 The

imaxabs

function

Synopsis

1

#include <inttypes.h>

intmax_t imaxabs(intmax_t j);

Description

2

The

imaxabs

function computes the absolute value of an integer

j

. If the result cannot

be represented, the behavior is undefined.

193)

193) The absolute value of the most negative number cannot be represented in two’s complement.

§7.8.2.1 Library

199

Returns

3

The

imaxabs

function returns the absolute value.

7.8.2.2 The

imaxdiv

function

Synopsis

1

#include <inttypes.h>

imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);

Description

2

The

imaxdiv

function computes

numer / denom

and

numer % denom

in a single

operation.

Returns

3

The

imaxdiv

function returns a structure of type

imaxdiv_t

comprising both the

quotient and the remainder. The structure shall contain (in either order) the members

quot

(the quotient) and

rem

(the remainder), each of which has type

intmax_t

. If

either part of the result cannot be represented, the behavior is undefined.

7.8.2.3 The

strtoimax

and

strtoumax

functions

Synopsis

1

#include <inttypes.h>

intmax_t strtoimax(const char * restrict nptr,

char ** restrict endptr, int base);

uintmax_t strtoumax(const char * restrict nptr,

char ** restrict endptr, int base);

Description

2

The

strtoimax

and

strtoumax

functions are equivalent to the

strtol

,

strtoll

,

strtoul

, and

strtoull

functions, except that the initial portion of the string is

converted to

intmax_t

and

uintmax_t

representation, respectively.

Returns

3

The

strtoimax

and

strtoumax

functions return the converted value, if any. If no

conversion could be performed, zero is returned. If the correct value is outside the range
of representable values,

INTMAX_MAX

,

INTMAX_MIN

, or

UINTMAX_MAX

is returned

(according to the return type and sign of the value, if any), and the value of the macro

ERANGE

is stored in

errno

.

Forward references: the

strtol

,

strtoll

,

strtoul

, and

strtoull

functions

(7.20.1.4).

200 Library

§7.8.2.3

7.8.2.4 The

wcstoimax

and

wcstoumax

functions

Synopsis

1

#include <stddef.h>

//

for

wchar_t

#include <inttypes.h>

intmax_t wcstoimax(const wchar_t * restrict nptr,

wchar_t ** restrict endptr, int base);

uintmax_t wcstoumax(const wchar_t * restrict nptr,

wchar_t ** restrict endptr, int base);

Description

2

The

wcstoimax

and

wcstoumax

functions are equivalent to the

wcstol

,

wcstoll

,

wcstoul

, and

wcstoull

functions except that the initial portion of the wide string is

converted to

intmax_t

and

uintmax_t

representation, respectively.

Returns

3

The

wcstoimax

function returns the converted value, if any. If no conversion could be

performed, zero is returned. If the correct value is outside the range of representable
values,

INTMAX_MAX

,

INTMAX_MIN

, or

UINTMAX_MAX

is returned (according to the

return type and sign of the value, if any), and the value of the macro

ERANGE

is stored in

errno

.

Forward references: the

wcstol

,

wcstoll

,

wcstoul

, and

wcstoull

functions

(7.24.4.1.2).

§7.8.2.4 Library

201

7.9 Alternative spellings

<iso646.h>

1

The header

<iso646.h>

defines the following eleven macros (on the left) that expand

to the corresponding tokens (on the right):

and &&

and_eq &=

bitand &

bitor |

compl ~

not !

not_eq !=

or ||

or_eq |=

xor ^

xor_eq ^=

202 Library

§7.9

7.10 Sizes of integer types

<limits.h>

1

The header

<limits.h>

defines several macros that expand to various limits and

parameters of the standard integer types.

2

The macros, their meanings, and the constraints (or restrictions) on their values are listed
in 5.2.4.2.1.

§7.10 Library

203

7.11 Localization

<locale.h>

1

The header

<locale.h>

declares two functions, one type, and defines several macros.

2

The type is

struct lconv

which contains members related to the formatting of numeric values. The structure shall
contain at least the following members, in any order. The semantics of the members and
their normal ranges are explained in 7.11.2.1. In the

"C"

locale, the members shall have

the values specified in the comments.

char *decimal_point;

// "."

char *thousands_sep;

// ""

char *grouping;

// ""

char *mon_decimal_point;

// ""

char *mon_thousands_sep;

// ""

char *mon_grouping;

// ""

char *positive_sign;

// ""

char *negative_sign;

// ""

char *currency_symbol;

// ""

char frac_digits;

// CHAR_MAX

char p_cs_precedes;

// CHAR_MAX

char n_cs_precedes;

// CHAR_MAX

char p_sep_by_space;

// CHAR_MAX

char n_sep_by_space;

// CHAR_MAX

char p_sign_posn;

// CHAR_MAX

char n_sign_posn;

// CHAR_MAX

char *int_curr_symbol;

// ""

char int_frac_digits;

// CHAR_MAX

char int_p_cs_precedes;

// CHAR_MAX

char int_n_cs_precedes;

// CHAR_MAX

char int_p_sep_by_space;

// CHAR_MAX

char int_n_sep_by_space;

// CHAR_MAX

char int_p_sign_posn;

// CHAR_MAX

char int_n_sign_posn;

// CHAR_MAX

204 Library

§7.11

3

The macros defined are

NULL

(described in 7.17); and

LC_ALL

LC_COLLATE

LC_CTYPE

LC_MONETARY

LC_NUMERIC

LC_TIME

which expand to integer constant expressions with distinct values, suitable for use as the
first argument to the

setlocale

function.

194)

Additional macro definitions, beginning

with the characters

LC_

and an uppercase letter,

195)

may also be specified by the

implementation.

7.11.1 Locale control

7.11.1.1 The

setlocale

function

Synopsis

1

#include <locale.h>

char *setlocale(int category, const char *locale);

Description

2

The

setlocale

function selects the appropriate portion of the program’s locale as

specified by the

category

and

locale

arguments. The

setlocale

function may be

used to change or query the program’s entire current locale or portions thereof. The value

LC_ALL

for

category

names the program’s entire locale; the other values for

category

name only a portion of the program’s locale.

LC_COLLATE

affects the

behavior of the

strcoll

and

strxfrm

functions.

LC_CTYPE

affects the behavior of

the character handling functions

196)

and the multibyte and wide character functions.

LC_MONETARY

affects the monetary formatting information returned by the

localeconv

function.

LC_NUMERIC

affects the decimal-point character for the

formatted input/output functions and the string conversion functions, as well as the
nonmonetary formatting information returned by the

localeconv

function.

LC_TIME

affects the behavior of the

strftime

and

wcsftime

functions.

3

A value of

"C"

for

locale

specifies the minimal environment for C translation; a value

of

""

for

locale

specifies the locale-specific native environment. Other

implementation-defined strings may be passed as the second argument to

setlocale

.

194) ISO/IEC 9945−2 specifies locale and charmap formats that may be used to specify locales for C.

195) See ‘‘future library directions’’ (7.26.5).

196) The only functions in 7.4 whose behavior is not affected by the current locale are

isdigit

and

isxdigit

.

§7.11.1.1 Library

205

4

At program startup, the equivalent of

setlocale(LC_ALL, "C");

is executed.

5

The implementation shall behave as if no library function calls the

setlocale

function.

Returns

6

If a pointer to a string is given for

locale

and the selection can be honored, the

setlocale

function returns a pointer to the string associated with the specified

category

for the new locale. If the selection cannot be honored, the

setlocale

function returns a null pointer and the program’s locale is not changed.

7

A null pointer for

locale

causes the

setlocale

function to return a pointer to the

string associated with the

category

for the program’s current locale; the program’s

locale is not changed.

197)

8

The pointer to string returned by the

setlocale

function is such that a subsequent call

with that string value and its associated category will restore that part of the program’s
locale. The string pointed to shall not be modified by the program, but may be
overwritten by a subsequent call to the

setlocale

function.

Forward references:

formatted input/output functions (7.19.6), multibyte/wide

character conversion functions (7.20.7), multibyte/wide string conversion functions
(7.20.8), numeric conversion functions (7.20.1), the

strcoll

function (7.21.4.3), the

strftime

function (7.23.3.5), the

strxfrm

function (7.21.4.5).

7.11.2 Numeric formatting convention inquiry

7.11.2.1 The

localeconv

function

Synopsis

1

#include <locale.h>

struct lconv *localeconv(void);

Description

2

The

localeconv

function sets the components of an object with type

struct lconv

with values appropriate for the formatting of numeric quantities (monetary and otherwise)
according to the rules of the current locale.

3

The members of the structure with type

char *

are pointers to strings, any of which

(except

decimal_point

) can point to

""

, to indicate that the value is not available in

the current locale or is of zero length. Apart from

grouping

and

mon_grouping

, the

197) The implementation shall arrange to encode in a string the various categories due to a heterogeneous

locale when

category

has the value

LC_ALL

.

206 Library

§7.11.2.1

strings shall start and end in the initial shift state. The members with type

char

are

nonnegative numbers, any of which can be

CHAR_MAX

to indicate that the value is not

available in the current locale. The members include the following:

char *decimal_point

The decimal-point character used to format nonmonetary quantities.

char *thousands_sep

The character used to separate groups of digits before the decimal-point
character in formatted nonmonetary quantities.

char *grouping

A string whose elements indicate the size of each group of digits in
formatted nonmonetary quantities.

char *mon_decimal_point

The decimal-point used to format monetary quantities.

char *mon_thousands_sep

The separator for groups of digits before the decimal-point in formatted
monetary quantities.

char *mon_grouping

A string whose elements indicate the size of each group of digits in
formatted monetary quantities.

char *positive_sign

The string used to indicate a nonnegative-valued formatted monetary
quantity.

char *negative_sign

The string used to indicate a negative-valued formatted monetary quantity.

char *currency_symbol

The local currency symbol applicable to the current locale.

char frac_digits

The number of fractional digits (those after the decimal-point) to be
displayed in a locally formatted monetary quantity.

char p_cs_precedes

Set to 1 or 0 if the

currency_symbol

respectively precedes or

succeeds the value for a nonnegative locally formatted monetary quantity.

char n_cs_precedes

Set to 1 or 0 if the

currency_symbol

respectively precedes or

succeeds the value for a negative locally formatted monetary quantity.

§7.11.2.1 Library

207

char p_sep_by_space

Set to a value indicating the separation of the

currency_symbol

, the

sign string, and the value for a nonnegative locally formatted monetary
quantity.

char n_sep_by_space

Set to a value indicating the separation of the

currency_symbol

, the

sign string, and the value for a negative locally formatted monetary
quantity.

char p_sign_posn

Set to a value indicating the positioning of the

positive_sign

for a

nonnegative locally formatted monetary quantity.

char n_sign_posn

Set to a value indicating the positioning of the

negative_sign

for a

negative locally formatted monetary quantity.

char *int_curr_symbol

The international currency symbol applicable to the current locale. The
first three characters contain the alphabetic international currency symbol
in accordance with those specified in ISO 4217. The fourth character
(immediately preceding the null character) is the character used to separate
the international currency symbol from the monetary quantity.

char int_frac_digits

The number of fractional digits (those after the decimal-point) to be
displayed in an internationally formatted monetary quantity.

char int_p_cs_precedes

Set to 1 or 0 if the

int_curr_symbol

respectively precedes or

succeeds the value for a nonnegative internationally formatted monetary
quantity.

char int_n_cs_precedes

Set to 1 or 0 if the

int_curr_symbol

respectively precedes or

succeeds the value for a negative internationally formatted monetary
quantity.

char int_p_sep_by_space

Set to a value indicating the separation of the

int_curr_symbol

, the

sign string, and the value for a nonnegative internationally formatted
monetary quantity.

208 Library

§7.11.2.1

char int_n_sep_by_space

Set to a value indicating the separation of the

int_curr_symbol

, the

sign string, and the value for a negative internationally formatted monetary
quantity.

char int_p_sign_posn

Set to a value indicating the positioning of the

positive_sign

for a

nonnegative internationally formatted monetary quantity.

char int_n_sign_posn

Set to a value indicating the positioning of the

negative_sign

for a

negative internationally formatted monetary quantity.

4

The elements of

grouping

and

mon_grouping

are interpreted according to the

following:

CHAR_MAX

No further grouping is to be performed.

0

The previous element is to be repeatedly used for the remainder of the
digits.

other

The integer value is the number of digits that compose the current group.
The next element is examined to determine the size of the next group of
digits before the current group.

5

The values of

p_sep_by_space

,

n_sep_by_space

,

int_p_sep_by_space

,

and

int_n_sep_by_space

are interpreted according to the following:

0

No space separates the currency symbol and value.

1

If the currency symbol and sign string are adjacent, a space separates them from the
value; otherwise, a space separates the currency symbol from the value.

2

If the currency symbol and sign string are adjacent, a space separates them;
otherwise, a space separates the sign string from the value.

For

int_p_sep_by_space

and

int_n_sep_by_space

, the fourth character of

int_curr_symbol

is used instead of a space.

6

The values of

p_sign_posn

,

n_sign_posn

,

int_p_sign_posn

,

and

int_n_sign_posn

are interpreted according to the following:

0

Parentheses surround the quantity and currency symbol.

1

The sign string precedes the quantity and currency symbol.

2

The sign string succeeds the quantity and currency symbol.

3

The sign string immediately precedes the currency symbol.

4

The sign string immediately succeeds the currency symbol.

§7.11.2.1 Library

209

7

The implementation shall behave as if no library function calls the

localeconv

function.

Returns

8

The

localeconv

function returns a pointer to the filled-in object. The structure

pointed to by the return value shall not be modified by the program, but may be
overwritten by a subsequent call to the

localeconv

function. In addition, calls to the

setlocale

function with categories

LC_ALL

,

LC_MONETARY

, or

LC_NUMERIC

may

overwrite the contents of the structure.

9

EXAMPLE 1

The following table illustrates rules which may well be used by four countries to format

monetary quantities.

Local format

International format

Country Positive Neg ative Positive Neg ative

Country1

1.234,56 mk

-1.234,56 mk

FIM 1.234,56

FIM -1.234,56

Country2

L.1.234 -L.1.234 ITL 1.234 -ITL 1.234

Country3

ƒ 1.234,56 ƒ -1.234,56 NLG 1.234,56 NLG -1.234,56

Country4

SFrs.1,234.56 SFrs.1,234.56C CHF 1,234.56 CHF 1,234.56C

10

For these four countries, the respective values for the monetary members of the structure returned by

localeconv

could be:

Country1 Country2 Country3 Country4

mon_decimal_point ","

"" ","

"."

mon_thousands_sep "."

"." "."

","

mon_grouping "\3"

"\3" "\3"

"\3"

positive_sign ""

"" ""

""

negative_sign "-"

"-" "-"

"C"

currency_symbol "mk"

"L." "\u0192"

"SFrs."

frac_digits 2

0

2

 

2

p_cs_precedes 0

1

1

 

1

n_cs_precedes 0

1

1

 

1

p_sep_by_space 1

0

1

 

0

n_sep_by_space 1

0

2

 

0

p_sign_posn 1

1

1

 

1

n_sign_posn 1

1

4

 

2

int_curr_symbol "FIM "

"ITL "

"NLG "

"CHF "

int_frac_digits 2

0

2

 

2

int_p_cs_precedes 1

1

1

 

1

int_n_cs_precedes 1

1

1

 

1

int_p_sep_by_space 1

1

1

 

1

int_n_sep_by_space 2

1

2

 

1

int_p_sign_posn 1

1

1

 

1

int_n_sign_posn 4

1

4

 

2

210 Library

§7.11.2.1

11

EXAMPLE 2

The following table illustrates how the cs_precedes, sep_by_space, and sign_posn members

affect the formatted value.

p_sep_by_space

p_cs_precedes p_sign_posn

0

1

2

0

0

(1.25$) (1.25 $) (1.25$)

1

+1.25$ +1.25 $

+ 1.25$

2

1.25$+ 1.25 $+ 1.25$ +

3

1.25+$ 1.25 +$ 1.25+ $

4

1.25$+ 1.25 $+ 1.25$ +

1

0

($1.25) ($ 1.25) ($1.25)

1

+$1.25 +$ 1.25 + $1.25

2

$1.25+ $ 1.25+ $1.25 +

3

+$1.25 +$ 1.25 + $1.25

4

$+1.25 $+ 1.25 $ +1.25

§7.11.2.1 Library

211

7.12 Mathematics

<math.h>

1

The header

<math.h>

declares two types and many mathematical functions and defines

several macros. Most synopses specify a family of functions consisting of a principal
function with one or more

double

parameters, a

double

return value, or both; and

other functions with the same name but with

f

and

l

suffixes, which are corresponding

functions with

float

and

long double

parameters, return values, or both.

198)

Integer arithmetic functions and conversion functions are discussed later.

2

The types

float_t

double_t

are floating types at least as wide as

float

and

double

, respectively, and such that

double_t

is at least as wide as

float_t

. If

FLT_EVAL_METHOD

equals 0,

float_t

and

double_t

are

float

and

double

,

respectively; if

FLT_EVAL_METHOD

equals 1, they are both

double

; if

FLT_EVAL_METHOD

equals

2, they are both

long double

; and for other values of

FLT_EVAL_METHOD

, they are

otherwise implementation-defined.

199)

3

The macro

HUGE_VAL

expands to a positive

double

constant expression, not necessarily representable as a

float

. The macros

HUGE_VALF

HUGE_VALL

are respectively

float

and

long double

analogs of

HUGE_VAL

.

200)

4

The macro

INFINITY

expands to a constant expression of type

float

representing positive or unsigned

infinity, if available; else to a positive constant of type

float

that overflows at

198) Particularly on systems with wide expression evaluation, a

<math.h>

function might pass arguments

and return values in wider format than the synopsis prototype indicates.

199) The types

float_t

and

double_t

are intended to be the implementation’s most efficient types at

least as wide as

float

and

double

, respectively. For

FLT_EVAL_METHOD

equal 0, 1, or 2, the

type

float_t

is the narrowest type used by the implementation to evaluate floating expressions.

200)

HUGE_VAL

,

HUGE_VALF

, and

HUGE_VALL

can be positive infinities in an implementation that

supports infinities.

212 Library

§7.12

translation time.

201)

5

The macro

NAN

is defined if and only if the implementation supports quiet NaNs for the

float

type. It

expands to a constant expression of type

float

representing a quiet NaN.

6

The number classification macros

FP_INFINITE

FP_NAN

FP_NORMAL

FP_SUBNORMAL

FP_ZERO

represent the mutually exclusive kinds of floating-point values. They expand to integer
constant expressions with distinct values. Additional implementation-defined floating-
point classifications, with macro definitions beginning with

FP_

and an uppercase letter,

may also be specified by the implementation.

7

The macro

FP_FAST_FMA

is optionally defined. If defined, it indicates that the

fma

function generally executes

about as fast as, or faster than, a multiply and an add of

double

operands.

202)

The

macros

FP_FAST_FMAF

FP_FAST_FMAL

are, respectively,

float

and

long double

analogs of

FP_FAST_FMA

. If defined,

these macros expand to the integer constant

1

.

8

The macros

FP_ILOGB0

FP_ILOGBNAN

expand to integer constant expressions whose values are returned by

ilogb(x)

if

x

is

zero or NaN, respectively. The value of

FP_ILOGB0

shall be either

INT_MIN

or

-INT_MAX

. The value of

FP_ILOGBNAN

shall be either

INT_MAX

or

INT_MIN

.

201) In this case, using

INFINITY

will violate the constraint in 6.4.4 and thus require a diagnostic.

202) Typically, the

FP_FAST_FMA

macro is defined if and only if the

fma

function is implemented

directly with a hardware multiply-add instruction. Software implementations are expected to be
substantially slower.

§7.12 Library

213

9

The macros

MATH_ERRNO

MATH_ERREXCEPT

expand to the integer constants

1

and

2

, respectively; the macro

math_errhandling

expands to an expression that has type

int

and the value

MATH_ERRNO

,

MATH_ERREXCEPT

, or the bitwise

OR

of both. The value of

math_errhandling

is

constant for the duration of the program.

It is unspecified whether

math_errhandling

is a macro or an identifier with external linkage. If a macro

definition is suppressed or a program defines an identifier with the name

math_errhandling

,

the behavior is undefined.

If the expression

math_errhandling & MATH_ERREXCEPT

can be nonzero, the implementation

shall define the macros

FE_DIVBYZERO

,

FE_INVALID

, and

FE_OVERFLOW

in

<fenv.h>

.

7.12.1 Treatment of error conditions

1

The behavior of each of the functions in

<math.h>

is specified for all representable

values of its input arguments, except where stated otherwise. Each function shall execute
as if it were a single operation without generating any externally visible exceptional
conditions.

2

For all functions, a domain error occurs if an input argument is outside the domain over
which the mathematical function is defined. The description of each function lists any
required domain errors; an implementation may define additional domain errors, provided
that such errors are consistent with the mathematical definition of the function.

203)

On a

domain error, the function returns an implementation-defined value; if the integer
expression

math_errhandling & MATH_ERRNO

is nonzero, the integer expression

errno

acquires the value

EDOM

; if the integer expression

math_errhandling &

MATH_ERREXCEPT

is nonzero, the ‘‘invalid’’ floating-point exception is raised.

3

Similarly, a range error occurs if the mathematical result of the function cannot be
represented in an object of the specified type, due to extreme magnitude.

4

A floating result overflows if the magnitude of the mathematical result is finite but so
large that the mathematical result cannot be represented without extraordinary roundoff
error in an object of the specified type. If a floating result overflows and default rounding
is in effect, or if the mathematical result is an exact infinity from finite arguments (for
example

log(0.0)

), then the function returns the value of the macro

HUGE_VAL

,

203) In an implementation that supports infinities, this allows an infinity as an argument to be a domain

error if the mathematical domain of the function does not include the infinity.

214 Library

§7.12.1

HUGE_VALF

, or

HUGE_VALL

according to the return type, with the same sign as the

correct value of the function; if the integer expression

math_errhandling &

MATH_ERRNO

is nonzero, the integer expression

errno

acquires the value

ERANGE

; if

the integer expression

math_errhandling & MATH_ERREXCEPT

is nonzero, the

‘‘divide-by-zero’’ floating-point exception is raised if the mathematical result is an exact
infinity and the ‘‘overflow’’ floating-point exception is raised otherwise.

5

The result underflows if the magnitude of the mathematical result is so small that the
mathematical result cannot be represented, without extraordinary roundoff error, in an
object of the specified type.

204)

If the result underflows, the function returns an

implementation-defined value whose magnitude is no greater than the smallest
normalized positive number in the specified type; if the integer expression

math_errhandling & MATH_ERRNO

is nonzero, whether

errno

acquires the

value

ERANGE

is implementation-defined; if the integer expression

math_errhandling & MATH_ERREXCEPT

is nonzero, whether the ‘‘underflow’’

floating-point exception is raised is implementation-defined.

7.12.2 The

FP_CONTRACT

pragma

Synopsis

1

#include <math.h>

#pragma STDC FP_CONTRACT

on-off-switch

Description

2

The

FP_CONTRACT

pragma can be used to allow (if the state is ‘‘on’’) or disallow (if the

state is ‘‘off’’) the implementation to contract expressions (6.5). Each pragma can occur
either outside external declarations or preceding all explicit declarations and statements
inside a compound statement. When outside external declarations, the pragma takes
effect from its occurrence until another

FP_CONTRACT

pragma is encountered, or until

the end of the translation unit. When inside a compound statement, the pragma takes
effect from its occurrence until another

FP_CONTRACT

pragma is encountered

(including within a nested compound statement), or until the end of the compound
statement; at the end of a compound statement the state for the pragma is restored to its
condition just before the compound statement. If this pragma is used in any other
context, the behavior is undefined. The default state (‘‘on’’ or ‘‘off’’) for the pragma is
implementation-defined.

204) The term underflow here is intended to encompass both ‘‘gradual underflow’’ as in IEC 60559 and

also ‘‘flush-to-zero’’ underflow.

§7.12.2 Library

215

7.12.3 Classification macros

1

In the synopses in this subclause, real-floating indicates that the argument shall be an
expression of real floating type.

7.12.3.1 The

fpclassify

macro

Synopsis

1

#include <math.h>

int fpclassify(

real-floating

x);

Description

2

The

fpclassify

macro classifies its argument value as NaN, infinite, normal,

subnormal, zero, or into another implementation-defined category. First, an argument
represented in a format wider than its semantic type is converted to its semantic type.
Then classification is based on the type of the argument.

205)

Returns

3

The

fpclassify

macro returns the value of the number classification macro

appropriate to the value of its argument.

4

EXAMPLE The

fpclassify

macro might be implemented in terms of ordinary functions as

#define fpclassify(x) \

((sizeof (x) == sizeof (float))

? _ _fpclassifyf(x) : \

(sizeof (x) == sizeof (double)) ? _ _fpclassifyd(x) : \

_ _fpclassifyl(x))

7.12.3.2 The

isfinite

macro

Synopsis

1

#include <math.h>

int isfinite(

real-floating

x);

Description

2

The

isfinite

macro determines whether its argument has a finite value (zero,

subnormal, or normal, and not infinite or NaN). First, an argument represented in a
format wider than its semantic type is converted to its semantic type. Then determination
is based on the type of the argument.

205) Since an expression can be evaluated with more range and precision than its type has, it is important to

know the type that classification is based on. For example, a normal

long double

value might

become subnormal when converted to

double

, and zero when converted to

float

.

216 Library

§7.12.3.2

Returns

3

The

isfinite

macro returns a nonzero value if and only if its argument has a finite

value.

7.12.3.3 The

isinf

macro

Synopsis

1

#include <math.h>

int isinf(

real-floating

x);

Description

2

The

isinf

macro determines whether its argument value is an infinity (positive or

negative). First, an argument represented in a format wider than its semantic type is
converted to its semantic type. Then determination is based on the type of the argument.

Returns

3

The

isinf

macro returns a nonzero value if and only if its argument has an infinite

value.

7.12.3.4 The

isnan

macro

Synopsis

1

#include <math.h>

int isnan(

real-floating

x);

Description

2

The

isnan

macro determines whether its argument value is a NaN. First, an argument

represented in a format wider than its semantic type is converted to its semantic type.
Then determination is based on the type of the argument.

206)

Returns

3

The

isnan

macro returns a nonzero value if and only if its argument has a NaN value.

7.12.3.5 The

isnormal

macro

Synopsis

1

#include <math.h>

int isnormal(

real-floating

x);

206) For the

isnan

macro, the type for determination does not matter unless the implementation supports

NaNs in the evaluation type but not in the semantic type.

§7.12.3.5 Library

217

Description

2

The

isnormal

macro determines whether its argument value is normal (neither zero,

subnormal, infinite, nor NaN). First, an argument represented in a format wider than its
semantic type is converted to its semantic type. Then determination is based on the type
of the argument.

Returns

3

The

isnormal

macro returns a nonzero value if and only if its argument has a normal

value.

7.12.3.6 The

signbit

macro

Synopsis

1

#include <math.h>

int signbit(

real-floating

x);

Description

2

The

signbit

macro determines whether the sign of its argument value is negative.

207)

Returns

3

The

signbit

macro returns a nonzero value if and only if the sign of its argument value

is negative.

7.12.4 Trigonometric functions

7.12.4.1 The

acos

functions

Synopsis

1

#include <math.h>

double acos(double x);

float acosf(float x);

long double acosl(long double x);

Description

2

The

acos

functions compute the principal value of the arc cosine of

x

. A domain error

occurs for arguments not in the interval [

−

1,

+

1].

Returns

3

The

acos

functions return arccos

x

in the interval [0,

π

] radians.

207) The

signbit

macro reports the sign of all values, including infinities, zeros, and NaNs. If zero is

unsigned, it is treated as positive.

218 Library

§7.12.4.1

7.12.4.2 The

asin

functions

Synopsis

1

#include <math.h>

double asin(double x);

float asinf(float x);

long double asinl(long double x);

Description

2

The

asin

functions compute the principal value of the arc sine of

x

. A domain error

occurs for arguments not in the interval [

−

1,

+

1].

Returns

3

The

asin

functions return arcsin

x

in the interval [

−

π

/2,

+

π

/2] radians.

7.12.4.3 The

atan

functions

Synopsis

1

#include <math.h>

double atan(double x);

float atanf(float x);

long double atanl(long double x);

Description

2

The

atan

functions compute the principal value of the arc tangent of

x

.

Returns

3

The

atan

functions return arctan

x

in the interval [

−

π

/2,

+

π

/2] radians.

7.12.4.4 The

atan2

functions

Synopsis

1

#include <math.h>

double atan2(double y, double x);

float atan2f(float y, float x);

long double atan2l(long double y, long double x);

Description

2

The

atan2

functions compute the value of the arc tangent of

y

/

x

, using the signs of both

arguments to determine the quadrant of the return value. A domain error may occur if
both arguments are zero.

Returns

3

The

atan2

functions return arctan

y

/

x

in the interval [

−

π

,

+

π

] radians.

§7.12.4.4 Library

219

7.12.4.5 The

cos

functions

Synopsis

1

#include <math.h>

double cos(double x);

float cosf(float x);

long double cosl(long double x);

Description

2

The

cos

functions compute the cosine of

x

(measured in radians).

Returns

3

The

cos

functions return cos

x

.

7.12.4.6 The

sin

functions

Synopsis

1

#include <math.h>

double sin(double x);

float sinf(float x);

long double sinl(long double x);

Description

2

The

sin

functions compute the sine of

x

(measured in radians).

Returns

3

The

sin

functions return sin

x

.

7.12.4.7 The

tan

functions

Synopsis

1

#include <math.h>

double tan(double x);

float tanf(float x);

long double tanl(long double x);

Description

2

The

tan

functions return the tangent of

x

(measured in radians).

Returns

3

The

tan

functions return tan

x

.

220 Library

§7.12.4.7

7.12.5 Hyperbolic functions

7.12.5.1 The

acosh

functions

Synopsis

1

#include <math.h>

double acosh(double x);

float acoshf(float x);

long double acoshl(long double x);

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,

+

∞

].

7.12.5.2 The

asinh

functions

Synopsis

1

#include <math.h>

double asinh(double x);

float asinhf(float x);

long double asinhl(long double x);

Description

2

The

asinh

functions compute the arc hyperbolic sine of

x

.

Returns

3

The

asinh

functions return arsinh

x

.

7.12.5.3 The

atanh

functions

Synopsis

1

#include <math.h>

double atanh(double x);

float atanhf(float x);

long double atanhl(long double x);

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 range error may occur if the argument

equals −1 or +1.

§7.12.5.3 Library

221

Returns

3

The

atanh

functions return artanh

x

.

7.12.5.4 The

cosh

functions

Synopsis

1

#include <math.h>

double cosh(double x);

float coshf(float x);

long double coshl(long double x);

Description

2

The

cosh

functions compute the hyperbolic cosine of

x

. A range error occurs if the

magnitude of

x

is too large.

Returns

3

The

cosh

functions return cosh

x

.

7.12.5.5 The

sinh

functions

Synopsis

1

#include <math.h>

double sinh(double x);

float sinhf(float x);

long double sinhl(long double x);

Description

2

The

sinh

functions compute the hyperbolic sine of

x

. A range error occurs if the

magnitude of

x

is too large.

Returns

3

The

sinh

functions return sinh

x

.

7.12.5.6 The

tanh

functions

Synopsis

1

#include <math.h>

double tanh(double x);

float tanhf(float x);

long double tanhl(long double x);

Description

2

The

tanh

functions compute the hyperbolic tangent of

x

.

222 Library

§7.12.5.6

Returns

3

The

tanh

functions return tanh

x

.

7.12.6 Exponential and logarithmic functions

7.12.6.1 The

exp

functions

Synopsis

1

#include <math.h>

double exp(double x);

float expf(float x);

long double expl(long double x);

Description

2

The

exp

functions compute the base-e exponential of

x

. A range error occurs if the

magnitude of

x

is too large.

Returns

3

The

exp

functions return e

x

.

7.12.6.2 The

exp2

functions

Synopsis

1

#include <math.h>

double exp2(double x);

float exp2f(float x);

long double exp2l(long double x);

Description

2

The

exp2

functions compute the base-2 exponential of

x

. A range error occurs if the

magnitude of

x

is too large.

Returns

3

The

exp2

functions return 2

x

.

7.12.6.3 The

expm1

functions

Synopsis

1

#include <math.h>

double expm1(double x);

float expm1f(float x);

long double expm1l(long double x);

§7.12.6.3 Library

223

Description

2

The

expm1

functions compute the base-e exponential of the argument, minus 1. A range

error occurs if

x

is too large.

208)

Returns

3

The

expm1

functions return e

x

−

1.

7.12.6.4 The

frexp

functions

Synopsis

1

#include <math.h>

double frexp(double value, int *exp);

float frexpf(float value, int *exp);

long double frexpl(long double value, int *exp);

Description

2

The

frexp

functions break a floating-point number into a normalized fraction and an

integral power of 2. They store the integer in the

int

object pointed to by

exp

.

Returns

3

If

value

is not a floating-point number, the results are unspecified. Otherwise, the

frexp

functions return the value

x

, such that

x

has a magnitude in the interval [1/2, 1) or

zero, and

value

equals

x

×

2

*exp

. If

value

is zero, both parts of the result are zero.

7.12.6.5 The

ilogb

functions

Synopsis

1

#include <math.h>

int ilogb(double x);

int ilogbf(float x);

int ilogbl(long double x);

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 casting 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.

208) For small magnitude

x

,

expm1(x)

is expected to be more accurate than

exp(x) - 1

.

224 Library

§7.12.6.5

Returns

3

The

ilogb

functions return the exponent of

x

as a signed

int

value.

Forward references: the

logb

functions (7.12.6.11).

7.12.6.6 The

ldexp

functions

Synopsis

1

#include <math.h>

double ldexp(double x, int exp);

float ldexpf(float x, int exp);

long double ldexpl(long double x, int exp);

Description

2

The

ldexp

functions multiply a floating-point number by an integral power of 2. A

range error may occur.

Returns

3

The

ldexp

functions return

x

×

2

exp

.

7.12.6.7 The

log

functions

Synopsis

1

#include <math.h>

double log(double x);

float logf(float x);

long double logl(long double x);

Description

2

The

log

functions compute the base-e (natural) logarithm of

x

. A domain error occurs if

the argument is negative. A range error may occur if the argument is zero.

Returns

3

The

log

functions return log

e

x

.

7.12.6.8 The

log10

functions

Synopsis

1

#include <math.h>

double log10(double x);

float log10f(float x);

long double log10l(long double x);

§7.12.6.8 Library

225

Description

2

The

log10

functions compute the base-10 (common) logarithm of

x

. A domain error

occurs if the argument is negative. A range error may occur if the argument is zero.

Returns

3

The

log10

functions return log

10

x

.

7.12.6.9 The

log1p

functions

Synopsis

1

#include <math.h>

double log1p(double x);

float log1pf(float x);

long double log1pl(long double x);

Description

2

The

log1p

functions compute the base-e (natural) logarithm of 1 plus the argument.

209)

A domain error occurs if the argument is less than −1. A range error may occur if the
argument equals −1.

Returns

3

The

log1p

functions return log

e

(1

+

x

).

7.12.6.10 The

log2

functions

Synopsis

1

#include <math.h>

double log2(double x);

float log2f(float x);

long double log2l(long double x);

Description

2

The

log2

functions compute the base-2 logarithm of

x

. A domain error occurs if the

argument is less than zero. A range error may occur if the argument is zero.

Returns

3

The

log2

functions return log

2

x

.

209) For small magnitude

x

,

log1p(x)

is expected to be more accurate than

log(1 + x)

.

226 Library

§7.12.6.10

7.12.6.11 The

logb

functions

Synopsis

1

#include <math.h>

double logb(double x);

float logbf(float x);

long double logbl(long double x);

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

×

FLT_RADIX

−

logb

(

x

)

<

FLT_RADIX

A domain error or range error may occur if the argument is zero.

Returns

3

The

logb

functions return the signed exponent of

x

.

7.12.6.12 The

modf

functions

Synopsis

1

#include <math.h>

double modf(double value, double *iptr);

float modff(float value, float *iptr);

long double modfl(long double value, long double *iptr);

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

.

§7.12.6.12 Library

227

7.12.6.13 The

scalbn

and

scalbln

functions

Synopsis

1

#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);

Description

2

The

scalbn

and

scalbln

functions compute

x

×

FLT_RADIX

n

efficiently, not

normally by computing

FLT_RADIX

n

explicitly. A range error may occur.

Returns

3

The

scalbn

and

scalbln

functions return

x

×

FLT_RADIX

n

.

7.12.7 Power and absolute-value functions

7.12.7.1 The

cbrt

functions

Synopsis

1

#include <math.h>

double cbrt(double x);

float cbrtf(float x);

long double cbrtl(long double x);

Description

2

The

cbrt

functions compute the real cube root of

x

.

Returns

3

The

cbrt

functions return

x

1/3

.

7.12.7.2 The

fabs

functions

Synopsis

1

#include <math.h>

double fabs(double x);

float fabsf(float x);

long double fabsl(long double x);

Description

2

The

fabs

functions compute the absolute value of a floating-point number

x

.

228 Library

§7.12.7.2

Returns

3

The

fabs

functions return |

x

|.

7.12.7.3 The

hypot

functions

Synopsis

1

#include <math.h>

double hypot(double x, double y);

float hypotf(float x, float y);

long double hypotl(long double x, long double y);

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 may occur.

3

Returns

4

The

hypot

functions return

√ 

x

2

+

y

2

.

7.12.7.4 The

pow

functions

Synopsis

1

#include <math.h>

double pow(double x, double y);

float powf(float x, float y);

long double powl(long double x, long double y);

Description

2

The

pow

functions compute

x

raised to the power

y

. A domain error occurs if

x

is finite

and negative and

y

is finite and not an integer value. A range error may occur. A domain

error may occur if

x

is zero and

y

is zero. A domain error or range error may occur if

x

is zero and

y

is less than zero.

Returns

3

The

pow

functions return

x

y

.

7.12.7.5 The

sqrt

functions

Synopsis

1

#include <math.h>

double sqrt(double x);

float sqrtf(float x);

long double sqrtl(long double x);

§7.12.7.5 Library

229