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

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

7.12.8.1 The

erf

functions

Synopsis

1

#include <math.h>

double erf(double x);

float erff(float x);

long double erfl(long double x);

Description

2

The

erf

functions compute the error function of

x

.

Returns

3

The

erf

functions return erf

x

=

2

√ 

π

∫

x

0

e

−

t

2

dt.

7.12.8.2 The

erfc

functions

Synopsis

1

#include <math.h>

double erfc(double x);

float erfcf(float x);

long double erfcl(long double x);

Description

2

The

erfc

functions compute the complementary error function of

x

. A range error

occurs if

x

is too large.

Returns

3

The

erfc

functions return erfc

x

=

1

−

erf

x

=

2

√ 

π

∫

∞

x

e

−

t

2

dt.

230 Library

§7.12.8.2

7.12.8.3 The

lgamma

functions

Synopsis

1

#include <math.h>

double lgamma(double x);

float lgammaf(float x);

long double lgammal(long double x);

Description

2

The

lgamma

functions compute the natural logarithm of the absolute value of gamma of

x

. A range error occurs if

x

is too large. A range error may occur if

x

is a negative

integer or zero.

Returns

3

The

lgamma

functions return log

e

|

Γ

(

x

) |.

7.12.8.4 The

tgamma

functions

Synopsis

1

#include <math.h>

double tgamma(double x);

float tgammaf(float x);

long double tgammal(long double x);

Description

2

The

tgamma

functions compute the gamma function of

x

. A domain error or range error

may occur if

x

is a negative integer or zero. A range error may occur if the magnitude of

x

is too large or too small.

Returns

3

The

tgamma

functions return

Γ

(

x

).

7.12.9 Nearest integer functions

7.12.9.1 The

ceil

functions

Synopsis

1

#include <math.h>

double ceil(double x);

float ceilf(float x);

long double ceill(long double x);

Description

2

The

ceil

functions compute the smallest integer value not less than

x

.

§7.12.9.1 Library

231

Returns

3

The

ceil

functions return



x



, expressed as a floating-point number.

7.12.9.2 The

floor

functions

Synopsis

1

#include <math.h>

double floor(double x);

float floorf(float x);

long double floorl(long double x);

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.

7.12.9.3 The

nearbyint

functions

Synopsis

1

#include <math.h>

double nearbyint(double x);

float nearbyintf(float x);

long double nearbyintl(long double x);

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.

7.12.9.4 The

rint

functions

Synopsis

1

#include <math.h>

double rint(double x);

float rintf(float x);

long double rintl(long double x);

Description

2

The

rint

functions differ from the

nearbyint

functions (7.12.9.3) only in that the

rint

functions may raise the ‘‘inexact’’ floating-point exception if the result differs in

value from the argument.

232 Library

§7.12.9.4

Returns

3

The

rint

functions return the rounded integer value.

7.12.9.5 The

lrint

and

llrint

functions

Synopsis

1

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

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.

7.12.9.6 The

round

functions

Synopsis

1

#include <math.h>

double round(double x);

float roundf(float x);

long double roundl(long double x);

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.

§7.12.9.6 Library

233

7.12.9.7 The

lround

and

llround

functions

Synopsis

1

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

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.

7.12.9.8 The

trunc

functions

Synopsis

1

#include <math.h>

double trunc(double x);

float truncf(float x);

long double truncl(long double x);

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.

234 Library

§7.12.9.8

7.12.10 Remainder functions

7.12.10.1 The

fmod

functions

Synopsis

1

#include <math.h>

double fmod(double x, double y);

float fmodf(float x, float y);

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

Description

2

The

fmod

functions compute the floating-point remainder of

x

/

y

.

Returns

3

The

fmod

functions return the value

x

−

n

y

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

7.12.10.2 The

remainder

functions

Synopsis

1

#include <math.h>

double remainder(double x, double y);

float remainderf(float x, float y);

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

Description

2

The

remainder

functions compute the remainder

x

REM

y

required by IEC 60559.

210)

Returns

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.

210) ‘‘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 x/y; whenever

| n

−

x/y |

=

1/2, then n is even. Thus, the remainder is always exact. If r

=

0, its sign shall be that of

x.’’ This definition is applicable for all implementations.

§7.12.10.2 Library

235

7.12.10.3 The

remquo

functions

Synopsis

1

#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 2

n

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.

7.12.11 Manipulation functions

7.12.11.1 The

copysign

functions

Synopsis

1

#include <math.h>

