*** UNIX MANUAL PAGE BROWSER ***

wctomb(3) Library Functions Manual wctomb(3) NAME wctomb, wcrtomb - Converts a wide character into a multibyte character LIBRARY Standard C Library (libc.so, libc.a) 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 stan- dards as follows: wctomb(): ISO C, XPG4 wcrtomb(): ISO C Refer to the standards(5) reference page for more information about in- dustry 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 lo- cale causes the shift state of the function to be unreliable. The implementation behaves as though no other function calls the wc- tomb() 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 DIGITAL UNIX product 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 func- tion 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. [Digital] In this case, the function also sets errno to indi- cate 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 (in- cluding 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 er- rno to indicate the error. If *s is a null pointer, both the wctomb() and wcrtomb() functions re- turn one of the following values, depending on whether the current lo- cale 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: [Digital] The wc parameter con- tains an invalid wide-character value. RELATED INFORMATION Functions: btowc(3), mblen(3), mbstowcs(3), mbtowc(3), wcstombs(3), wc- tob(3) Files: locale(4) delim off wctomb(3)