wcstombs

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 re-
          turned.

       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 at-
       tributes(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.

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

COLOPHON
       This page is part of release 5.05 of the Linux  man-pages  project.   A
       description  of  the project, information about reporting bugs, and the
       latest    version    of    this    page,    can     be     found     at
       https://www.kernel.org/doc/man-pages/.

GNU                               2019-03-06                       WCSTOMBS(3)