Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

mbtowc(3C)

Name

mbtowc - convert a character to a wide-character code

Synopsis

#include <stdlib.h> 

int mbtowc(wchar_t *restrict pwc, const char *restrict s, size_t n);

Description

If s is not a null pointer, mbtowc() determines the number of the bytes that constitute the character pointed to by s. It then determines the wide-character code for the value of type wchar_t that corresponds to that character. (The value of the wide-character code corresponding to the null byte is 0.) If the character is valid and pwc is not a null pointer, mbtowc() stores the wide-character code in the object pointed to by pwc.

A call with s as a null pointer causes this function to return 0. The behavior of this function is affected by the LC_CTYPE category of the current locale. At most n bytes of the array pointed to by s will be examined.

Return Values

If s is a null pointer, mbtowc() returns 0. If s is not a null pointer, mbtowc() returns 0 (if s points to the null byte), the number of bytes that constitute the converted character (if the next n or fewer bytes form a valid character), or −1 and may set errno to indicate the error (if they do not form a valid character).

In no case will the value returned be greater than n or the value of the MB_CUR_MAX macro.

Errors

The mbtowc() function may fail if:

EILSEQ

Invalid character sequence is detected.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
CSI
Enabled
Interface Stability
Committed
MT-Level
MT-Safe
Standard

See Also

wctomb(3C), mblen(3C), mbstowcs(3C), setlocale(3C), wcstombs(3C), attributes(7), standards(7)