wcstombs, wcsrtombs - Convert a wide-character string into
a multibyte-character string
#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 );
Standard C Library (libc)
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.
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.
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 copying 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 widecharacter
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 calculation 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().
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.
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.
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.
Functions: btowc(3), mblen(3), mbsinit(3), mbstowcs(3),
mbtowc(3), wcslen(3), wctob(3), wctomb(3)
wcstombs(3)
[ Back ] | 