wcstombs(3)						     Library Functions Manual						       wcstombs(3)

NAME

       wcstombs, wcsrtombs - Converts a wide-character string into a multibyte-character string

LIBRARY

       Standard C Library (libc.so, libc.a)

SYNOPSIS

       #include <stdlib.h>

       size_t wcstombs(
	       char *s,
	       const wchar_t *pwcs,
	       size_t n);

       #include <wchar.h>

       size_t wcsrtombs(
	       char *s,
	       const wchar_t **pwcs,
	       size_t n,
	       mbstate_t *ps );

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       wcstombs():  ISO C, XPG4

       wcsrtombs():  ISO C

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Points  to  the location where the converted multibyte-character string is stored.  Points or indirectly points to the address of the wide-
       character string to be converted.  Specifies the maximum number of bytes to be stored in the output variable (s).  Points to  an  mbstate_t
       structure containing the conversion state of the data in pwcs.

DESCRIPTION

       The  wcstombs()	function converts a wide-character string into a multibyte-character string and stores the result in a location pointed to
       by the s parameter.  The wcstombs() function stores only the number of bytes specified by the n parameter as the output string.	When copy-
       ing between objects that overlap, the behavior of wcstombs() is undefined.

       The  behavior of the wcstombs() function is affected by the LC_CTYPE category of the current locale.  In environments that use shift-state-
       dependent encoding, the array pointed to by s begins in its initial shift state.

       The wcstombs() function converts each character in the pwcs wide-character string and stores the converted character in the s  string.  The
       wcstombs()  function  stops storing characters in the output array under the following conditions: The function has encountered a null wide
       character in the pwcs wide-character string and has written a corresponding null byte in s.  The function cannot store the  next  converted
       wide  character	because  there	is not enough room in s; that is, the function would have to store more than n bytes in the s parameter to
       store the character.  The function has already stored n bytes in the s parameter.  The function has encountered an  invalid  wide-character
       code in the pwcs wide-character string.

       If the wcstombs() function stores exactly n bytes in the s parameter, the function does not store a terminating null byte.

       To  ensure that there is enough room in the s parameter to fit the converted string, the application should allocate enough memory to store
       the maximum multibyte-character string based on the number of wide characters in the wide-character string. Allocate the  number  of  bytes
       (and  pass  the value in the n parameter) equal to the length of the pwcs wide-character string (as determined by the wcslen() or wcsrlen()
       function) multiplied by the value of MB_CUR_MAX in the current locale.  A prior call to wcstombs() or wcsrtombs() can perform this calcula-
       tion  for  the  application.   For example, on the first call to wcstombs() or wcsrtombs(), the application can pass s as a null pointer to
       obtain the number of bytes (not including the terminating null byte) required for s.  The application then uses this return  value  as  the
       value for n in the call to wcstombs() or wcsrtombs() that performs the conversion.

       The wcsrtombs() function is a restartable version of wcstombs().  Restartable conversion functions obtain and store the conversion state in
       an mbstate_t structure that can be read and changed by subsequent calls to the same or other restartable conversion functions. Results  are
       undefined when an application uses restartable and nonrestartable conversion functions with the same source and destination variables.  For
       example, an application would use wcsrlen() rather than wcslen() to determine the length of pwcs if that variable were to be processed with
       wcsrtombs() rather than wcstombs().

RESTRICTIONS

       The  wcsrtombs()  and other restartable versions of conversion routines are functional only when used with locales that support shift state
       encoding.  Currently, the Tru64 UNIX product does not provide any locales that use shift state encoding, so the wcstombs() and  wcsrtombs()
       functions do not differ in terms of run-time behavior.

RETURN VALUES

       If  the	wcstombs()  and wcsrtombs() functions do not encounter an invalid wide-character code, they return the number of bytes stored, not
       including the terminating null byte.  When these functions encounter a wide-character code that does not correspond to  a  valid  multibyte
       character, they return a value of -1 cast to size_t and set errno to indicate the error.

       If  the	wcstombs()  and  wcsrtombs() cannot store all of the converted characters in the output array, the functions stop before storing a
       character that would overflow the output array and return the number of bytes stored in the array.  When the return value is n, the  output
       array is not null terminated.

       If these functions are called with a null pointer value for s, they return the number of bytes required for the output character array.

ERRORS

       If  any of the following conditions occur, the wcstombs() and wcsrtombs() functions set errno to the corresponding value: The array pointed
       to by the pwcs parameter contains an entry that does not correspond to a valid multibyte character.

RELATED INFORMATION

       Functions: btowc(3), mblen(3), mbsinit(3), mbstowcs(3), mbtowc(3), wcslen(3), wctob(3), wctomb(3) delim off

																       wcstombs(3)