wcrtomb, wcrtomb_s

 

C

Language

headers

Type support

Dynamic memory management

Error handling

Program utilities

Variadic function support

Date and time utilities

Strings library

Algorithms

Numerics

Input/output support

Localization support

Thread support (C11)

Atomic operations (C11)

Technical Specifications

 

Strings library

Byte strings

Multibyte strings

Wide strings

 

Null-terminated multibyte strings

Wide/multibyte conversions
mbsinit (C95)
mbtowc mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
Types
mbstate_t (C95)

 

Defined in header <wchar.h>
size_t wcrtomb( char *s, wchar_t wc, mbstate_t *ps);	(1)	(since C95)
errno_t wcrtomb_s(size_t *restrict retval, char *restrict s, rsize_t ssz,                   wchar_t wc, mbstate_t *restrict ps);	(2)	(since C11)

Converts a wide character to its narrow multibyte representation.

1) If s is not a null pointer, the function determines the number of bytes necessary to store the multibyte character representation of wc (including any shift sequences), and stores the multibyte character representation in the character array whose first element is pointed to by s. At most MB_CUR_MAX bytes can be written by this function.

If s is a null pointer, the call is equivalent to wcrtomb(buf, L'\0', ps) for some internal buffer buf.

If wc is the null wide character L'\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter *ps is updated to represent the initial shift state.

2) Same as (1), except that

if s is a null pointer, the call is equivalent to wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) with internal variables retval and buf (whose size is greater than MB_CUR_MAX)

the result is returned in the out-parameter retval

the following errors are detected at runtime and call the currently installed constraint handler function:

• retval or ps is a null pointer.
• ssz is zero or greater than RSIZE_MAX (unless s is null)
• ssz is less than the number of bytes that would be written (unless s is null)
• s is a null pointer but ssz is not zero

As all bounds-checked functions, wcrtomb_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including wchar.h.

Parameters

s	-	pointer to narrow character array where the multibyte character will be stored
wc	-	the wide character to convert
ps	-	pointer to the conversion state object used when interpreting the multibyte string
ssz	-	max number of bytes to write (the size of the buffer s)
retval	-	pointer to an out-parameter where the result (number of bytes in the multibyte string including any shift sequences) will be stored

Return value

1) On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by s.

On failure (if wc is not a valid wide character), returns (size_t)-1, stores EILSEQ in errno, and leaves *ps in unspecified state.

2) Returns zero on success and non-zero on failure, in which case, s[0] is set to '\0' (unless s is null or ssz is zero or greater than RSIZE_MAX) and *retval is set to (size_t)-1 (unless retval is null)

Example

Run this code

#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
#include <stdlib.h>
 
void print_wide(const wchar_t* wstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    char mb[MB_CUR_MAX+1];
    for(;*wstr; ++wstr) {
        int ret = wcrtomb(mb, *wstr, &state);
        mb[ret] = '\0';
        printf("multibyte char %s is %d bytes\n", mb, ret);
    }
}
 
int main()
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001F34C"); // or L"zß水🍌"
}

Output:

multibyte char z is 1 bytes
multibyte char ß is 2 bytes
multibyte char 水 is 3 bytes
multibyte char 🍌 is 4 bytes

References

• C11 standard (ISO/IEC 9899:2011):

• 7.29.6.3.3 The wcrtomb function (p: 444)

• K.3.9.3.1.1 The wcrtomb_s function (p: 647-648)

• C99 standard (ISO/IEC 9899:1999):

• 7.24.6.3.3 The wcrtomb function (p: 390)

See also

wctombwctomb_s (C11)	converts a wide character to its multibyte representation (function)
mbrtowc (C95)	converts the next multibyte character to wide character, given state (function)
C++ documentation for wcrtomb