double copysign(double x, double y);

float copysignf(float x, float y);

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

Description

2

The

copysign

functions produce a value with the magnitude of

x

and the sign of

y

.

They produce a NaN (with the sign of

y

) if

x

is a NaN. On implementations that

represent a signed zero but do not treat negative zero consistently in arithmetic
operations, the

copysign

functions 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

.

236 Library

§7.12.11.1

7.12.11.2 The

nan

functions

Synopsis

1

#include <math.h>

double nan(const char *tagp);

float nanf(const char *tagp);

long double nanl(const char *tagp);

Description

2

The call

nan("

n-char-sequence

")

is equivalent to

strtod("NAN(

n-char-

sequence

)", (char**) NULL)

;

the call

nan("")

is equivalent to

strtod("NAN()", (char**) NULL)

. If

tagp

does not point to an n-char

sequence or an empty string, the call is equivalent to

strtod("NAN", (char**)

NULL)

. 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 (7.20.1.3).

7.12.11.3 The

nextafter

functions

Synopsis

1

#include <math.h>

double nextafter(double x, double y);

float nextafterf(float x, float y);

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

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.

211)

The

nextafter

functions return

y

if

x

equals

y

. A range error may occur

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

3

The

nextafter

functions return the next representable value in the specified format

after

x

in the direction of

y

.

211) The argument values are converted to the type of the function, even by a macro implementation of the

function.

§7.12.11.3 Library

237

7.12.11.4 The

nexttoward

functions

Synopsis

1

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

Description

2

The

nexttoward

functions are equivalent to the

nextafter

functions except that the

second parameter has type

long double

and the functions return

y

converted to the

type of the function if

x

equals

y

.

212)

7.12.12 Maximum, minimum, and positive difference functions

7.12.12.1 The

fdim

functions

Synopsis

1

#include <math.h>

double fdim(double x, double y);

float fdimf(float x, float y);

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

Description

2

The

fdim

functions determine the positive difference between their arguments:







x

−

y

+

0

if

x

>

y

if

x

≤

y

A range error may occur.

Returns

3

The

fdim

functions return the positive difference value.

7.12.12.2 The

fmax

functions

Synopsis

1

#include <math.h>

double fmax(double x, double y);

float fmaxf(float x, float y);

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

212) 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.

238 Library

§7.12.12.2

Description

2

The

fmax

functions determine the maximum numeric value of their arguments.

213)

Returns

3

The

fmax

functions return the maximum numeric value of their arguments.

7.12.12.3 The

fmin

functions

Synopsis

1

#include <math.h>

double fmin(double x, double y);

float fminf(float x, float y);

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

Description

2

The

fmin

functions determine the minimum numeric value of their arguments.

214)

Returns

3

The

fmin

functions return the minimum numeric value of their arguments.

7.12.13 Floating multiply-add

7.12.13.1 The

fma

functions

Synopsis

1

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

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

Returns

3

The

fma

functions return (

x

×

y

)

+

z

, rounded as one ternary operation.

213) NaN arguments are treated as missing data: if one argument is a NaN and the other numeric, then the

fmax

functions choose the numeric value. See F.9.9.2.

214) The

fmin

functions are analogous to the

fmax

functions in their treatment of NaNs.

§7.12.13.1 Library

239

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

215)

The following

subclauses provide macros that are quiet (non floating-point exception raising) versions
of the relational operators, and other comparison macros that facilitate writing efficient
code that accounts for 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.

7.12.14.1 The

isgreater

macro

Synopsis

1

#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

argument. The value of

isgreater(x, y)

is always equal to

(x) > (y)

; howev er,

unlike

(x) > (y)

,

isgreater(x, y)

does not raise the ‘‘invalid’’ floating-point

exception when

x

and

y

are unordered.

Returns

3

The

isgreater

macro returns the value of

(x) > (y)

.

7.12.14.2 The

isgreaterequal

macro

Synopsis

1

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

; howev er, unlike

(x) >= (y)

,

isgreaterequal(x, y)

does

not raise the ‘‘invalid’’ floating-point exception when

x

and

y

are unordered.

215) 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.

240 Library

§7.12.14.2

Returns

3

The

isgreaterequal

macro returns the value of

(x) >= (y)

.

7.12.14.3 The

isless

macro

Synopsis

1

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

; howev er,

unlike

(x) < (y)

,

isless(x, y)

does not raise the ‘‘invalid’’ floating-point

exception when

x

and

y

are unordered.

Returns

