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

printf("x" "1" "= %d, x" "2" "= %s", x1, x2);

fputs(

"strncmp(\"abc\\0d\", \"abc\", '\\4') == 0" ": @\n",

s);

#include "vers2.h"

(after macro replacement, before file access)

"hello";

"hello" ", world"

or, after concatenation of the character string literals,

printf("x1= %d, x2= %s", x1, x2);

fputs(

"strncmp(\"abc\\0d\", \"abc\", '\\4') == 0: @\n",

s);

#include "vers2.h"

(after macro replacement, before file access)

"hello";

"hello, world"

Space around the

and

tokens in the macro definition is optional.

EXAMPLE 5

To illustrate the rules for placemarker preprocessing tokens, the sequence

#define t(x,y,z) x ## y ## z

int j[] = { t(1,2,3), t(,4,5), t(6,,7), t(8,9,),

t(10,,), t(,11,), t(,,12), t(,,) };

results in

int j[] = { 123, 45, 67, 89,

10, 11, 12,

};

EXAMPLE 6

To demonstrate the redefinition rules, the following sequence is valid.

#define OBJ_LIKE

(1-1)

#define OBJ_LIKE

white space

*/ (1-1) /*

other

#define FUNC_LIKE(a)

( a )

#define FUNC_LIKE( a )( /*

note the white space

*/ \

a /*

other stuff on this line

*/ )

But the following redefinitions are invalid:

#define OBJ_LIKE

(0) //

different token sequence

#define OBJ_LIKE

(1 - 1) //

different white space

#define FUNC_LIKE(b) ( a )

different parameter usage

#define FUNC_LIKE(b) ( b )

different parameter spelling

EXAMPLE 7

Finally, to show the variable argument list macro facilities:

#define debug(...)

fprintf(stderr, _ _VA_ARGS_ _)

#define showlist(...)

puts(#_ _VA_ARGS_ _)

#define report(test, ...) ((test)?puts(#test):\

printf(_ _VA_ARGS_ _))

debug("Flag");

debug("X = %d\n", x);

showlist(The first, second, and third items.);

report(x>y, "x is %d but y is %d", x, y);

§6.10.3.5 Language

157

results in

fprintf(stderr, "Flag" );

fprintf(stderr, "X = %d\n", x );

puts( "The first, second, and third items." );

((x>y)?puts("x>y"):

printf("x is %d but y is %d", x, y));

6.10.4 Line control

Constraints

The string literal of a

#line

directive, if present, shall be a character string literal.

Semantics

The line number of the current source line is one greater than the number of new-line
characters read or introduced in translation phase 1 (5.1.1.2) while processing the source
file to the current token.

A preprocessing directive of the form

# line

digit-sequence new-line

causes the implementation to behave as if the following sequence of source lines begins
with a source line that has a line number as specified by the digit sequence (interpreted as
a decimal integer). The digit sequence shall not specify zero, nor a number greater than
2147483647.

A preprocessing directive of the form

# line

digit-sequence

s-char-sequence

opt

new-line

sets the presumed line number similarly and changes the presumed name of the source
file to be the contents of the character string literal.

A preprocessing directive of the form

# line

pp-tokens new-line

(that does not match one of the two previous forms) is permitted. The preprocessing
tokens after

line

on the directive are processed just as in normal text (each identifier

currently defined as a macro name is replaced by its replacement list of preprocessing
tokens). The directive resulting after all replacements shall match one of the two
previous forms and is then processed as appropriate.

158 Language

§6.10.4

6.10.5 Error directive

Semantics

A preprocessing directive of the form

# error

pp-tokens

opt

new-line

causes the implementation to produce a diagnostic message that includes the specified
sequence of preprocessing tokens.

6.10.6 Pragma directive

Semantics

A preprocessing directive of the form

# pragma

pp-tokens

opt

new-line

where the preprocessing token

STDC

does not immediately follow

pragma

in the

directive (prior to any macro replacement)

152)

causes the implementation to behave in an

implementation-defined manner. The behavior might cause translation to fail or cause the
translator or the resulting program to behave in a non-conforming manner. Any such

pragma

that is not recognized by the implementation is ignored.

If the preprocessing token

STDC

does immediately follow

pragma

in the directive (prior

to any macro replacement), then no macro replacement is performed on the directive, and
the directive shall have one of the following forms

153)

whose meanings are described

elsewhere:

#pragma STDC FP_CONTRACT

on-off-switch

#pragma STDC FENV_ACCESS

on-off-switch

#pragma STDC CX_LIMITED_RANGE

on-off-switch

on-off-switch: one of

ON OFF

DEFAULT

Forward references: the

FP_CONTRACT

pragma (7.12.2), the

FENV_ACCESS

pragma

(7.6.1), the

CX_LIMITED_RANGE

pragma (7.3.4).

152) An implementation is not required to perform macro replacement in pragmas, but it is permitted

except for in standard pragmas (where

STDC

immediately follows

pragma

). If the result of macro

replacement in a non-standard pragma has the same form as a standard pragma, the behavior is still
implementation-defined; an implementation is permitted to behave as if it were the standard pragma,
but is not required to.

153) See ‘‘future language directions’’ (6.11.8).

§6.10.6 Language

