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

7.24.6.4.1 The

mbsrtowcs

function

Synopsis

#include <wchar.h>

size_t mbsrtowcs(wchar_t * restrict dst,

const char ** restrict src,

size_t len,

mbstate_t * restrict ps);

Description

The

mbsrtowcs

function converts a sequence of multibyte characters that begins in the

conversion state described by the object pointed to by

, from the array indirectly

pointed to by

src

into a sequence of corresponding wide characters. If

dst

is not a null

pointer, the converted characters are stored into the array pointed to by

dst

. Conversion

continues up to and including a terminating null character, which is also stored.
Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
not form a valid multibyte character, or (if

dst

is not a null pointer) when

len

wide

characters have been stored into the array pointed to by

dst

301)

Each conversion takes

place as if by a call to the

mbrtowc

function.

dst

is not a null pointer, the pointer object pointed to by

src

is assigned either a null

pointer (if conversion stopped due to reaching a terminating null character) or the address
just past the last multibyte character converted (if any). If conversion stopped due to
reaching a terminating null character and if

dst

is not a null pointer, the resulting state

described is the initial conversion state.

Returns

If the input conversion encounters a sequence of bytes that do not form a valid multibyte
character, an encoding error occurs: the

mbsrtowcs

function stores the value of the

macro

EILSEQ

errno

and returns

(size_t)(-1)

; the conversion state is

unspecified. Otherwise, it returns the number of multibyte characters successfully
converted, not including the terminating null character (if any).

301) Thus, the value of

len

is ignored if

dst

is a null pointer.

§7.24.6.4.1 Library

391

Otherwise, if the corresponding real type of either operand is

double

, the other

operand is converted, without change of type domain, to a type whose
corresponding real type is

double

Otherwise, if the corresponding real type of either operand is

float

, the other

operand is converted, without change of type domain, to a type whose
corresponding real type is

float

51)

Otherwise, the integer promotions are performed on both operands. Then the
following rules are applied to the promoted operands:

If both operands have the same type, then no further conversion is needed.

Otherwise, if both operands have signed integer types or both have unsigned
integer types, the operand with the type of lesser integer conversion rank is
converted to the type of the operand with greater rank.

Otherwise, if the operand that has unsigned integer type has rank greater or
equal to the rank of the type of the other operand, then the operand with
signed integer type is converted to the type of the operand with unsigned
integer type.

Otherwise, if the type of the operand with signed integer type can represent
all of the values of the type of the operand with unsigned integer type, then
the operand with unsigned integer type is converted to the type of the
operand with signed integer type.

Otherwise, both operands are converted to the unsigned integer type
corresponding to the type of the operand with signed integer type.

The values of floating operands and of the results of floating expressions may be
represented in greater precision and range than that required by the type; the types are not
changed thereby.

52)

51) For example, addition of a

double _Complex

and a

float

entails just the conversion of the

float

operand to

double

(and yields a

double _Complex

result).

52) The cast and assignment operators are still required to perform their specified conversions as

described in 6.3.1.4 and 6.3.1.5.

§6.3.1.8 Language

6.3.2 Other operands

6.3.2.1 Lvalues, arrays, and function designators

An lvalue is an expression with an object type or an incomplete type other than

void

;

53)

if an lvalue does not designate an object when it is evaluated, the behavior is undefined.
When an object is said to have a particular type, the type is specified by the lvalue used to
designate the object. A modifiable lvalue is an lvalue that does not have array type, does
not have an incomplete type, does not have a const-qualified type, and if it is a structure
or union, does not have any member (including, recursively, any member or element of
all contained aggregates or unions) with a const-qualified type.

Except when it is the operand of the

sizeof

operator, the unary

operator, the

operator, or the left operand of the

operator or an assignment operator,

an lvalue that does not have array type is converted to the value stored in the designated
object (and is no longer an lvalue). If the lvalue has qualified type, the value has the
unqualified version of the type of the lvalue; otherwise, the value has the type of the
lvalue. If the lvalue has an incomplete type and does not have array type, the behavior is
undefined.

Except when it is the operand of the

sizeof

operator or the unary

operator, or is a