3

The

isless

macro returns the value of

(x) < (y)

.

7.12.14.4 The

islessequal

macro

Synopsis

1

#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 second argument. The value of

islessequal(x, y)

is always equal to

(x) <= (y)

; howev er, unlike

(x) <= (y)

,

islessequal(x, y)

does not raise

the ‘‘invalid’’ floating-point exception when

x

and

y

are unordered.

Returns

3

The

islessequal

macro returns the value of

(x) <= (y)

.

7.12.14.5 The

islessgreater

macro

Synopsis

1

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

; howev er,

islessgreater(x, y)

does not raise

the ‘‘invalid’’ floating-point exception when

x

and

y

are unordered (nor does it evaluate

x

and

y

twice).

§7.12.14.5 Library

241

Returns

3

The

islessgreater

macro returns the value of

(x) < (y) || (x) > (y)

.

7.12.14.6 The

isunordered

macro

Synopsis

1

#include <math.h>

int isunordered(

real-floating

x,

real-floating

y);

Description

2

The

isunordered

macro determines whether its arguments are unordered.

Returns

3

The

isunordered

macro returns 1 if its arguments are unordered and 0 otherwise.

242 Library

§7.12.14.6

7.13 Nonlocal 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.

216)

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

7.13.1.1 The

setjmp

macro

Synopsis

1

#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

216) These functions are useful for dealing with unusual conditions encountered in a low-level function of

a program.

§7.13.1.1 Library

243

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

7.13.2.1 The

longjmp

function

Synopsis

1

#include <setjmp.h>

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 function containing

the invocation of the

setjmp

macro has terminated execution

217)

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.

3

All accessible objects have values, and all other components of the abstract machine

218)

have state, as of the time the

longjmp

function was called, except that the values 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 are

indeterminate.

Returns

4

After

longjmp

is completed, program 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.

217) 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.

218) This includes, but is not limited to, the floating-point status flags and the state of open files.

244 Library

§7.13.2.1

#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.13.2.1 Library

245

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,

219)

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.

219) See ‘‘future library directions’’ (7.26.9). The names of the signal numbers reflect the following terms

(respectively): abort, floating-point exception, illegal instruction, interrupt, segmentation violation,
and termination.

246 Library

§7.14

7.14.1 Specify signal handling

7.14.1.1 The

signal

function

Synopsis

1

#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), is called a signal
handler.

3

When a signal occurs and

func

points to a function, it is implementation-defined

whether the equivalent 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 storage duration
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, 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

value of

errno

is indeterminate.

220)

6

At program startup, the equivalent of

signal(sig, SIG_IGN);

220) If any signal is generated by an asynchronous signal handler, the behavior is undefined.

§7.14.1.1 Library

247

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

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 (7.20.4.1), the

exit

function (7.20.4.3), the

_Exit

function (7.20.4.4).

7.14.2 Send signal

7.14.2.1 The

raise

function

Synopsis

1

#include <signal.h>

int raise(int sig);

Description

2

The

raise

function carries out the actions described in 7.14.1.1 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.

248 Library

§7.14.2.1

7.15 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. As
described in 6.9.1, its parameter list contains one or more parameters. The rightmost
parameter plays a special role in the access mechanism, and will be designated parmN in
this description.

3

The type declared is

va_list

which is an 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

value of

ap

in the calling function is indeterminate and shall be passed to the

va_end

macro prior to any further reference to

ap

.

221)

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

7.15.1.1 The

va_arg

macro

Synopsis

1

#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

221) It is permitted to create a pointer to a

va_list

and pass that pointer to another function, in which

case the original function may make further use of the original list after the other function returns.

§7.15.1.1 Library

249

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 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 there is no actual next argument, or 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:

— 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 void and the other is a pointer to a character type.

Returns

3

The first invocation of the

va_arg

macro after that of the

va_start

macro returns the

value of the argument after that specified by parmN . Successive inv ocations return the
values of the remaining arguments in succession.

7.15.1.2 The

va_copy

macro

Synopsis

1

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

7.15.1.3 The

va_end

macro

Synopsis

1

#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

250 Library

§7.15.1.3

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.

7.15.1.4 The

va_start

macro

Synopsis

1

#include <stdarg.h>

void va_start(va_list ap,

parmN

);

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

The parameter parmN is the identifier of the rightmost parameter in the variable
parameter list in the function definition (the one just before the

, ...

). If the parameter

parmN is declared with the

register

storage class, with a function or array type, or

