huschi.net

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.
SEE ALSO
       mblen(3), mbstowcs(3), mbtowc(3), wcsrtombs(3) wctomb(3)
COLOPHON
       This page is part of release 4.15 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                               2017-09-15                       WCSTOMBS(3)