7.4.21 <wchar.h>

The following shows macros.

Type

Definition Name

Description

Macro

mbstate_t

Indicates the type for holding the necessary state of conversion between sequences of multibyte characters and wide characters.

wint_t

Indicates the type for holding extended characters.

Constant
(macro)

WEOF

Indicates the end-of-file.

Function

fwprintf

Converts the output format and outputs data to a stream.

vfwprintf

Equivalent to fwprintf with the variable argument list replaced by va_list.

swprintf

Converts the output format and writes data to an array of wide characters.

vswprintf

Equivalent to swprintf with the variable argument list replaced by va_list.

wprintf

Equivalent to fwprintf with stdout added as an argument before the specified arguments.

vwprintf

Equivalent to wprintf with the variable argument list replaced by va_list.

fwscanf

Inputs and converts data from the stream under control of the wide string and assigns it to an object.

vfwscanf <-lang=c99>

Equivalent to fwscanf with the variable argument list replaced by va_list.

swscanf

Converts data under control of the wide string and assigns it to an object.

vswscanf <-lang=c99>

Equivalent to swscanf with the variable argument list replaced by va_list.

wscanf

Equivalent to fwscanf with stdin added as an argument before the specified arguments.

vwscanf <-lang=c99>

Equivalent to wscanf with the variable argument list replaced by va_list.

fgetwc

Inputs a wide character as the wchar_t type and converts it to the wint_t type.

fgetws

Stores a sequence of wide characters in an array.

fputwc

Writes a wide character.

fputws

Writes a wide string.

fwide

Specifies the input/output unit.

getwc

Equivalent to fgetwc.

getwchar

Equivalent to getwc with stdin specified as an argument.

putwc

Equivalent to fputwc.

putwchar

Equivalent to putwc with stdout specified as the second argument.

Function

ungetwc

Returns a wide character to a stream.

wcstod

wcstof

wcstold

These convert the initial part of a wide string to double, float, or long double representation.

wcstol

wcstoll <-lang=c99>

wcstoul

wcstoull <-lang=c99>

These convert the initial part of a wide string to long int, long long int, unsigned long int, or unsigned long long int representation.

wcscpy

Copies a wide string.

wcsncpy

Copies n or fewer wide characters.

wmemcpy

Copies n wide characters.

wmemmove

Copies n wide characters.

wcscat

Copies a wide string and appends it to the end of another wide string.

wcsncat

Copies a wide string with n or fewer wide characters and appends it to the end of another wide character string.

wcscmp

Compares two wide strings.

wcsncmp

Compares two arrays with n or fewer wide characters.

wmemcmp

Compares n wide characters.

wcschr

Searches for a specified wide string in another wide string.

wcscspn

Checks if a wide string contains another specified wide string.

wcspbrk

Searches for the first occurrence of a specified wide string in another wide string.

wcsrchr

Searches for the last occurrence of a specified wide character in a wide string.

wcsspn

Calculates the length of the maximum initial segment of a wide string, which consists of specified wide characters.

wcsstr

Searches for the first occurrence of a specified sequence of wide characters in a wide string.

wcstok

Divides a wide string into a sequence of tokens delimited by a specified wide character.

wmemchr

Searches for the first occurrence of a specified wide character within the first n wide characters in an object.

wcslen

Calculates the length of a wide string.

wmemset

Copies n wide characters.

mbsinit

Checks if a specified object indicates the initial conversion state.

mbrlen

Calculates the number of bytes in a multibyte character.

 

fwprintf

Outputs data to a stream input/output file according to the format.

[Format]

#include <stdio.h>
#include <wchar.h>
long fwprintf(FILE *restrict fp, const wchar_t *restrict control [, arg] );

[Parameters]

fp File pointer

control Pointer to wide string indicating format

arg, List of data to be output according to format

[Return values]

Normal: Number of wide strings converted and output

Abnormal: Negative value

[Remarks]

The fwprintf function is the wide-character version of the fprintf function.

 

vfwprintf

Outputs a variable parameter list to the specified stream input/output file according to a format.

[Format]

#include <stdarg.h>
#include <stdio.h>
#include <wchar.h>
long vfwprintf(FILE *restrict fp, const char *restrict control, va_list arg)