with a type that is not compatible with the type that results after application of the default
argument promotions, the behavior is undefined.

Returns

5

The

va_start

macro returns no value.

6

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;

§7.15.1.4 Library

251

if (n_ptrs > MAXARGS)

n_ptrs = MAXARGS;

va_start(ap, n_ptrs);

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, ...);

7

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, f4_after);

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

}

252 Library

§7.15.1.4

7.16 Boolean type and values

<stdbool.h>

1

The header

<stdbool.h>

defines four macros.

2

The macro

bool

expands to

_Bool

.

3

The remaining three macros are suitable for use in

#if

preprocessing directives. They

are

true

which expands to the integer constant 1,

false

which expands to the integer constant 0, and

_ _bool_true_false_are_defined

which expands to the integer constant 1.

4

Notwithstanding the provisions of 7.1.3, a program may undefine and perhaps then
redefine the macros

bool

,

true

, and

false

.

222)

222) See ‘‘future library directions’’ (7.26.7).

§7.16 Library

253

7.17 Common definitions

<stddef.h>

1

The following types and macros are defined in the standard header

<stddef.h>

. Some

are also defined in other headers, as noted in their respective subclauses.

2

The types are

ptrdiff_t

which is the signed integer type of the result of subtracting two pointers;

size_t

which is the unsigned integer type of the result of the

sizeof

operator; and

wchar_t

which is an integer type whose range of values can represent distinct codes for all
members of the largest extended character set specified among the supported locales; the
null character shall have the code value zero. Each member of the basic character set
shall have a code value equal to its value when used as the lone character in an integer
character constant if an implementation does not define

_ _STDC_MB_MIGHT_NEQ_WC_ _

.

3

The macros are

NULL

which expands to an implementation-defined null pointer constant; and

offsetof(

type

,

member-designator

)

which expands to an integer constant expression that has type

size_t

, the value of

which is the offset in bytes, to the structure member (designated by member-designator),
from the beginning of its structure (designated by type). The type and member designator
shall be such that given

static

type

t;

then the expression

&(t.

member-designator

)

evaluates to an address constant. (If the

specified member is a bit-field, the behavior is undefined.)

Recommended practice

4

The types used for

size_t

and

ptrdiff_t

should not have an integer conversion rank

greater than that of

signed long int

unless the implementation supports objects

large enough to make this necessary.

Forward references: localization (7.11).

254 Library

§7.17

7.18 Integer types

<stdint.h>

1

The header

<stdint.h>

declares sets of integer types having specified widths, and

defines corresponding sets of macros.

223)

It also defines macros that specify limits of

integer types corresponding to types defined in other standard headers.

2

Types are defined in the following categories:

— integer types having certain exact widths;

— integer types having at least certain specified widths;

— fastest integer types having at least certain specified widths;

— integer types wide enough to hold pointers to objects;

— integer types having greatest width.

(Some of these types may denote the same type.)

3

Corresponding macros specify limits of the declared types and construct suitable
constants.

4

For each type described herein that the implementation provides,

224)

<stdint.h>

shall

declare that typedef name and define the associated macros. Conversely, for each type
described herein that the implementation does not provide,

<stdint.h>

shall not

declare that typedef name nor shall it define the associated macros. An implementation
shall provide those types described as ‘‘required’’, but need not provide any of the others
(described as ‘‘optional’’).

7.18.1 Integer types

1

When typedef names differing only in the absence or presence of the initial

u

are defined,

they shall denote corresponding signed and unsigned types as described in 6.2.5; an
implementation providing one of these corresponding types shall also provide the other.

2

In the following descriptions, the symbol N represents an unsigned decimal integer with
no leading zeros (e.g., 8 or 24, but not 04 or 048).

223) See ‘‘future library directions’’ (7.26.8).

224) Some of these types may denote implementation-defined extended integer types.

§7.18.1 Library

255

7.18.1.1 Exact-width integer types

1

The typedef name

int

N

_t

designates a signed integer type with width N , no padding

bits, and a two’s complement representation. Thus,

int8_t

denotes a signed integer

type with a width of exactly 8 bits.

2

The typedef name

uint

N

_t

designates an unsigned integer type with width N . Thus,

uint24_t

denotes an unsigned integer type with a width of exactly 24 bits.

3

These types are optional. However, if an implementation provides integer types with
widths of 8, 16, 32, or 64 bits, no padding bits, and (for the signed types) that have a
two’s complement representation, it shall define the corresponding typedef names.

