wctomb(3)wctomb(3)NAME
wctomb, wcrtomb - Convert a wide character into a multibyte character
SYNOPSIS
#include <stdlib.h>
int wctomb(
char *s,
wchar_t wc ); #include <wchar.h>
size_t wcrtomb(
char *s,
wchar_t wc,
mbstate_t *ps );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
wctomb(), wcrtomb(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
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.
DESCRIPTION
The wctomb() function converts a wide character into a multibyte char‐
acter 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 cate‐
gory 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 shift-state 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 pre‐
cedes the null byte with the shift sequence needed to restore the ini‐
tial shift state; in this case, completion of the call sets the conver‐
sion state to the initial conversion state.
RESTRICTIONS
The wcrtomb() and other restartable versions of conversion routines are
functional only when used with locales that support shift-state encod‐
ing. 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.
RETURN VALUES
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 charac‐
ter. 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.
ERRORS
If the following condition occurs, the wctomb() and wcrtomb() functions
set errno to the corresponding value: [Tru64 UNIX] The wc parameter
contains an invalid wide-character value.
SEE ALSO
Functions: btowc(3), mblen(3), mbstowcs(3), mbtowc(3), wcstombs(3),
wctob(3)
Files: locale(4)wctomb(3)