[Parameters]

fp File pointer

control Pointer to wide string indicating format

arg Parameter list

[Return values]

Normal: Number of characters converted and output

Abnormal:Negative value

[Remarks]

The vfwprintf function is the wide-character version of the vfprintf function.

 

swprintf

Converts data according to a format and outputs it to the specified area.

[Format]

#include <stdio.h>
#include <wchar.h>
long swprintf(wchar_t *restrict s, size_t n, const wchar_t *restrict control [, arg]...);

[Parameters]

s Pointer to storage area to which data is to be output

n Number of wide characters to be output

control Pointer to wide string indicating format

arg, Data to be output according to format

[Return values]

Normal: Number of characters converted

Abnormal: When a representation format error occurs or writing n or morewide characters is requested: Negative value

[Remarks]

The swprintf function is the wide-character version of the sprintf function.

 

vswprintf

Outputs a variable parameter list to the specified storage area according to a format.

[Format]

#include <stdarg.h>
#include <wchar.h>
long vswprintf(wchar_t *restrict s, size_t n, const wchar_t *restrict control, va_list arg)

[Parameters]

s Pointer to storage area to which data is to be output

n Number of wide characters to be output

control Pointer to wide string indicating format

arg Parameter list

[Return values]

Normal: Number of characters converted

Abnormal: Negative value

[Remarks]

The vswprintf function is the wide-character version of the vsprintf function.

 

wprintf

Converts data according to a format and outputs it to the standard output file (stdout).

[Format]

#include <stdio.h>
#include <wchar.h>
long wprintf(const wchar_t *restrict control [, arg]...);

[Parameters]

control Pointer to string indicating format

arg, Data to be output according to format

[Return values]

Normal: Number of wide characters converted and output

Abnormal:Negative value

[Remarks]

The wprintf function is the wide-character version of printf function.

 

vwprintf

Outputs a variable parameter list to the standard output file (stdout) according to a format.

[Format]

#include <stdarg.h>
#include <wchar.h>
long vwprintf(const wchar_t *restrict control, va_list arg);

[Parameters]

control Pointer to wide string indicating format

arg Parameter list

[Return values]

Normal: Number of characters converted and output

Abnormal:Negative value

[Remarks]

The vwprintf function is the wide-character version of the vprintf function.

 

fwscanf

Inputs data from a stream input/output file and converts it according to a format.

[Format]

#include <stdio.h>
#include <wchar.h>
long fwscanf(FILE *restrict fp, const wchar_t *restrict control [, ptr]...);

[Parameters]

fp File pointer

control Pointer to wide string indicating format

ptr Pointer to storage area that stores input data

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: Input data ends before input data conversion is performed: EOF

[Remarks]

The fwscanf function is the wide-character version of the fscanf function.

 

vfwscanf

Inputs data from a stream input/output file and converts it according to a format.

[Format]

#include <stdarg.h>
#include <stdio.h>
#include <wchar.h>
long vfwscanf(FILE *restrict fp, const wchar_t *restrict control, va_list arg)


[Parameters]

fp File pointer

control Pointer to wide string indicating format

arg Parameter list

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: Input data ends before input data conversion is performed: EOF

[Remarks]

The vfwscanf is the wide-character version of the vfscanf function.

 

swscanf

Inputs data from the specified storage area and converts it according to a format.

[Format]

#include <stdio.h>
#include <wchar.h>
long swscanf(const wchar_t *restrict s, const wchar_t *restrict control [, ptr]...);

[Parameters]

s Storage area containing data to be input

control Pointer to wide string indicating format

ptr, Pointer to storage area that stores input and converted data

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: EOF

[Remarks]

The swscanf is the wide-character version of the sscanf function.

 

vswscanf

Inputs data from the specified storage area and converts it according to a format.

[Format]

#include <stdarg.h>
#include <wchar.h>
long vswscanf(const wchar_t *restrict s, const wchar_t *restrict control, va_list arg);

[Parameters]

s Storage area containing data to be input

control Pointer to wide string indicating format

arg Parameter list

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: EOF

 

wscanf

Inputs data from the standard input file (stdin) and converts it according to a format.