string literal used to initialize an array, an expression that has type ‘‘array of type’’ is
converted to an expression with type ‘‘pointer to type’’ that points to the initial element of
the array object and is not an lvalue. If the array object has register storage class, the
behavior is undefined.

A function designator is an expression that has function type. Except when it is the
operand of the

sizeof

operator

54)

or the unary

operator, a function designator with

type ‘‘function returning type’’ is converted to an expression that has type ‘‘pointer to
function returning type’’.

Forward references: address and indirection operators (6.5.3.2), assignment operators
(6.5.16), common definitions

<stddef.h>

(7.17), initialization (6.7.8), postfix

increment and decrement operators (6.5.2.4), prefix increment and decrement operators
(6.5.3.1), the

sizeof

operator (6.5.3.4), structure and union members (6.5.2.3).

53) The name ‘‘lvalue’’ comes originally from the assignment expression

E1 = E2

, in which the left

operand

is required to be a (modifiable) lvalue. It is perhaps better considered as representing an

object ‘‘locator value’’. What is sometimes called ‘‘rvalue’’ is in this International Standard described
as the ‘‘value of an expression’’.

An obvious example of an lvalue is an identifier of an object. As a further example, if

is a unary

expression that is a pointer to an object,

is an lvalue that designates the object to which

points.

54) Because this conversion does not occur, the operand of the

sizeof

operator remains a function

designator and violates the constraint in 6.5.3.4.

46 Language

§6.3.2.1

6.3.2.2

void

The (nonexistent) value of a void expression (an expression that has type

void

) shall not

be used in any way, and implicit or explicit conversions (except to

void

) shall not be

applied to such an expression. If an expression of any other type is evaluated as a void
expression, its value or designator is discarded. (A void expression is evaluated for its
side effects.)

6.3.2.3 Pointers

A pointer to

void

may be converted to or from a pointer to any incomplete or object

type. A pointer to any incomplete or object type may be converted to a pointer to

void

and back again; the result shall compare equal to the original pointer.

For any qualifier q, a pointer to a non-q-qualified type may be converted to a pointer to
the q-qualified version of the type; the values stored in the original and converted pointers
shall compare equal.

An integer constant expression with the value 0, or such an expression cast to type

void *

, is called a null pointer constant.

55)

If a null pointer constant is converted to a

pointer type, the resulting pointer, called a null pointer, is guaranteed to compare unequal
to a pointer to any object or function.

Conversion of a null pointer to another pointer type yields a null pointer of that type.
Any two null pointers shall compare equal.

An integer may be converted to any pointer type. Except as previously specified, the
result is implementation-defined, might not be correctly aligned, might not point to an
entity of the referenced type, and might be a trap representation.

56)

Any pointer type may be converted to an integer type. Except as previously specified, the
result is implementation-defined. If the result cannot be represented in the integer type,
the behavior is undefined. The result need not be in the range of values of any integer
type.

A pointer to an object or incomplete type may be converted to a pointer to a different
object or incomplete type. If the resulting pointer is not correctly aligned

57)

for the

pointed-to type, the behavior is undefined. Otherwise, when converted back again, the
result shall compare equal to the original pointer. When a pointer to an object is

55) The macro

NULL

is defined in

<stddef.h>

(and other headers) as a null pointer constant; see 7.17.

56) The mapping functions for converting a pointer to an integer or an integer to a pointer are intended to

be consistent with the addressing structure of the execution environment.

57) In general, the concept ‘‘correctly aligned’’ is transitive: if a pointer to type A is correctly aligned for a

pointer to type B, which in turn is correctly aligned for a pointer to type C, then a pointer to type A is
correctly aligned for a pointer to type C.

§6.3.2.3 Language

6.4 Lexical elements

Syntax

token:

keyword
identifier
constant
string-literal
punctuator

preprocessing-token:

header-name
identifier
pp-number
character-constant
string-literal
punctuator
each non-white-space character that cannot be one of the above

Constraints

Each preprocessing token that is converted to a token shall have the lexical form of a
keyword, an identifier, a constant, a string literal, or a punctuator.

Semantics

