wctomb(3) Library Functions Manual wctomb(3)
NAME
wctomb, wcrtomb - Converts a wide character into a multibyte character
LIBRARY
Standard C Library (libc)
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 );
STANDARDS
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.
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 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 depen-
dent encoding, calls to the wctomb() function with the wchar parameter set to 0 (zero) put the function in its initial shift state. Subse-
quent 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 conver-
sion 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
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.
RESTRICTIONS
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.
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 char-
acter. 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 parame-
ter contains an invalid wide-character value.
RELATED INFORMATION
Functions: btowc(3), mblen(3), mbstowcs(3), mbtowc(3), wcstombs(3), wctob(3)
Files: locale(4) delim off
wctomb(3)