[Format]

#include <wchar.h>
long wscanf(const wchar_t *control [, ptr] );

[Parameters]

control Pointer to wide string indicating format

ptr, Pointer to storage area that stores input and converted data

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: EOF

[Remarks]

The wscanf function is the wide-character version of the scanf function.

 

vwscanf

Inputs data from the specified storage area and converts it according to a format.

[Format]

#include <stdarg.h>
#include <wchar.h>
long vwscanf(const wchar_t *restrict control, va_list arg)

[Parameters]

control Pointer to wide string indicating format

arg Parameter list

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: Input data ends before input data conversion is performed: EOF

[Remarks]

The vwscanf function is provided to support wide-character format with the vscanf function.

 

fgetwc

Inputs one wide character from a stream input/output file.

[Format]

#include <stdio.h>
#include <wchar.h>
wint_t fgetwc(FILE *fp);

[Parameters]

fp File pointer

[Return values]

Normal: End-of-file: EOF

Otherwise: Input wide character

Abnormal: EOF

[Remarks]

When a read error occurs, the error indicator for that file is set.

The fgetwc function is provided to support wide-character input to the fgetc function.

 

fgetws

Inputs a wide string from a stream input/output file.

[Format]

#include <stdio.h>
#include <wchar.h>
wchar_t *fgetws(wchar_t *restrict s, long n, FILE *fp);

[Parameters]

s Pointer to storage area to which wide string is input

n Number of bytes of storage area to which wide string is input

fp File pointer

[Return values]

Normal: End-of-file: NULL

Otherwise: s

Abnormal: NULL

[Remarks]

The fgetws function is provided to support wide-character input to the fgets function.

 

fputwc

Outputs one wide character to a stream input/output file.

[Format]

#include <stdio.h>
#include <wchar.h>
wint_t fputwc(wchar_t c, FILE *fp);

[Parameters]

c Character to be output

fp File pointer

[Return values]

Normal: Output wide character

Abnormal: EOF

[Remarks]

When a write error occurs, the error indicator for that file is set.

The fputwc function is the wide-character version of the fputc function.

 

fputws

Outputs a wide string to a stream input/output file.

[Format]

#include <stdio.h>
#include <wchar.h>
long fputws(const wchar_t *restrict s, FILE *restrict fp);

[Parameters]

s Pointer to wide string to be output

fp File pointer

[Return values]

Normal: 0

Abnormal: EOF

[Remarks]

The fputws function is the wide-character version of the fputs function.

 

fwide

Specifies the input unit of a file.

[Format]

#include <stdio.h>
#include <wchar.h>
long fwide(FILE *fp, long mode);

[Parameters]

fp File pointer

mode Value indicating the input unit

[Return values]

A wide character is specified as the unit: Value greater than 0

A byte is specified as the unit: Value smaller than 0

No input/output unit is specified: 0

[Remarks]

The fwide function does not change the stream input/output unit that has already been determined.

 

getwc

Inputs one wide character from a stream input/output file.

[Format]

#include <stdio.h>
#include <wchar.h>
long getwc(FILE *fp);

[Parameters]

fp File pointer

[Return values]

Normal: End-of-file: WEOF

Otherwise: Input wide character

Abnormal: EOF

[Remarks]

When a read error occurs, the error indicator for that file is set.

The getwc function is equivalent to fgetwc, but getwc may evaluate fp two or more times because it is implemented as a macro. Accordingly, specify an expression without side effects for fp.

 

getwchar

Inputs one wide character from the standard input file (stdin).

[Format]

#include <wchar.h>
long getwchar(void);

[Return values]

Normal: End-of-file: WEOF

Otherwise: Input wide character

Abnormal: EOF

[Remarks]

When a read error occurs, the error indicator for that file is set.

The getwchar function is the wide-character version of the getchar function.

 

putwc

Outputs one wide character to a stream input/output file.

[Format]

#include <stdio.h>
#include <wchar.h>
wint_t putwc(wchar_t c, FILE *fp);

[Parameters]

c Wide character to be output

fp File pointer

[Return values]

Normal: Output wide character

Abnormal: WEOF

[Remarks]

When a write error occurs, the error indicator for that file is set.

