Content-type: text/html Man page of wctomb

wctomb

Section: C Library Functions (3)
Index Return to Main Contents
 

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 standards as follows:

wctomb(): ISO C, XPG4

wcrtomb(): ISO C

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 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 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 Tru64 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 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.

[Digital]  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.  

ERRORS

If the following condition occurs, the wctomb() and wcrtomb() functions set errno to the corresponding value: [Digital]  The wc parameter 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


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
RESTRICTIONS
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:41:19 GMT, October 02, 2010