wcstombs(3)wcstombs(3)NAME
wcstombs, wcsrtombs - Convert a wide-character string into a multibyte-
character string
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 );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards 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 multi‐
byte-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-char‐
acter 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 corre‐
sponding 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 con‐
verted 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() func‐
tion) 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().
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 wcsr‐
tombs() 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 char‐
acter, they return a value of -1 cast to size_t and set errno to indi‐
cate 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 wcsr‐
tombs() functions set errno to the corresponding value: The array
pointed to by the pwcs parameter contains an entry that does not corre‐
spond to a valid multibyte character.
SEE ALSO
Functions: btowc(3), mblen(3), mbsinit(3), mbstowcs(3), mbtowc(3),
wcslen(3), wctob(3), wctomb(3)wcstombs(3)