7.18.1.2 Minimum-width integer types

1

The typedef name

int_least

N

_t

designates a signed integer type with a width of at

least N , such that no signed integer type with lesser size has at least the specified width.
Thus,

int_least32_t

denotes a signed integer type with a width of at least 32 bits.

2

The typedef name

uint_least

N

_t

designates an unsigned integer type with a width

of at least N , such that no unsigned integer type with lesser size has at least the specified
width. Thus,

uint_least16_t

denotes an unsigned integer type with a width of at

least 16 bits.

3

The following types are required:

int_least8_t

int_least16_t

int_least32_t

int_least64_t

uint_least8_t

uint_least16_t

uint_least32_t

uint_least64_t

All other types of this form are optional.

7.18.1.3 Fastest minimum-width integer types

1

Each of the following types designates an integer type that is usually fastest

225)

to operate

with among all integer types that have at least the specified width.

2

The typedef name

int_fast

N

_t

designates the fastest signed integer type with a width

of at least N . The typedef name

uint_fast

N

_t

designates the fastest unsigned integer

type with a width of at least N .

225) The designated type is not guaranteed to be fastest for all purposes; if the implementation has no clear

grounds for choosing one type over another, it will simply pick some integer type satisfying the
signedness and width requirements.

256 Library

§7.18.1.3

3

The following types are required:

int_fast8_t

int_fast16_t

int_fast32_t

int_fast64_t

uint_fast8_t

uint_fast16_t

uint_fast32_t

uint_fast64_t

All other types of this form are optional.

7.18.1.4 Integer types capable of holding object pointers

1

The following type designates a signed integer type with the property that any valid
pointer to

void

can be converted to this type, then converted back to pointer to

void

,

and the result will compare equal to the original pointer:

intptr_t

The following type designates an unsigned integer type with the property that any valid
pointer to

void

can be converted to this type, then converted back to pointer to

void

,

and the result will compare equal to the original pointer:

uintptr_t

These types are optional.

7.18.1.5 Greatest-width integer types

1

The following type designates a signed integer type capable of representing any value of
any signed integer type:

intmax_t

The following type designates an unsigned integer type capable of representing any value
of any unsigned integer type:

uintmax_t

These types are required.

7.18.2 Limits of specified-width integer types

1

The following object-like macros

226)

specify the minimum and maximum limits of the

types declared in

<stdint.h>

. Each macro name corresponds to a similar type name in

7.18.1.

2

Each instance of any defined macro shall be replaced by a constant expression suitable
for use in

#if

preprocessing directives, and this expression shall have the same type as

would an expression that is an object of the corresponding type converted according to

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

_ _STDC_LIMIT_MACROS

is defined

before

<stdint.h>

is included.

§7.18.2 Library

257

the integer promotions. Its implementation-defined value shall be equal to or greater in
magnitude (absolute value) than the corresponding value given below, with the same sign,
except where stated to be exactly the given value.

7.18.2.1 Limits of exact-width integer types

1

— minimum values of exact-width signed integer types

INT

N

_MIN

exactly

−

(2

N

−

1

)

— maximum values of exact-width signed integer types

INT

N

_MAX

exactly 2

N

−

1

−

1

— maximum values of exact-width unsigned integer types

UINT

N

_MAX

exactly 2

N

−

1

7.18.2.2 Limits of minimum-width integer types

1

— minimum values of minimum-width signed integer types

INT_LEAST

N

_MIN

−

(2

N

−

1

−

1)

— maximum values of minimum-width signed integer types

INT_LEAST

N

_MAX

2

N

−

1

−

1

— maximum values of minimum-width unsigned integer types

UINT_LEAST

N

_MAX

2

N

−

1

7.18.2.3 Limits of fastest minimum-width integer types

1

— minimum values of fastest minimum-width signed integer types

INT_FAST

N

_MIN

−

(2

N

−

1

−

1)

— maximum values of fastest minimum-width signed integer types

INT_FAST

N

_MAX

2

N

−

1

−

1

— maximum values of fastest minimum-width unsigned integer types

UINT_FAST

N

_MAX

2

N

−

1

7.18.2.4 Limits of integer types capable of holding object pointers

1

— minimum value of pointer-holding signed integer type

INTPTR_MIN

−

(2

15

−

1)

— maximum value of pointer-holding signed integer type

INTPTR_MAX

2

15

−

1

258 Library

§7.18.2.4

— maximum value of pointer-holding unsigned integer type

UINTPTR_MAX