159

6.10.7 Null directive

Semantics

A preprocessing directive of the form

new-line

has no effect.

6.10.8 Predefined macro names

The following macro names

154)

shall be defined by the implementation:

_ _DATE_ _

The date of translation of the preprocessing translation unit: a character
string literal of the form

"Mmm dd yyyy"

, where the names of the

months are the same as those generated by the

asctime

function, and the

first character of

is a space character if the value is less than 10. If the

date of translation is not available, an implementation-defined valid date
shall be supplied.

_ _FILE_ _

The presumed name of the current source file (a character string literal).

155)

_ _LINE_ _

The presumed line number (within the current source file) of the current
source line (an integer constant).

155)

_ _STDC_ _

The integer constant

, intended to indicate a conforming implementation.

_ _STDC_HOSTED_ _

The integer constant

if the implementation is a hosted

implementation or the integer constant

if it is not.

_ _STDC_MB_MIGHT_NEQ_WC_ _

The integer constant

, intended to indicate that, in

the encoding for

wchar_t

, a member of the basic character set need not

have a code value equal to its value when used as the lone character in an
integer character constant.

_ _STDC_VERSION_ _

The integer constant

199901L

156)

_ _TIME_ _

The time of translation of the preprocessing translation unit: a character
string literal of the form

"hh:mm:ss"

as in the time generated by the

asctime

function. If the time of translation is not available, an

implementation-defined valid time shall be supplied.

154) See ‘‘future language directions’’ (6.11.9).

155) The presumed source file name and line number can be changed by the

#line

directive.

156) This macro was not specified in ISO/IEC 9899:1990 and was specified as

199409L

ISO/IEC 9899/AMD1:1995. The intention is that this will remain an integer constant of type

long

int

that is increased with each revision of this International Standard.

160 Language

§6.10.8

The following macro names are conditionally defined by the implementation:

_ _STDC_IEC_559_ _

The integer constant

, intended to indicate conformance to the

specifications in annex F (IEC 60559 floating-point arithmetic).

_ _STDC_IEC_559_COMPLEX_ _

The integer constant

, intended to indicate

adherence to the specifications in informative annex G (IEC 60559
compatible complex arithmetic).

_ _STDC_ISO_10646_ _

An integer constant of the form

yyyymmL

(for example,

199712L

). If this symbol is defined, then every character in the Unicode

required set, when stored in an object of type

wchar_t

, has the same

value as the short identifier of that character. The Unicode required set
consists of all the characters that are defined by ISO/IEC 10646, along with
all amendments and technical corrigenda, as of the specified year and
month.

The values of the predefined macros (except for

_ _FILE_ _

and

_ _LINE_ _

) remain

constant throughout the translation unit.

None of these macro names, nor the identifier

defined

, shall be the subject of a

#define

or a

#undef

preprocessing directive. Any other predefined macro names

shall begin with a leading underscore followed by an uppercase letter or a second
underscore.

The implementation shall not predefine the macro

_ _cplusplus

, nor shall it define it

in any standard header.

Forward references: the

asctime

function (7.23.3.1), standard headers (7.1.2).

6.10.9 Pragma operator

Semantics

A unary operator expression of the form:

_Pragma (

string-literal

)

is processed as follows: The string literal is destringized by deleting the

prefix, if

present, deleting the leading and trailing double-quotes, replacing each escape sequence

by a double-quote, and replacing each escape sequence

by a single backslash. The

resulting sequence of characters is processed through translation phase 3 to produce
preprocessing tokens that are executed as if they were the pp-tokens in a pragma
directive. The original four preprocessing tokens in the unary operator expression are
removed.

EXAMPLE A directive of the form:

#pragma listing on "..\listing.dir"

can also be expressed as:

§6.10.9 Language

161

6.11 Future language directions

6.11.1 Floating types

Future standardization may include additional floating-point types, including those with
greater range, precision, or both than

long double

6.11.2 Linkages of identifiers

Declaring an identifier with internal linkage at file scope without the

static

storage-

class specifier is an obsolescent feature.

6.11.3 External names

Restriction of the significance of an external name to fewer than 255 characters
(considering each universal character name or extended source character as a single
character) is an obsolescent feature that is a concession to existing implementations.

6.11.4 Character escape sequences

Lowercase letters as escape sequences are reserved for future standardization. Other
characters may be used in extensions.

6.11.5 Storage-class specifiers

The placement of a storage-class specifier other than at the beginning of the declaration
specifiers in a declaration is an obsolescent feature.

6.11.6 Function declarators

The use of function declarators with empty parentheses (not prototype-format parameter
type declarators) is an obsolescent feature.

6.11.7 Function definitions

The use of function definitions with separate parameter identifier and declaration lists
(not prototype-format parameter type and identifier declarators) is an obsolescent feature.

6.11.8 Pragma directives

Pragmas whose first preprocessing token is

STDC

are reserved for future standardization.

6.11.9 Predefined macro names

Macro names beginning with

_ _STDC_

are reserved for future standardization.

§6.11.9 Language

163

7. Library

7.1 Introduction

7.1.1 Definitions of terms