The putwc function is equivalent to fputwc, but putwc may evaluate fp two or more times because it is implemented as a macro. Accordingly, specify an expression without side effects for fp.

 

putwchar

Outputs one wide character to the standard output file (stdout).

[Format]

#include <wchar.h>
wint_t putwchar(wchar_t c);

[Parameters]

c Wide character to be output

[Return values]

Normal: Output wide character

Abnormal: WEOF

[Remarks]

When a write error occurs, the error indicator for that file is set.

The putwchar function is the wide-character version of the putchar function.

 

ungetwc

Returns one wide character to a stream input/output file.

[Format]

#include <stdio.h>
#include <wchar.h>
wint_t ungetwc(wint_t c, FILE *fp);

[Parameters]

c Wide character to be returned

fp File pointer

[Return values]

Normal: Returned wide character

Abnormal: WEOF

[Remarks]

The ungetwc function is the wide-character version of the ungetc function.

 

wcstod/wcstof/wcstold

Converts the initial part of a wide string to a specified-type floating-point number.

[Format]

#include <wchar.h>
double wcstod(const wchar_t *restrict nptr, wchar_t **restrict endptr);
float wcstof(const wchar_t *restrict nptr, wchar_t **restrict endptr);
long double wcstold(const wchar_t *restrict nptr, wchar_t **restrict endptr);


[Parameters]

nptr Pointer to a number-representing string to be converted

endptr Pointer to the storage area containing a pointer to the first character that does not represent a floating-point number

[Return Values]

Normal: If the string pointed by nptr begins with a character that does not represent a floating-point number: 0
If the string pointed by nptr begins with a character thatrepresents a floating-point number: Converted data as a specified-type floating-point number

Abnormal: If the converted data overflows: HUGE_VAL, HUGE_VALF, or HUGE_VALL with the same sign as that of the string before conversion
If the converted data underflows: 0

[Remarks]

If the converted result overflows or underflows, errno is set.

The wcstod function group is the wide-character version of the strtod function group.

 

wcstol/wcstoll/wcstoul/wcstoull

Converts the initial part of a wide string to a specified-type integer.

[Format]

#include <wchar.h>
long int wcstol(const wchar_t * restrict nptr, wchar_t ** restrict endptr, long base);
long long int wcstoll(const wchar_t * restrict nptr, wchar_t ** restrict endptr, long base);
unsigned long int wcstoul(const wchar_t * restrict nptr, wchar_t ** restrict endptr, long base);
unsigned long long int wcstoull(const wchar_t * restrict nptr, wchar_t ** restrict endptr, long base;



[Parameters]

nptr Pointer to a number-representing string to be converted

endptr Pointer to the storage area containing a pointer to the first character that does not represent an integer

base Radix of conversion (0 or 2 to 36)

[Return values]

Normal: If the string pointed by nptr begins with a character that does not represent an integer: 0
If the string pointed by nptr begins with a character that represents an integer: Converted data as a specified-type integer

Abnormal: If the converted data overflows: LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX, ULONG_MAX, or ULLONG_MAX depending on the sign of the string before conversion

[Remarks]

If the converted result overflows, errno is set.

The wcstol function group is the wide-character version of the strtol function group.

 

wcscpy

Copies the contents of a source wide string including the null character to a destination storage area.

[Format]

#include <wchar.h>
wchar_t *wcscpy(wchar_t * restrict s1, const wchar_t * restrict s2);

[Parameters]

s1 Pointer to destination storage area

s2 Pointer to source string

[Return values]

s1 value

[Remarks]

The wcscpy function group is the wide-character version of the strcpy function group.

 

wcsncpy

Copies a source wide string of a specified length to a destination storage area.

[Format]

#include <wchar.h>
wchar_t *wcsncpy(wchar_t * restrict s1, const wchar_t * restrict s2, size_t n);

[Parameters]

s1 Pointer to destination storage area

s2 Pointer to source string

n Number of characters to be copied

[Return values]

s1 value

[Remarks]

The wcsncpy function is the wide-character version of the strncpy function.

 

wmemcpy

Copies the contents of a source storage area of a specified length to a destination storage area.

[Format]

#include <wchar.h>
wchar_t *wmemcpy(wchar_t *restrict s1, const wchar_t *restrict s2, size_t n);

[Parameters]

s1 Pointer to destination storage area

s2 Pointer to source storage area

n Number of characters to be copied

[Return values]

s1 value

[Remarks]

The wmemcpy function is the wide-character version of the memcpy function.

 

wmemmove

Copies the specified size of the contents of a source area to a destination storage area. If part of the source storage area and the destination storage area overlap, data is copied to the destination storage area before the overlapped source storage area is overwritten. Therefore, correct copy is enabled.

[Format]

#include <wchar.h>
wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2, size_t n);

