wctomb, wcrtomb - Convert a wide character into a multibyte
character
#include <stdlib.h>
int wctomb(
char *s,
wchar_t wc ); #include <wchar.h>
size_t wcrtomb(
char *s,
wchar_t wc,
mbstate_t *ps );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
wctomb(), wcrtomb(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Points to the location where the conversion is stored.
Specifies the wide character to be converted. Points to a
mbstate_t structure that contains the conversion state of
the data in s.
The wctomb() function converts a wide character into a
multibyte character and stores the result in s. The
wctomb() function stores no more than MB_CUR_MAX bytes in
s and returns the number of bytes stored.
The behavior of the wctomb() function is affected by the
LC_CTYPE category of the current locale. In environments
with shift-state dependent encoding, calls to the wctomb()
function with the wchar parameter set to 0 (zero) put the
function in its initial shift state. Subsequent calls with
the wc parameter set to nonzero values alter the state of
the function as necessary. Changing the LC_CTYPE category
of the locale causes the shift state of the function to be
unreliable.
The implementation behaves as though no other function
calls the wctomb() function.
In the case of nonrestartable functions, such as wctomb(),
conversion to shift-state encoding must first be enabled
by calling the function with a null pointer parameter and
then calling the function again with the wide-character
value to be converted. The status of the conversion operation
after the call is not available to subsequent calls.
The wcrtomb() function is a restartable version of
wctomb(), which means that, for locales that define shiftstate
encoding, the shift state for the character in s is
maintained in the mbstate_t structure and is therefore
available to subsequent calls by wcrtomb() and other
restartable conversion functions.
If wc is a null wide character, wcrtomb() stores a null
byte in s. If the current locale defines shift-state
encoding, the function also precedes the null byte with
the shift sequence needed to restore the initial shift
state; in this case, completion of the call sets the conversion
state to the initial conversion state.
The wcrtomb() and other restartable versions of conversion
routines are functional only when used with locales that
support shift-state encoding. Currently, the operating
system does not provide any locales that use shift-state
encoding. Therefore, the wcrtomb() function has the same
run-time behavior as the wctomb() function and neither
function returns values for state-dependent conditions.
If *s is not a null pointer, the wctomb() function returns
one of the following values: A positive value indicating
the number of bytes in the multibyte character, if the wc
parameter corresponds to a valid multibyte character -1,
if the wc parameter does not correspond to a valid multibyte
character.
[Tru64 UNIX] In this case, the function also sets
errno to indicate the error.
If *s is not a null pointer, the wcrtomb() function
returns one of the following values: A positive value
indicating the number of bytes (including shift sequences)
stored in s, if wc can be converted to a valid multibyte
character (size_t)-1, if wc is not a valid wide character.
In this case, the conversion state is undefined and the
function sets errno to indicate the error.
If *s is a null pointer, both the wctomb() and wcrtomb()
functions return one of the following values, depending on
whether the current locale uses state-dependent encoding:
0 (zero), if encoding is not state dependent A nonzero
value, if encoding is state dependent
In no case do the wctomb() or wcrtomb() functions return a
value greater than the value of the MB_CUR_MAX variable.
If the following condition occurs, the wctomb() and wcrtomb()
functions set errno to the corresponding value:
[Tru64 UNIX] The wc parameter contains an invalid widecharacter
value.
Functions: btowc(3), mblen(3), mbstowcs(3), mbtowc(3),
wcstombs(3), wctob(3)
Files: locale(4)
wctomb(3)
[ Back ] | 