A string is a contiguous sequence of characters terminated by and including the first null
character. The term multibyte string is sometimes used instead to emphasize special
processing given to multibyte characters contained in the string or to avoid confusion
with a wide string. A pointer to a string is a pointer to its initial (lowest addressed)
character. The length of a string is the number of bytes preceding the null character and
the value of a string is the sequence of the values of the contained characters, in order.

The decimal-point character is the character used by functions that convert floating-point
numbers to or from character sequences to denote the beginning of the fractional part of
such character sequences.

157)

It is represented in the text and examples by a period, but

may be changed by the

setlocale

function.

A null wide character is a wide character with code value zero.

A wide string is a contiguous sequence of wide characters terminated by and including
the first null wide character. A pointer to a wide string is a pointer to its initial (lowest
addressed) wide character. The length of a wide string is the number of wide characters
preceding the null wide character and the value of a wide string is the sequence of code
values of the contained wide characters, in order.

A shift sequence is a contiguous sequence of bytes within a multibyte string that
(potentially) causes a change in shift state (see 5.2.1.2). A shift sequence shall not have a
corresponding wide character; it is instead taken to be an adjunct to an adjacent multibyte
character.

158)

Forward references: character handling (7.4), the

setlocale

function (7.11.1.1).

157) The functions that make use of the decimal-point character are the numeric conversion functions

(7.20.1, 7.24.4.1) and the formatted input/output functions (7.19.6, 7.24.2).

158) For state-dependent encodings, the values for

MB_CUR_MAX

and

MB_LEN_MAX

shall thus be large

enough to count all the bytes in any complete multibyte character plus at least one adjacent shift
sequence of maximum length. Whether these counts provide for more than one shift sequence is the
implementation’s choice.

164 Library

§7.1.1

7.1.2 Standard headers

Each library function is declared, with a type that includes a prototype, in a header,

159)

whose contents are made available by the

#include

preprocessing directive. The

header declares a set of related functions, plus any necessary types and additional macros
needed to facilitate their use. Declarations of types described in this clause shall not
include type qualifiers, unless explicitly stated otherwise.

The standard headers are

<assert.h>

<complex.h>

<ctype.h>

<errno.h>

<fenv.h>

<float.h>

<inttypes.h>

<iso646.h>

<limits.h>

<locale.h>

<math.h>

<setjmp.h>

<signal.h>

<stdarg.h>

<stdbool.h>

<stddef.h>

<stdint.h>

<stdio.h>

<stdlib.h>

<string.h>

<tgmath.h>

<time.h>

<wchar.h>

<wctype.h>

If a file with the same name as one of the above

and

delimited sequences, not

provided as part of the implementation, is placed in any of the standard places that are
searched for included source files, the behavior is undefined.

Standard headers may be included in any order; each may be included more than once in
a giv en scope, with no effect different from being included only once, except that the
effect of including

<assert.h>

depends on the definition of

NDEBUG

(see 7.2). If

used, a header shall be included outside of any external declaration or definition, and it
shall first be included before the first reference to any of the functions or objects it
declares, or to any of the types or macros it defines. However, if an identifier is declared
or defined in more than one header, the second and subsequent associated headers may be
included after the initial reference to the identifier. The program shall not have any
macros with names lexically identical to keywords currently defined prior to the
inclusion.

Any definition of an object-like macro described in this clause shall expand to code that is
fully protected by parentheses where necessary, so that it groups in an arbitrary
expression as if it were a single identifier.

Any declaration of a library function shall have external linkage.

A summary of the contents of the standard headers is given in annex B.

Forward references: diagnostics (7.2).

159) A header is not necessarily a source file, nor are the

and

delimited sequences in header names

necessarily valid source file names.

§7.1.2 Library

165

7.1.3 Reserved identifiers

Each header declares or defines all identifiers listed in its associated subclause, and
optionally declares or defines identifiers listed in its associated future library directions
subclause and identifiers which are always reserved either for any use or for use as file
scope identifiers.

— All identifiers that begin with an underscore and either an uppercase letter or another

underscore are always reserved for any use.

— All identifiers that begin with an underscore are always reserved for use as identifiers

with file scope in both the ordinary and tag name spaces.

— Each macro name in any of the following subclauses (including the future library

directions) is reserved for use as specified if any of its associated headers is included;
unless explicitly stated otherwise (see 7.1.4).

— All identifiers with external linkage in any of the following subclauses (including the

future library directions) are always reserved for use as identifiers with external
linkage.

160)

— Each identifier with file scope listed in any of the following subclauses (including the

future library directions) is reserved for use as a macro name and as an identifier with
file scope in the same name space if any of its associated headers is included.

No other identifiers are reserved. If the program declares or defines an identifier in a
context in which it is reserved (other than as allowed by 7.1.4), or defines a reserved
identifier as a macro name, the behavior is undefined.

If the program removes (with

#undef

) any macro definition of an identifier in the first

group listed above, the behavior is undefined.

7.1.4 Use of library functions

Each of the following statements applies unless explicitly stated otherwise in the detailed
descriptions that follow: If an argument to a function has an invalid value (such as a value
outside the domain of the function, or a pointer outside the address space of the program,
or a null pointer, or a pointer to non-modifiable storage when the corresponding
parameter is not const-qualified) or a type (after promotion) not expected by a function
with variable number of arguments, the behavior is undefined. If a function argument is
described as being an array, the pointer actually passed to the function shall have a value
such that all address computations and accesses to objects (that would be valid if the
pointer did point to the first element of such an array) are in fact valid. Any function
declared in a header may be additionally implemented as a function-like macro defined in