[Parameters]

s1 Pointer to destination storage area

s2 Pointer to source storage area

n Number of characters to be copied

[Return values]

s1 value

[Remarks]

The wmemmove function is the wide-character version of the memmove function.

 

wcscat

Concatenates a string after another string.

[Format]

#include <wchar.h>
wchar_t *wcscat(wchar_t *s1, const wchar_t *s2);

[Return values]

s1 value

[Parameters]

s1 Pointer to the string after which another string is appended

s2 Pointer to the string to be appended after the other string

[Remarks]

The wcscat function is the wide-character version of the strcat function.

 

wcsncat

Concatenates a string of a specified length after another string.

[Format]

#include <wchar.h>
wchar_t *wcsncat(wchar_t * restrict s1, const wchar_t * restrict s2, size_t n);

[Parameters]

s1 Pointer to the string after which another string is appended

s2 Pointer to the string to be appended after the other string

n Number of characters to concatenate

[Return values]

s1 value

[Remarks]

The wcsncat function is the wide-character version of the strncat function.

 

wcscmp

Compares the contents of two strings specified.

[Format]

#include <wchar.h>
long wcscmp(const wchar_t *s1, const wchar_t *s2);

[Parameters]

s1 Pointer to the reference string to be compared

s2 Pointer to the string to compare to the reference

[Return values]

If string pointed by s1 > string pointed by s2: Positive value

If string pointed by s1 == string pointed by s2: 0

If string pointed by s1 < string pointed by s2: Negative value

[Remarks]

The wcscmp function is the wide-character version of the strcmp function.

 

wcsncmp

Compares two strings specified up to a specified length.

[Format]

#include <wchar.h>
long wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);

[Parameters]

s1 Pointer to the reference string to be compared

s2 Pointer to the string to compare to the reference

n Maximum number of characters to compare

[Return values]

If string pointed by s1 > string pointed by s2: Positive value

If string pointed by s1 == string pointed by s2: 0

If string pointed by s1 < string pointed by s2: Negative value

[Remarks]

The wcsncmp function is the wide-character version of the strncmp function.

 

wmemcmp

Compares the contents of two storage areas specified.

[Format]

#include <wchar.h>
long wmemcmp(const wchar_t * s1, const wchar_t * s2, size_t n);

[Parameters]

s1 Pointer to the reference storage area to be compared

s2 Pointer to the storage area to compare to the reference

n Number of characters to compare

[Return values]

If storage area pointed by s1 > storage area pointed by s2: Positive value

If storage area pointed by s1 == storage area pointed by s2: 0

If storage area pointed by s1 < storage area pointed by s2: Negative value

[Remarks]

The wmemcmp function is the wide-character version of the memcmp function.

 

wcschr

Searches a specified string for the first occurrence of a specified character.

[Format]

#include <wchar.h>
wchar_t *wcschr(const wchar_t *s, wchar_t c);

[Parameters]

s Pointer to the string to be searched

c Character to search for

[Return values]

If the character is found: Pointer to the found character

If the character is not found: NULL

[Remarks]

The wcschr function is the wide-character version of the strchr function.

 

wcscspn

Checks a specified string from the beginning and counts the number of consecutive characters at the beginning that are not included in another string specified.

[Format]

#include <wchar.h>
size_t wcscspn(const wchar_t *s1, const wchar_t *s2);

[Parameters]

s1 Pointer to the string to be checked

s2 Pointer to the string used to check s1

[Return values]

Number of characters at the beginning of the s1 string that are not included in the s2 string

[Remarks]

