wctomb_s, _wctomb_s_l

Convierte un carácter ancho en el carácter multibyte correspondiente. Una versión de , _wctomb_lcon mejoras de seguridad como se describe en Características de wctombseguridad de CRT.

Sintaxis

errno_t wctomb_s(
   int *pRetValue,
   char *mbchar,
   size_t sizeInBytes,
   wchar_t wchar
);
errno_t _wctomb_s_l(
   int *pRetValue,
   char *mbchar,
   size_t sizeInBytes,
   wchar_t wchar,
   _locale_t locale
);

Parámetros

pRetValue
Número de bytes o un código que indica el resultado.

mbchar
Dirección de un carácter multibyte.

sizeInBytes
Tamaño del búfer mbchar.

wchar
Carácter ancho que se va a convertir.

locale
Configuración regional que se va a usar.

Valor devuelto

Devuelve cero si se ejecuta correctamente; devuelve un código de error si se produce un error.

Condiciones de error

mbchar	sizeInBytes	Valor devuelto	pRetValue
NULL	>0	EINVAL	no modificado
cualquiera	>INT_MAX	EINVAL	no modificado
cualquiera	demasiado pequeño	EINVAL	no modificado

Si se produce alguna de las condiciones de error anteriores, se invoca al controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, wctomb devuelve EINVAL y establece errno en EINVAL.

El valor EILSEQ devuelto indica que el valor pasado a través del parámetro wchar no es un carácter ancho válido.

Comentarios

La función wctomb_s convierte su argumento wchar en el carácter multibyte correspondiente y almacena el resultado en mbchar. Puede llamar a la función desde cualquier ubicación de cualquier programa.

Si wctomb_s convierte el carácter ancho en un carácter multibyte, coloca el número de bytes (que nunca es mayor que MB_CUR_MAX) en el carácter ancho en el entero al que apunta pRetValue. Si wchar es el carácter nulo ancho (L'\0'), wctomb_s rellena pRetValue con 1. Si el puntero mbchar de destino es NULL, wctomb_s coloca 0 en pRetValue. Si la conversión no es posible en la configuración regional actual, wctomb_s coloca -1 en pRetValue.

wctomb_s usa la configuración regional actual para la información dependiente de la configuración regional; _wctomb_s_l es igual, salvo que en su lugar usa la configuración regional pasada. Para obtener más información, vea Locale.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Requisitos

Routine	Encabezado necesario
wctomb_s	<stdlib.h>
_wctomb_s_l	<stdlib.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

Este programa muestra el comportamiento de la función wctomb_s.

// crt_wctomb_s.cpp
#include <stdio.h>
#include <stdlib.h>

int main( void )
{
    int i;
    wchar_t wc = L'a';
    char *pmb = (char *)malloc( MB_CUR_MAX );

    printf_s( "Convert a wide character:\n" );
    wctomb_s( &i, pmb, MB_CUR_MAX, wc );
    printf_s( "   Characters converted: %u\n", i );
    printf_s( "   Multibyte character: %.1s\n\n", pmb );
}

Convert a wide character:
   Characters converted: 1
   Multibyte character: a

Consulte también

Conversión de datos
Configuración regional
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
WideCharToMultiByte