160) The list of reserved identifiers with external linkage includes

errno

math_errhandling

setjmp

, and

va_end

166 Library

§7.1.4

the header, so if a library function is declared explicitly when its header is included, one
of the techniques shown below can be used to ensure the declaration is not affected by
such a macro. Any macro definition of a function can be suppressed locally by enclosing
the name of the function in parentheses, because the name is then not followed by the left
parenthesis that indicates expansion of a macro function name. For the same syntactic
reason, it is permitted to take the address of a library function even if it is also defined as
a macro.

161)

The use of

#undef

to remove any macro definition will also ensure that an

actual function is referred to. Any inv ocation of a library function that is implemented as
a macro shall expand to code that evaluates each of its arguments exactly once, fully
protected by parentheses where necessary, so it is generally safe to use arbitrary
expressions as arguments.

162)

Likewise, those function-like macros described in the

following subclauses may be invoked in an expression anywhere a function with a
compatible return type could be called.

163)

All object-like macros listed as expanding to

integer constant expressions shall additionally be suitable for use in

#if

preprocessing

directives.

Provided that a library function can be declared without reference to any type defined in a
header, it is also permissible to declare the function and use it without including its
associated header.

There is a sequence point immediately before a library function returns.

The functions in the standard library are not guaranteed to be reentrant and may modify
objects with static storage duration.

164)

161) This means that an implementation shall provide an actual function for each library function, even if it

also provides a macro for that function.

162) Such macros might not contain the sequence points that the corresponding function calls do.

163) Because external identifiers and some macro names beginning with an underscore are reserved,

implementations may provide special semantics for such names. For example, the identifier

_BUILTIN_abs

could be used to indicate generation of in-line code for the

abs

function. Thus, the

appropriate header could specify

#define abs(x) _BUILTIN_abs(x)

for a compiler whose code generator will accept it.

In this manner, a user desiring to guarantee that a given library function such as

abs

will be a genuine

function may write

#undef abs

whether the implementation’s header provides a macro implementation of

abs

or a built-in

implementation. The prototype for the function, which precedes and is hidden by any macro
definition, is thereby revealed also.

164) Thus, a signal handler cannot, in general, call standard library functions.

§7.1.4 Library

167

EXAMPLE The function

atoi

may be used in any of sev eral ways:

— by use of its associated header (possibly generating a macro expansion)

#include <stdlib.h>

const char *str;

...

i = atoi(str);

— by use of its associated header (assuredly generating a true function reference)

#include <stdlib.h>

#undef atoi

const char *str;

...

i = atoi(str);

#include <stdlib.h>

const char *str;

...

i = (atoi)(str);

— by explicit declaration

extern int atoi(const char *);

const char *str;

...

i = atoi(str);

168 Library

§7.1.4

7.2 Diagnostics

<assert.h>

The header

<assert.h>

defines the

assert

macro and refers to another macro,

NDEBUG

which is not defined by

<assert.h>

. If

NDEBUG

is defined as a macro name at the

point in the source file where

<assert.h>

is included, the

assert

macro is defined

simply as

#define assert(ignore) ((void)0)

The

assert

macro is redefined according to the current state of

NDEBUG

each time that

<assert.h>

is included.

The

assert

macro shall be implemented as a macro, not as an actual function. If the

macro definition is suppressed in order to access an actual function, the behavior is
undefined.

7.2.1 Program diagnostics

7.2.1.1 The

assert

macro

Synopsis

#include <assert.h>

void assert(

scalar

expression);

Description

The

assert

macro puts diagnostic tests into programs; it expands to a void expression.

When it is executed, if

expression

(which shall have a scalar type) is false (that is,

compares equal to 0), the

assert

macro writes information about the particular call that

failed (including the text of the argument, the name of the source file, the source line
number, and the name of the enclosing function — the latter are respectively the values of
the preprocessing macros

_ _FILE_ _

and

_ _LINE_ _

and of the identifier

_ _func_ _

) on the standard error stream in an implementation-defined format.

165)

then calls the

abort

function.

Returns

The

assert

macro returns no value.

Forward references: the

abort

function (7.20.4.1).

165) The message written might be of the form:

Assertion failed:

expression

, function

abc

, file

xyz

, line

nnn

§7.2.1.1 Library

169

7.3 Complex arithmetic

<complex.h>

7.3.1 Introduction

The header

<complex.h>

defines macros and declares functions that support complex

arithmetic.

166)

Each synopsis specifies a family of functions consisting of a principal

function with one or more

double complex

parameters and a

double complex

double

return value; and other functions with the same name but with

and

suffixes

which are corresponding functions with

float

and

long double

parameters and

return values.

The macro

complex

expands to

_Complex

; the macro

_Complex_I

expands to a constant expression of type

const float _Complex

, with the value of

the imaginary unit.

167)

The macros

imaginary

and

_Imaginary_I

are defined if and only if the implementation supports imaginary types;

168)

if defined,

