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.10 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				  2016-10-08			   WCSTOMBS(3)