The wcscspn function is the wide-character version of the strcspn function.

 

wcspbrk

Searches a specified string for the first occurrence of the character that is included in another string specified.

[Format]

#include <wchar.h>
wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);

[Parameters]

s1 Pointer to the string to be searched

s2 Pointer to the string that indicates the characters to search s1 for

[Return values]

If the character is found: Pointer to the found character

If the character is not found: NULL

[Remarks]

The wcspbrk function is the wide-character version of the strpbrk function.

 

wcsrchr

Searches a specified string for the last occurrence of a specified character.

[Format]

#include <wchar.h>
wchar_t *wcsrchr(const wchar_t *s, wchar_t c);

[Parameters]

s Pointer to the string to be searched

c Character to search for

[Return values]

If the character is found: Pointer to the found character

If the character is not found: NULL

 

wcsspn

Checks a specified string from the beginning and counts the number of consecutive characters at the beginning that are included in another string specified.

[Format]

#include <wchar.h>
size_t wcsspn(const wchar_t *s1, const wchar_t *s2);

[Parameters]

s1 Pointer to the string to be checked

s2 Pointer to the string used to check s1

[Return values]

Number of characters at the beginning of the s1 string that are included in the s2 string

[Remarks]

The wcsspn function is the wide-character version of the strspn function.

 

wcsstr

Searches a specified string for the first occurrence of another string specified.

[Format]

#include <wchar.h>
wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);

[Parameters]

s1 Pointer to the string to be searched

s2 Pointer to the string to search for

[Return values]

If the string is found: Pointer to the found string

If the string is not found: NULL

 

wcstok

Divides a specified string into some tokens.

[Format]

#include <wchar.h>
wchar_t* wcstok(wchar_t * restrict s1, const wchar_t * restrict s2, wchar_t ** restrict ptr);

[Parameters]

s1 Pointer to the string to be divided into some tokens

s2 Pointer to the string representing string-dividing characters

ptr Pointer to the string where search is to be started at the next function call

[Return values]

If division into tokens is successful: Pointer to the first token divided

If division into tokens is unsuccessful: NULL

[Remarks]

The wcstok function is the wide-character version of the strtok function.

To search the same string for the second or later time, set s1 to NULL and ptr to the value returned by the previous function call to the same string.

 

wmemchr

Searches a specified storage area for the first occurrence of a specified character.

[Format]

#include <wchar.h>
wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);

[Parameters]

s Pointer to the storage area to be searched

c Character to search for

n Number of characters to search

[Return values]

If the character is found: Pointer to the found character

If the character is not found: NULL

[Remarks]

The wmemchr function is the wide-character version of the memchr function.

 

wcslen

Calculates the length of a wide string except the terminating null wide character.

[Format]

#include <wchar.h>
size_t wcslen(const wchar_t *s);

[Parameters]

s Pointer to the wide string to check the length of

[Return values]

Number of characters in the wide string

[Remarks]

The wcslen function is the wide-character version of the strlen function.

 

wmemset

Sets a specified character a specified number of times at the beginning of a specified storage area.

[Format]

#include <wchar.h>
wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);

[Parameters]

s Pointer to storage area to set characters in

c Character to be set

n Number of characters to be set

[Return values]

Value of s

[Remarks]

The wmemset function is the wide-character version of the memset function.

 

mbsinit

Checks if a specified mbstate_t object indicates the initial conversion state.

[Format]

#include <wchar.h>
long mbsinit(const mbstate_t *ps);

[Parameters]

ps Pointer to mbstate_t object

[Return values]

Initial conversion state: Nonzero

Otherwise: 0

 

mbrlen

Calculates the number of bytes in a specified multibyte character.

[Format]

#include <wchar.h>
size_t mbrlen(const char * restrict s, size_t n, mbstate_t *restrict ps);

[Parameters]

s Pointer to multibyte string

n Maximum number of bytes to be checked for multibyte character

ps Pointer to mbstate_t object

[Return values]

0: A null wide character is detected in n or fewer bytes.

From 1 to n inclusive: A multibyte character is detected in n or fewer bytes.

(size_t)(2): No complete multibyte character is detected in n bytes.

(size_t)(1): An illegal multibyte sequence is detected.