they expand to

_Imaginary

and a constant expression of type

const float

_Imaginary

with the value of the imaginary unit.

The macro

expands to either

_Imaginary_I

_Complex_I

. If

_Imaginary_I

is not

defined,

shall expand to

_Complex_I

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

complex

imaginary

, and

Forward references: IEC 60559-compatible complex arithmetic (annex G).

166) See ‘‘future library directions’’ (7.26.1).

167) The imaginary unit is a number i such that

= −

168) A specification for imaginary types is in informative annex G.

170 Library

§7.3.1

7.3.2 Conventions

Values are interpreted as radians, not degrees. An implementation may set

errno

but is

not required to.

7.3.3 Branch cuts

Some of the functions below hav e branch cuts, across which the function is
discontinuous. For implementations with a signed zero (including all IEC 60559
implementations) that follow the specifications of annex G, the sign of zero distinguishes
one side of a cut from another so the function is continuous (except for format
limitations) as the cut is approached from either side. For example, for the square root
function, which has a branch cut along the negative real axis, the top of the cut, with
imaginary part +0, maps to the positive imaginary axis, and the bottom of the cut, with
imaginary part −0, maps to the negative imaginary axis.

Implementations that do not support a signed zero (see annex F) cannot distinguish the
sides of branch cuts. These implementations shall map a cut so the function is continuous
as the cut is approached coming around the finite endpoint of the cut in a counter
clockwise direction. (Branch cuts for the functions specified here have just one finite
endpoint.) For example, for the square root function, coming counter clockwise around
the finite endpoint of the cut along the negative real axis approaches the cut from above,
so the cut maps to the positive imaginary axis.

7.3.4 The

CX_LIMITED_RANGE

pragma

Synopsis

#include <complex.h>

#pragma STDC CX_LIMITED_RANGE

on-off-switch

Description

The usual mathematical formulas for complex multiply, divide, and absolute value are
problematic because of their treatment of infinities and because of undue overflow and
underflow. The

CX_LIMITED_RANGE

pragma can be used to inform the

implementation that (where the state is ‘‘on’’) the usual mathematical formulas are
acceptable.

169)

The pragma can occur either outside external declarations or preceding all

explicit declarations and statements inside a compound statement. When outside external

169) The purpose of the pragma is to allow the implementation to use the formulas:

iy)

iv)

(xu

−

yv)

i(yu

xv)

iy) / (u

iv)

[(xu

yv)

i(yu

−

xv)]/(u

)

| x

iy |

√ 

where the programmer can determine they are safe.

§7.3.4 Library

171

declarations, the pragma takes effect from its occurrence until another

CX_LIMITED_RANGE

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

CX_LIMITED_RANGE

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 for the pragma is ‘‘off’’.

7.3.5 Trigonometric functions

7.3.5.1 The

cacos

functions

Synopsis

#include <complex.h>

double complex cacos(double complex z);

float complex cacosf(float complex z);

long double complex cacosl(long double complex z);

Description

The

cacos

functions compute the complex arc cosine of

, with branch cuts outside the

interval [

−

1] along the real axis.

Returns

The

cacos

functions return the complex arc cosine value, in the range of a strip

mathematically unbounded along the imaginary axis and in the interval [0,

] along the

real axis.

7.3.5.2 The

casin

functions

Synopsis

#include <complex.h>

double complex casin(double complex z);

float complex casinf(float complex z);

long double complex casinl(long double complex z);

Description

The

casin

functions compute the complex arc sine of

, with branch cuts outside the

interval [

−

1] along the real axis.

Returns

The

casin

functions return the complex arc sine value, in the range of a strip

mathematically unbounded along the imaginary axis and in the interval [

−

/2,

/2]

along the real axis.

172 Library

§7.3.5.2

7.3.5.3 The

catan

functions

Synopsis

#include <complex.h>

double complex catan(double complex z);

float complex catanf(float complex z);

long double complex catanl(long double complex z);

Description

The

catan

functions compute the complex arc tangent of

, with branch cuts outside the

interval [

−

i] along the imaginary axis.

Returns

The

catan

functions return the complex arc tangent value, in the range of a strip

mathematically unbounded along the imaginary axis and in the interval [

−

/2,

/2]

along the real axis.

7.3.5.4 The

ccos

functions

Synopsis

#include <complex.h>

double complex ccos(double complex z);

float complex ccosf(float complex z);

long double complex ccosl(long double complex z);

Description

The

ccos

functions compute the complex cosine of

Returns

The

ccos

functions return the complex cosine value.

7.3.5.5 The

csin

functions

Synopsis

#include <complex.h>

double complex csin(double complex z);

float complex csinf(float complex z);

long double complex csinl(long double complex z);

Description

The

csin

functions compute the complex sine of

Returns

The

csin

functions return the complex sine value.

§7.3.5.5 Library

173

7.3.5.6 The

ctan

functions

Synopsis

#include <complex.h>

double complex ctan(double complex z);

float complex ctanf(float complex z);

long double complex ctanl(long double complex z);

Description

The

ctan

functions compute the complex tangent of

Returns

The

ctan

functions return the complex tangent value.

7.3.6 Hyperbolic functions

7.3.6.1 The

cacosh

functions