A token is the minimal lexical element of the language in translation phases 7 and 8. The
categories of tokens are: keywords, identifiers, constants, string literals, and punctuators.
A preprocessing token is the minimal lexical element of the language in translation
phases 3 through 6.

The categories of preprocessing tokens are: header names,

identifiers, preprocessing numbers, character constants, string literals, punctuators, and
single non-white-space characters that do not lexically match the other preprocessing
token categories.

58)

If a

or a

character matches the last category, the behavior is

undefined. Preprocessing tokens can be separated by white space; this consists of
comments (described later), or white-space characters (space, horizontal tab, new-line,
vertical tab, and form-feed), or both. As described in 6.10, in certain circumstances
during translation phase 4, white space (or the absence thereof) serves as more than
preprocessing token separation. White space may appear within a preprocessing token
only as part of a header name or between the quotation characters in a character constant
or string literal.

58) An additional category, placemarkers, is used internally in translation phase 4 (see 6.10.3.3); it cannot

occur in source files.

§6.4 Language

If the input stream has been parsed into preprocessing tokens up to a given character, the
next preprocessing token is the longest sequence of characters that could constitute a
preprocessing token. There is one exception to this rule: header name preprocessing
tokens are recognized only within

#include

preprocessing directives and in

implementation-defined locations within

#pragma

directives. In such contexts, a

sequence of characters that could be either a header name or a string literal is recognized
as the former.

EXAMPLE 1

The program fragment

1Ex

is parsed as a preprocessing number token (one that is not a

valid floating or integer constant token), even though a parse as the pair of preprocessing tokens

and

might produce a valid expression (for example, if

were a macro defined as

). Similarly, the program

fragment

1E1

is parsed as a preprocessing number (one that is a valid floating constant token), whether or

not

is a macro name.

EXAMPLE 2

The program fragment

x+++++y

is parsed as

x ++ ++ + y

, which violates a constraint on

increment operators, even though the parse

x ++ + ++ y

might yield a correct expression.

Forward references: character constants (6.4.4.4), comments (6.4.9), expressions (6.5),
floating constants (6.4.4.2), header names (6.4.7), macro replacement (6.10.3), postfix
increment and decrement operators (6.5.2.4), prefix increment and decrement operators
(6.5.3.1), preprocessing directives (6.10), preprocessing numbers (6.4.8), string literals
(6.4.5).

6.4.1 Keywords

Syntax

keyword: one of

auto

break

case

char

const

continue

default

double

else

enum

extern

float

for

goto

inline

int

long

register

restrict

return

short

signed

sizeof

static

struct

switch

typedef

union

unsigned

void

volatile

while

_Bool

_Complex

_Imaginary

Semantics

The above tokens (case sensitive) are reserved (in translation phases 7 and 8) for use as
keywords, and shall not be used otherwise. The keyword

_Imaginary

is reserved for

specifying imaginary types.

59)

59) One possible specification for imaginary types appears in annex G.

50 Language

§6.4.1

6.4.2 Identifiers

6.4.2.1 General

Syntax

identifier:

identifier-nondigit
identifier identifier-nondigit
identifier digit

identifier-nondigit:

nondigit
universal-character-name
other implementation-defined characters

nondigit: one of

digit: one of

Semantics

An identifier is a sequence of nondigit characters (including the underscore

, the

lowercase and uppercase Latin letters, and other characters) and digits, which designates
one or more entities as described in 6.2.1. Lowercase and uppercase letters are distinct.
There is no specific limit on the maximum length of an identifier.

Each universal character name in an identifier shall designate a character whose encoding
in ISO/IEC 10646 falls into one of the ranges specified in annex D.

60)

The initial

character shall not be a universal character name designating a digit. An implementation
may allow multibyte characters that are not part of the basic source character set to
appear in identifiers; which characters and their correspondence to universal character
names is implementation-defined.

When preprocessing tokens are converted to tokens during translation phase 7, if a
preprocessing token could be converted to either a keyword or an identifier, it is converted
to a keyword.

60) On systems in which linkers cannot accept extended characters, an encoding of the universal character

name may be used in forming valid external identifiers. For example, some otherwise unused
character or sequence of characters may be used to encode the

