Your company here, and a link to your site. Click to find out more.

wcstombs - Man Page

convert a wide-character string to a multibyte string


Standard C library (libc, -lc)


#include <stdlib.h>

size_t wcstombs(char dest[restrict .n], const wchar_t *restrict src,
                size_t n);


If dest is not NULL, the wcstombs() function converts the wide-character string src to a multibyte string starting at dest. At most n bytes are written to dest. The sequence of characters placed in dest begins in the initial shift state. The conversion can stop for three reasons:

The programmer must ensure that there is room for at least n bytes at dest.

If dest is NULL, n is ignored, and the conversion proceeds as above, except that the converted bytes are not written out to memory, and no length limit exists.

In order to avoid the case 2 above, the programmer should make sure n is greater than or equal to wcstombs(NULL,src,0)+1.

Return Value

The wcstombs() function returns the number of bytes that make up the converted part of a multibyte sequence, not including the terminating null byte. If a wide character was encountered which could not be converted, (size_t) -1 is returned.


For an explanation of the terms used in this section, see attributes(7).

wcstombs()Thread safetyMT-Safe


The function wcsrtombs(3) provides a better interface to the same functionality.


C11, POSIX.1-2008.


POSIX.1-2001, C99.


The behavior of wcstombs() depends on the LC_CTYPE category of the current locale.

See Also

mblen(3), mbstowcs(3), mbtowc(3), wcsrtombs(3), wctomb(3)

Referenced By

locale(7), MB_CUR_MAX(3), mbstowcs(3), mbtowc(3), wcsrtombs(3), wctomb(3).

2023-10-31 Linux man-pages 6.7