WCTOMB(3) BSD Library Functions Manual WCTOMB(3)NAME
wctomb -- converts a wide character to a multibyte character
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
int
wctomb(char * s, const wchar_t wchar);
DESCRIPTION
The wctomb() converts the wide character wchar to the corresponding multibyte character, and stores it in the array pointed to by s.
wctomb() may store at most MB_CUR_MAX bytes in the array.
In state-dependent encoding, wctomb() may store the special sequence to change the conversion state before an actual multibyte character into
the array pointed to by s. If wchar is a nul wide character (' '), this function sets its own internal state to an initial conversion
state.
Calling any other functions in Standard C Library (libc, -lc) never changes the internal state of wctomb(), except changing the LC_CTYPE cat-
egory of the current locale by calling setlocale(3). Such setlocale(3) calls cause the internal state of this function to be indeterminate.
The behaviour of wctomb() is affected by the LC_CTYPE category of the current locale.
There is one special case:
s == NULL wctomb() initializes its own internal state to an initial state, and determines whether the current encoding is state-depen-
dent. This function returns 0 if the encoding is state-independent, otherwise non-zero. In this case, wchar is completely
ignored.
RETURN VALUES
Normally, wctomb() returns:
positive Number of bytes for the valid multibyte character pointed to by s. There are no cases that the value returned is greater than
n or the value of the MB_CUR_MAX macro.
-1 wchar is an invalid wide character.
If s is equal to NULL, mbtowc() returns:
0 The current encoding is state-independent.
non-zero The current encoding is state-dependent.
ERRORS
No errors are defined.
SEE ALSO setlocale(3)STANDARDS
The wctomb() function conforms to ANSI X3.159-1989 (``ANSI C89'').
BSD February 3, 2002 BSD
Check Out this Related Man Page
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)