in a universal character name.

Extended characters may produce a long external identifier.

§6.4.2.1 Language

Implementation limits

As discussed in 5.2.4.1, an implementation may limit the number of significant initial
characters in an identifier; the limit for an external name (an identifier that has external
linkage) may be more restrictive than that for an internal name (a macro name or an
identifier that does not have external linkage). The number of significant characters in an
identifier is implementation-defined.

Any identifiers that differ in a significant character are different identifiers. If two
identifiers differ only in nonsignificant characters, the behavior is undefined.

Forward references: universal character names (6.4.3), macro replacement (6.10.3).

6.4.2.2 Predefined identifiers

Semantics

The identifier

_ _func_ _

shall be implicitly declared by the translator as if,

immediately following the opening brace of each function definition, the declaration

static const char _ _func_ _[] = "

function-name

appeared, where function-name is the name of the lexically-enclosing function.

61)

This name is encoded as if the implicit declaration had been written in the source
character set and then translated into the execution character set as indicated in translation
phase 5.

EXAMPLE Consider the code fragment:

#include <stdio.h>

void myfunc(void)

{

printf("%s\n", _ _func_ _);

...

}

Each time the function is called, it will print to the standard output stream:

myfunc

Forward references: function definitions (6.9.1).

61) Since the name

_ _func_ _

is reserved for any use by the implementation (7.1.3), if any other

identifier is explicitly declared using the name

_ _func_ _

, the behavior is undefined.

52 Language

§6.4.2.2

wide characters for which none of

iswcntrl

iswdigit

iswpunct

, or

iswspace

is true.

305)

7.25.2.1.3 The

iswblank

function

Synopsis

#include <wctype.h>

int iswblank(wint_t wc);

Description

The

iswblank

function tests for any wide character that is a standard blank wide

character or is one of a locale-specific set of wide characters for which

iswspace

is true

and that is used to separate words within a line of text. The standard blank wide
characters are the following: space (

L' '

), and horizontal tab (

L'\t'

). In the

"C"

locale,

iswblank

returns true only for the standard blank characters.

7.25.2.1.4 The

iswcntrl

function

Synopsis

#include <wctype.h>

int iswcntrl(wint_t wc);

Description

The

iswcntrl

function tests for any control wide character.

7.25.2.1.5 The

iswdigit

function

Synopsis

#include <wctype.h>

int iswdigit(wint_t wc);

Description

The

iswdigit

function tests for any wide character that corresponds to a decimal-digit

character (as defined in 5.2.1).

7.25.2.1.6 The

iswgraph

function

Synopsis

#include <wctype.h>

int iswgraph(wint_t wc);

305) The functions

iswlower

and

iswupper

test true or false separately for each of these additional

wide characters; all four combinations are possible.

§7.25.2.1.6 Library

395

6.4.3 Universal character names

Syntax

universal-character-name:

hex-quad

hex-quad hex-quad

hex-quad:

hexadecimal-digit hexadecimal-digit

Constraints

A universal character name shall not specify a character whose short identifier is less than
00A0 other than 0024 (

), 0040 (

), or 0060 (

‘

), nor one in the range D800 through

DFFF inclusive.

62)

Description

Universal character names may be used in identifiers, character constants, and string
literals to designate characters that are not in the basic character set.

Semantics

The universal character name

nnnnnnnn designates the character whose eight-digit

short identifier (as specified by ISO/IEC 10646) is nnnnnnnn.

63)

Similarly, the universal

character name

nnnn designates the character whose four-digit short identifier is nnnn

(and whose eight-digit short identifier is 0000nnnn).

62) The disallowed characters are the characters in the basic character set and the code positions reserved

by ISO/IEC 10646 for control characters, the character DELETE, and the S-zone (reserved for use by
UTF−16).

63) Short identifiers for characters were first specified in ISO/IEC 10646−1/AMD9:1997.

§6.4.3 Language

6.4.4 Constants

Syntax

constant:

integer-constant
floating-constant
enumeration-constant
character-constant

Constraints

Each constant shall have a type and the value of a constant shall be in the range of
representable values for its type.