Synopsis

#include <complex.h>

double complex cacosh(double complex z);

float complex cacoshf(float complex z);

long double complex cacoshl(long double complex z);

Description

The

cacosh

functions compute the complex arc hyperbolic cosine of

, with a branch

cut at values less than 1 along the real axis.

Returns

The

cacosh

functions return the complex arc hyperbolic cosine value, in the range of a

half-strip of non-negative values along the real axis and in the interval [

−

] along

the imaginary axis.

7.3.6.2 The

casinh

functions

Synopsis

#include <complex.h>

double complex casinh(double complex z);

float complex casinhf(float complex z);

long double complex casinhl(long double complex z);

Description

The

casinh

functions compute the complex arc hyperbolic sine of

, with branch cuts

outside the interval [

−

i] along the imaginary axis.

174 Library

§7.3.6.2

Returns

The

casinh

functions return the complex arc hyperbolic sine value, in the range of a

strip mathematically unbounded along the real axis and in the interval [

−

/2,

/2]

along the imaginary axis.

7.3.6.3 The

catanh

functions

Synopsis

#include <complex.h>

double complex catanh(double complex z);

float complex catanhf(float complex z);

long double complex catanhl(long double complex z);

Description

The

catanh

functions compute the complex arc hyperbolic tangent of

, with branch

cuts outside the interval [

−

1] along the real axis.

Returns

The

catanh

functions return the complex arc hyperbolic tangent value, in the range of a

strip mathematically unbounded along the real axis and in the interval [

−

/2,

/2]

along the imaginary axis.

7.3.6.4 The

ccosh

functions

Synopsis

#include <complex.h>

double complex ccosh(double complex z);

float complex ccoshf(float complex z);

long double complex ccoshl(long double complex z);

Description

The

ccosh

functions compute the complex hyperbolic cosine of

Returns

The

ccosh

functions return the complex hyperbolic cosine value.

7.3.6.5 The

csinh

functions

Synopsis

#include <complex.h>

double complex csinh(double complex z);

float complex csinhf(float complex z);

long double complex csinhl(long double complex z);

§7.3.6.5 Library

175

Description

The

csinh

functions compute the complex hyperbolic sine of

Returns

The

csinh

functions return the complex hyperbolic sine value.

7.3.6.6 The

ctanh

functions

Synopsis

#include <complex.h>

double complex ctanh(double complex z);

float complex ctanhf(float complex z);

long double complex ctanhl(long double complex z);

Description

The

ctanh

functions compute the complex hyperbolic tangent of

Returns

The

ctanh

functions return the complex hyperbolic tangent value.

7.3.7 Exponential and logarithmic functions

7.3.7.1 The

cexp

functions

Synopsis

#include <complex.h>

double complex cexp(double complex z);

float complex cexpf(float complex z);

long double complex cexpl(long double complex z);

Description

The

cexp

functions compute the complex base-e exponential of

Returns

The

cexp

functions return the complex base-e exponential value.

7.3.7.2 The

clog

functions

Synopsis

#include <complex.h>

double complex clog(double complex z);

float complex clogf(float complex z);

long double complex clogl(long double complex z);

176 Library

§7.3.7.2

Description

The

clog

functions compute the complex natural (base-e) logarithm of

, with a branch

cut along the negative real axis.

Returns

The

clog

functions return the complex natural logarithm value, in the range of a strip

mathematically unbounded along the real axis and in the interval [

−

] along the

imaginary axis.

7.3.8 Power and absolute-value functions

7.3.8.1 The

cabs

functions

Synopsis

#include <complex.h>

double cabs(double complex z);

float cabsf(float complex z);

long double cabsl(long double complex z);

Description

The

cabs

functions compute the complex absolute value (also called norm, modulus, or

magnitude) of

Returns

The

cabs

functions return the complex absolute value.

7.3.8.2 The

cpow

functions

Synopsis

#include <complex.h>

double complex cpow(double complex x, double complex y);

float complex cpowf(float complex x, float complex y);

long double complex cpowl(long double complex x,

long double complex y);

Description

The

cpow

functions compute the complex power function

, with a branch cut for the

first parameter along the negative real axis.

Returns

The

cpow

functions return the complex power function value.

§7.3.8.2 Library

177

7.3.8.3 The

csqrt

functions

Synopsis

#include <complex.h>

double complex csqrt(double complex z);

float complex csqrtf(float complex z);

long double complex csqrtl(long double complex z);

Description

The

csqrt

functions compute the complex square root of

, with a branch cut along the

negative real axis.

Returns

The

csqrt

functions return the complex square root value, in the range of the right half-

plane (including the imaginary axis).

7.3.9 Manipulation functions

7.3.9.1 The

carg

functions

Synopsis

#include <complex.h>

double carg(double complex z);

float cargf(float complex z);

long double cargl(long double complex z);

Description

The

carg

functions compute the argument (also called phase angle) of

, with a branch

cut along the negative real axis.

Returns

The

carg

functions return the value of the argument in the interval [

−

7.3.9.2 The

cimag

functions

Synopsis

#include <complex.h>

double cimag(double complex z);

float cimagf(float complex z);

long double cimagl(long double complex z);

178 Library

§7.3.9.2

Description

The

cimag

functions compute the imaginary part of

170)