2

16

−

1

7.18.2.5 Limits of greatest-width integer types

1

— minimum value of greatest-width signed integer type

INTMAX_MIN

−

(2

63

−

1)

— maximum value of greatest-width signed integer type

INTMAX_MAX

2

63

−

1

— maximum value of greatest-width unsigned integer type

UINTMAX_MAX

2

64

−

1

7.18.3 Limits of other integer types

1

The following object-like macros

227)

specify the minimum and maximum limits of

integer types corresponding to types defined in other standard headers.

2

Each instance of these macros shall be replaced by a constant expression suitable for use
in

#if

preprocessing directives, and this expression shall have the same type as would an

expression that is an object of the corresponding type converted according to the integer
promotions. Its implementation-defined value shall be equal to or greater in magnitude
(absolute value) than the corresponding value given below, with the same sign. An
implementation shall define only the macros corresponding to those typedef names it
actually provides.

228)

— limits of

ptrdiff_t

PTRDIFF_MIN −65535

PTRDIFF_MAX +65535

— limits of

sig_atomic_t

SIG_ATOMIC_MIN

see below

SIG_ATOMIC_MAX

see below

— limit of

size_t

SIZE_MAX 65535

— limits of

wchar_t

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

_ _STDC_LIMIT_MACROS

is defined

before

<stdint.h>

is included.

228) A freestanding implementation need not provide all of these types.

§7.18.3 Library

259

WCHAR_MIN

see below

WCHAR_MAX

see below

— limits of

wint_t

WINT_MIN

see below

WINT_MAX

see below

3

If

sig_atomic_t

(see 7.14) is defined as a signed integer type, the value of

SIG_ATOMIC_MIN

shall be no greater than −127 and the value of

SIG_ATOMIC_MAX

shall be no less than 127; otherwise,

sig_atomic_t

is defined as an unsigned integer

type, and the value of

SIG_ATOMIC_MIN

shall be 0 and the value of

SIG_ATOMIC_MAX

shall be no less than 255.

4

If

wchar_t

(see 7.17) is defined as a signed integer type, the value of

WCHAR_MIN

shall be no greater than −127 and the value of

WCHAR_MAX

shall be no less than 127;

otherwise,

wchar_t

is defined as an unsigned integer type, and the value of

WCHAR_MIN

shall be 0 and the value of

WCHAR_MAX

shall be no less than 255.

229)

5

If

wint_t

(see 7.24) is defined as a signed integer type, the value of

WINT_MIN

shall

be no greater than −32767 and the value of

WINT_MAX

shall be no less than 32767;

otherwise,

wint_t

is defined as an unsigned integer type, and the value of

WINT_MIN

shall be 0 and the value of

WINT_MAX

shall be no less than 65535.

7.18.4 Macros for integer constants

1

The following function-like macros

230)

expand to integer constants suitable for

initializing objects that have integer types corresponding to types defined in

<stdint.h>

. Each macro name corresponds to a similar type name in 7.18.1.2 or

7.18.1.5.

2

The argument in any instance of these macros shall be an unsuffixed integer constant (as
defined in 6.4.4.1) with a value that does not exceed the limits for the corresponding type.

3

Each invocation of one of these macros shall expand to an integer constant expression
suitable for use in

#if

preprocessing directives. The type of the expression shall have

the same type as would an expression of the corresponding type converted according to
the integer promotions. The value of the expression shall be that of the argument.

229) The values

WCHAR_MIN

and

WCHAR_MAX

do not necessarily correspond to members of the extended

character set.

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

_ _STDC_CONSTANT_MACROS

is

defined before

<stdint.h>

is included.

260 Library

§7.18.4

7.18.4.1 Macros for minimum-width integer constants

1

The macro

INT

N

_C(

value

)

shall expand to an integer constant expression

corresponding to the type

int_least

N

_t

. The macro

UINT

N

_C(

value

)

shall expand

to an integer constant expression corresponding to the type

uint_least

N

_t

. For

example, if

uint_least64_t

is a name for the type

unsigned long long int

,

then

UINT64_C(0x123)

might expand to the integer constant

0x123ULL

.

7.18.4.2 Macros for greatest-width integer constants

1

The following macro expands to an integer constant expression having the value specified
by its argument and the type

intmax_t

:

INTMAX_C(

value

)

The following macro expands to an integer constant expression having the value specified
by its argument and the type

uintmax_t

:

UINTMAX_C(

value

)

§7.18.4.2 Library

261