Semantics

Each constant has a type, determined by its form and value, as detailed later.

6.4.4.1 Integer constants

Syntax

integer-constant:

decimal-constant integer-suffix

opt

octal-constant integer-suffix

opt

hexadecimal-constant integer-suffix

opt

decimal-constant:

nonzero-digit
decimal-constant digit

octal-constant:

octal-constant octal-digit

hexadecimal-constant:

hexadecimal-prefix hexadecimal-digit
hexadecimal-constant hexadecimal-digit

hexadecimal-prefix: one of

0x 0X

nonzero-digit: one of

octal-digit: one of

54 Language

§6.4.4.1

hexadecimal-digit: one of

integer-suffix:

unsigned-suffix long-suffix

opt

unsigned-suffix long-long-suffix
long-suffix unsigned-suffix

opt

long-long-suffix unsigned-suffix

opt

unsigned-suffix: one of

long-suffix: one of

long-long-suffix: one of

ll LL

Description

An integer constant begins with a digit, but has no period or exponent part. It may have a
prefix that specifies its base and a suffix that specifies its type.

A decimal constant begins with a nonzero digit and consists of a sequence of decimal
digits. An octal constant consists of the prefix

optionally followed by a sequence of the

digits

through

only. A hexadecimal constant consists of the prefix

followed

by a sequence of the decimal digits and the letters

(or

) through

(or

) with values

10 through 15 respectively.

Semantics

The value of a decimal constant is computed base 10; that of an octal constant, base 8;
that of a hexadecimal constant, base 16. The lexically first digit is the most significant.

The type of an integer constant is the first of the corresponding list in which its value can
be represented.

§6.4.4.1 Language

Octal or Hexadecimal

Suffix Decimal Constant Constant

int int

long int

unsigned int

long int

unsigned long int

long long int

unsigned long long int

long long int

none

unsigned int

unsigned long int

unsigned long long int

long int

unsigned long int

long long int

unsigned long long int

long long int

Both

unsigned long int

and

unsigned long long int

long long int

unsigned long long int

LL long long int

Both

and

unsigned long long int

If an integer constant cannot be represented by any type in its list, it may have an
extended integer type, if the extended integer type can represent its value. If all of the
types in the list for the constant are signed, the extended integer type shall be signed. If
all of the types in the list for the constant are unsigned, the extended integer type shall be
unsigned. If the list contains both signed and unsigned types, the extended integer type
may be signed or unsigned. If an integer constant cannot be represented by any type in
its list and has no extended integer type, then the integer constant has no type.

56 Language

§6.4.4.1

6.4.4.2 Floating constants

Syntax

floating-constant:

decimal-floating-constant
hexadecimal-floating-constant

decimal-floating-constant:

fractional-constant exponent-part

opt

floating-suffix

opt

digit-sequence exponent-part floating-suffix

opt

hexadecimal-floating-constant:

hexadecimal-prefix hexadecimal-fractional-constant

binary-exponent-part floating-suffix

opt

hexadecimal-prefix hexadecimal-digit-sequence

binary-exponent-part floating-suffix

opt

fractional-constant:

digit-sequence

opt

digit-sequence

exponent-part:

sign

opt

digit-sequence

sign

opt

digit-sequence

sign: one of

digit-sequence:

digit
digit-sequence digit

hexadecimal-fractional-constant:

hexadecimal-digit-sequence

opt

hexadecimal-digit-sequence

binary-exponent-part:

sign

opt

digit-sequence

sign

opt

digit-sequence

hexadecimal-digit-sequence:

hexadecimal-digit
hexadecimal-digit-sequence hexadecimal-digit

floating-suffix: one of

§6.4.4.2 Language

Description

A floating constant has a significand part that may be followed by an exponent part and a
suffix that specifies its type. The components of the significand part may include a digit
sequence representing the whole-number part, followed by a period (

), followed by a

digit sequence representing the fraction part. The components of the exponent part are an

, or

followed by an exponent consisting of an optionally signed digit sequence.

Either the whole-number part or the fraction part has to be present; for decimal floating
constants, either the period or the exponent part has to be present.

