GENWiki

WCSTOMBS(3) Linux Programmer's Manual WCSTOMBS(3)

NAME

     wcstombs - convert a wide-character string to a multibyte string

SYNOPSIS

     #include <stdlib.h>

     size_t wcstombs(char *dest, const wchar_t *src, size_t n);

DESCRIPTION

     If  dest is not NULL, the wcstombs() function converts the wide-charac-
     ter 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:

     1. A wide character has been encountered that can not be represented as
        a multibyte sequence (according to the  current  locale).   In  this
        case, (size_t) -1 is returned.

     2. The  length  limit forces a stop.  In this case, the number of bytes
        written to dest is returned, but the shift state at  this  point  is
        lost.

     3. The  wide-character  string has been completely converted, including
        the terminating null wide character (L'\0').  In this case, the con-
        version  ends in the initial shift state.  The number of bytes writ-
        ten  to  dest,  excluding  the  terminating  null  byte  ('\0'),  is
        returned.

     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 con-
     verted, (size_t) -1 is returned.

ATTRIBUTES

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

     +-----------+---------------+---------+
     |Interface  | Attribute     | Value   |
     +-----------+---------------+---------+
     |wcstombs() | Thread safety | MT-Safe |
     +-----------+---------------+---------+

CONFORMING TO

     POSIX.1-2001, POSIX.1-2008, C99.

NOTES

     The behavior of wcstombs() depends on the LC_CTYPE category of the cur-
     rent locale.

     The function wcsrtombs(3) provides a better interface to the same func-
     tionality.