Returns

The

cimag

functions return the imaginary part value (as a real).

7.3.9.3 The

conj

functions

Synopsis

#include <complex.h>

double complex conj(double complex z);

float complex conjf(float complex z);

long double complex conjl(long double complex z);

Description

The

conj

functions compute the complex conjugate of

, by rev ersing the sign of its

imaginary part.

Returns

The

conj

functions return the complex conjugate value.

7.3.9.4 The

cproj

functions

Synopsis

#include <complex.h>

double complex cproj(double complex z);

float complex cprojf(float complex z);

long double complex cprojl(long double complex z);

Description

The

cproj

functions compute a projection of

onto the Riemann sphere:

projects to

except that all complex infinities (even those with one infinite part and one NaN part)

project to positive infinity on the real axis. If

has an infinite part, then

cproj(z)

equivalent to

INFINITY + I * copysign(0.0, cimag(z))

Returns

The

cproj

functions return the value of the projection onto the Riemann sphere.

170) For a variable

of complex type,

z == creal(z) + cimag(z)*I

§7.3.9.4 Library

179

7.3.9.5 The

creal

functions

Synopsis

#include <complex.h>

double creal(double complex z);

float crealf(float complex z);

long double creall(long double complex z);

Description

The

creal

functions compute the real part of

171)

Returns

The

creal

functions return the real part value.

171) For a variable

of complex type,

z == creal(z) + cimag(z)*I

180 Library

§7.3.9.5

7.4 Character handling

<ctype.h>

The header

<ctype.h>

declares several functions useful for classifying and mapping

characters.

172)

In all cases the argument is an

int

, the value of which shall be

representable as an

unsigned char

or shall equal the value of the macro

EOF

. If the

argument has any other value, the behavior is undefined.

The behavior of these functions is affected by the current locale. Those functions that
have locale-specific aspects only when not in the

"C"

locale are noted below.

The term printing character refers to a member of a locale-specific set of characters, each
of which occupies one printing position on a display device; the term control character
refers to a member of a locale-specific set of characters that are not printing
characters.

173)

All letters and digits are printing characters.

Forward references:

EOF

(7.19.1), localization (7.11).

7.4.1 Character classification functions

The functions in this subclause return nonzero (true) if and only if the value of the
argument

conforms to that in the description of the function.

7.4.1.1 The

isalnum

function

Synopsis

#include <ctype.h>

int isalnum(int c);

Description

The

isalnum

function tests for any character for which

isalpha

isdigit

is true.

7.4.1.2 The

isalpha

function

Synopsis

#include <ctype.h>

int isalpha(int c);

Description

The

isalpha

function tests for any character for which

isupper

islower

is true,

or any character that is one of a locale-specific set of alphabetic characters for which

172) See ‘‘future library directions’’ (7.26.2).

173) In an implementation that uses the seven-bit US ASCII character set, the printing characters are those

whose values lie from 0x20 (space) through 0x7E (tilde); the control characters are those whose
values lie from 0 (NUL) through 0x1F (US), and the character 0x7F (DEL).

§7.4.1.2 Library

181

none of

iscntrl

isdigit

ispunct

, or

isspace

is true.

174)

In the

"C"

locale,

isalpha

returns true only for the characters for which

isupper

islower

is true.

7.4.1.3 The

isblank

function

Synopsis

#include <ctype.h>

int isblank(int c);

Description

The

isblank

function tests for any character that is a standard blank character or is one

of a locale-specific set of characters for which

isspace

is true and that is used to

separate words within a line of text. The standard blank characters are the following:
space (

' '

), and horizontal tab (

'\t'

). In the

"C"

locale,

isblank

returns true only

for the standard blank characters.

7.4.1.4 The

iscntrl

function

Synopsis

#include <ctype.h>

int iscntrl(int c);

Description

The

iscntrl

function tests for any control character.

7.4.1.5 The

isdigit

function

Synopsis

#include <ctype.h>

int isdigit(int c);

Description

The

isdigit

function tests for any decimal-digit character (as defined in 5.2.1).

7.4.1.6 The

isgraph

function

Synopsis

#include <ctype.h>

int isgraph(int c);

174) The functions

islower

and

isupper

test true or false separately for each of these additional

characters; all four combinations are possible.

182 Library

§7.4.1.6

Description

The

isgraph