Semantics

The significand part is interpreted as a (decimal or hexadecimal) rational number; the
digit sequence in the exponent part is interpreted as a decimal integer. For decimal
floating constants, the exponent indicates the power of 10 by which the significand part is
to be scaled. For hexadecimal floating constants, the exponent indicates the power of 2
by which the significand part is to be scaled. For decimal floating constants, and also for
hexadecimal floating constants when

FLT_RADIX

is not a power of 2, the result is either

the nearest representable value, or the larger or smaller representable value immediately
adjacent to the nearest representable value, chosen in an implementation-defined manner.
For hexadecimal floating constants when

FLT_RADIX

is a power of 2, the result is

correctly rounded.

An unsuffixed floating constant has type

double

. If suffixed by the letter

, it has

type

float

. If suffixed by the letter

, it has type

long double

Floating constants are converted to internal format as if at translation-time. The
conversion of a floating constant shall not raise an exceptional condition or a floating-
point exception at execution time.

Recommended practice

The implementation should produce a diagnostic message if a hexadecimal constant
cannot be represented exactly in its evaluation format; the implementation should then
proceed with the translation of the program.

The translation-time conversion of floating constants should match the execution-time
conversion of character strings by library functions, such as

strtod

, giv en matching

inputs suitable for both conversions, the same result format, and default execution-time
rounding.

64)

64) The specification for the library functions recommends more accurate conversion than required for

floating constants (see 7.20.1.3).

58 Language

§6.4.4.2

6.4.4.3 Enumeration constants

Syntax

enumeration-constant:

identifier

Semantics

An identifier declared as an enumeration constant has type

int

Forward references: enumeration specifiers (6.7.2.2).

6.4.4.4 Character constants

Syntax

character-constant:

c-char-sequence

c-char-sequence:

c-char
c-char-sequence c-char

c-char:

any member of the source character set except

the single-quote

, backslash

, or new-line character

escape-sequence

escape-sequence:

simple-escape-sequence
octal-escape-sequence
hexadecimal-escape-sequence
universal-character-name

simple-escape-sequence: one of

\' \" \? \\

\a \b \f \n \r \t \v

octal-escape-sequence:

octal-digit

octal-digit octal-digit

octal-digit octal-digit octal-digit

hexadecimal-escape-sequence:

hexadecimal-digit

hexadecimal-escape-sequence hexadecimal-digit

§6.4.4.4 Language

Description

An integer character constant is a sequence of one or more multibyte characters enclosed
in single-quotes, as in

'x'

. A wide character constant is the same, except prefixed by the

letter

. With a few exceptions detailed later, the elements of the sequence are any

members of the source character set; they are mapped in an implementation-defined
manner to members of the execution character set.

The single-quote

, the double-quote

, the question-mark

, the backslash

, and

arbitrary integer values are representable according to the following table of escape
sequences:

single quote

double quote

question mark

backslash

octal character

octal digits

hexadecimal character

hexadecimal digits

The double-quote

and question-mark

are representable either by themselves or by the

escape sequences

and

, respectively, but the single-quote

and the backslash

shall be represented, respectively, by the escape sequences

and

The octal digits that follow the backslash in an octal escape sequence are taken to be part
of the construction of a single character for an integer character constant or of a single
wide character for a wide character constant. The numerical value of the octal integer so
formed specifies the value of the desired character or wide character.

The hexadecimal digits that follow the backslash and the letter

in a hexadecimal escape

sequence are taken to be part of the construction of a single character for an integer
character constant or of a single wide character for a wide character constant. The
numerical value of the hexadecimal integer so formed specifies the value of the desired
character or wide character.

Each octal or hexadecimal escape sequence is the longest sequence of characters that can
constitute the escape sequence.

In addition, characters not in the basic character set are representable by universal
character names and certain nongraphic characters are representable by escape sequences
consisting of the backslash

followed by a lowercase letter:

and

65)

65) The semantics of these characters were discussed in 5.2.2. If any other character follows a backslash,

the result is not a token and a diagnostic is required. See ‘‘future language directions’’ (6.11.4).

60 Language

§6.4.4.4

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