function tests for any printing character except space (

' '

7.4.1.7 The

islower

function

Synopsis

#include <ctype.h>

int islower(int c);

Description

The

islower

function tests for any character that is a lowercase letter or is one of a

locale-specific set of characters for which none of

iscntrl

isdigit

ispunct

, or

isspace

is true. In the

"C"

locale,

islower

returns true only for the lowercase

letters (as defined in 5.2.1).

7.4.1.8 The

isprint

function

Synopsis

#include <ctype.h>

int isprint(int c);

Description

The

isprint

function tests for any printing character including space (

' '

7.4.1.9 The

ispunct

function

Synopsis

#include <ctype.h>

int ispunct(int c);

Description

The

ispunct

function tests for any printing character that is one of a locale-specific set

of punctuation characters for which neither

isspace

nor

isalnum

is true. In the

"C"

locale,

ispunct

returns true for every printing character for which neither

isspace

nor

isalnum

is true.

7.4.1.10 The

isspace

function

Synopsis

#include <ctype.h>

int isspace(int c);

Description

The

isspace

function tests for any character that is a standard white-space character or

is one of a locale-specific set of characters for which

isalnum

is false. The standard

§7.4.1.10 Library

183

white-space characters are the following: space (

' '

), form feed (

'\f'

), new-line

(

'\n'

), carriage return (

'\r'

), horizontal tab (

'\t'

), and vertical tab (

'\v'

). In the

"C"

locale,

isspace

returns true only for the standard white-space characters.

7.4.1.11 The

isupper

function

Synopsis

#include <ctype.h>

int isupper(int c);

Description

The

isupper

function tests for any character that is an uppercase letter or is one of a

locale-specific set of characters for which none of

iscntrl

isdigit

ispunct

, or

isspace

is true. In the

"C"

locale,

isupper

returns true only for the uppercase

letters (as defined in 5.2.1).

7.4.1.12 The

isxdigit

function

Synopsis

#include <ctype.h>

int isxdigit(int c);

Description

The

isxdigit

function tests for any hexadecimal-digit character (as defined in 6.4.4.1).

7.4.2 Character case mapping functions

7.4.2.1 The

tolower

function

Synopsis

#include <ctype.h>

int tolower(int c);

Description

The

tolower

function converts an uppercase letter to a corresponding lowercase letter.

Returns

If the argument is a character for which

isupper

is true and there are one or more

corresponding characters, as specified by the current locale, for which

islower

is true,

the

tolower

function returns one of the corresponding characters (always the same one

for any giv en locale); otherwise, the argument is returned unchanged.

184 Library

§7.4.2.1

7.4.2.2 The

toupper

function

Synopsis

#include <ctype.h>

int toupper(int c);

Description

The

toupper

function converts a lowercase letter to a corresponding uppercase letter.

Returns

If the argument is a character for which

islower

is true and there are one or more

corresponding characters, as specified by the current locale, for which

isupper

is true,

the

toupper

function returns one of the corresponding characters (always the same one

for any giv en locale); otherwise, the argument is returned unchanged.

§7.4.2.2 Library

185

7.5 Errors

<errno.h>

The header

<errno.h>

defines several macros, all relating to the reporting of error

conditions.

The macros are

EDOM

EILSEQ

ERANGE

which expand to integer constant expressions with type

int

, distinct positive values, and

which are suitable for use in

#if

preprocessing directives; and

errno

which expands to a modifiable lvalue

175)

that has type

int

, the value of which is set to a

positive error number by several library functions. It is unspecified whether

errno

is a

macro or an identifier declared with external linkage. If a macro definition is suppressed
in order to access an actual object, or a program defines an identifier with the name

errno

, the behavior is undefined.

The value of

errno

is zero at program startup, but is never set to zero by any library

function.

176)

The value of

errno

may be set to nonzero by a library function call

whether or not there is an error, provided the use of

errno

is not documented in the

description of the function in this International Standard.

Additional macro definitions, beginning with

and a digit or

and an uppercase

letter,

177)

may also be specified by the implementation.

175) The macro

errno

need not be the identifier of an object. It might expand to a modifiable lvalue

resulting from a function call (for example,

*errno()

176) Thus, a program that uses

errno

for error checking should set it to zero before a library function call,

then inspect it before a subsequent library function call. Of course, a library function can save the
value of

errno

on entry and then set it to zero, as long as the original value is restored if

errno

’s

value is still zero just before the return.

177) See ‘‘future library directions’’ (7.26.3).

186 Library

§7.5

7.6 Floating-point environment

<fenv.h>

The header

<fenv.h>

declares two types and several macros and functions to provide

access to the floating-point environment. The floating-point environment refers
collectively to any floating-point status flags and control modes supported by the
implementation.

178)

A floating-point status flag is a system variable whose value is set

(but never cleared) when a floating-point exception is raised, which occurs as a side effect
of exceptional floating-point arithmetic to provide auxiliary information.

179)

A floating-

point control mode is a system variable whose value may be set by the user to affect the
subsequent behavior of floating-point arithmetic.

Certain programming conventions support the intended model of use for the floating-
point environment:

180)

— a function call does not alter its caller’s floating-point control modes, clear its caller’s

floating-point status flags, nor depend on the state of its caller’s floating-point status
flags unless the function is so documented;

— a function call is assumed to require default floating-point control modes, unless its

documentation promises otherwise;

— a function call is assumed to have the potential for raising floating-point exceptions,

unless its documentation promises otherwise.

The type

fenv_t

represents the entire floating-point environment.

The type

fexcept_t

represents the floating-point status flags collectively, including any status the
implementation associates with the flags.

178) This header is designed to support the floating-point exception status flags and directed-rounding

control modes required by IEC 60559, and other similar floating-point state information. Also it is
designed to facilitate code portability among all systems.

179) A floating-point status flag is not an object and can be set more than once within an expression.

180) With these conventions, a programmer can safely assume default floating-point control modes (or be

unaware of them). The responsibilities associated with accessing the floating-point environment fall
on the programmer or program that does so explicitly.

§7.6 Library

187

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