wcrtomb_s

Convierte un carácter ancho en su representación de carácter multibyte. Una versión de wcrtomb con mejoras de seguridad, como se describe en Características de seguridad en CRT.

Sintaxis

errno_t wcrtomb_s(
   size_t *pReturnValue,
   char *mbchar,
   size_t sizeOfmbchar,
   wchar_t *wchar,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcrtomb_s(
   size_t *pReturnValue,
   char (&mbchar)[size],
   wchar_t *wchar,
   mbstate_t *mbstate
); // C++ only

Parámetros

pReturnValue
Devuelve el número de bytes escritos o -1 si se ha producido un error.

mbchar
Carácter convertido multibyte resultante.

sizeOfmbchar
Tamaño de la variable mbchar en bytes.

wchar
Carácter ancho que se va a convertir.

mbstate
Puntero a un objeto mbstate_t .

Valor devuelto

Devuelve cero o un valor errno si se produce un error.

Comentarios

La función wcrtomb_s convierte un carácter ancho, a partir del estado de conversión especificado incluido en mbstate, del valor incluido en wchar, en la dirección representada por mbchar. El valor pReturnValue será el número de bytes convertidos, pero no más de MB_CUR_MAX bytes, o -1 si se ha producido un error.

Si mbstate es nulo, se usa el estado de conversión interno mbstate_t. Si el carácter contenido en wchar no tiene un carácter multibyte correspondiente, el valor de pReturnValue es -1 y la función devuelve el errno valor de EILSEQ.

La wcrtomb_s función difiere de wctomb_s, _wctomb_s_l por su capacidad de reinicio. El estado de la conversión se almacena en mbstate para llamadas posteriores a la misma o a otras funciones reiniciables. Los resultados no están definidos cuando se combina el uso de funciones reiniciables y no reiniciables. Por ejemplo, una aplicación usaría wcsrlen en lugar de wcslen si se empleara una llamada subsiguiente a wcsrtombs_s en lugar de a wcstombs_s.

En C++, el uso de esta función se simplifica con las sobrecargas de plantilla; las sobrecargas pueden deducir automáticamente la longitud de búfer (lo que elimina el requisito de especificar un argumento de tamaño) y pueden reemplazar automáticamente funciones anteriores no seguras con sus homólogos seguros más recientes. Para obtener más información, consulte Sobrecargas de plantillas seguras.

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.

Excepciones

La función wcrtomb_s es segura para subprocesos siempre y cuando ninguna función del proceso actual llame a setlocale mientras se ejecuta esta función y mbstate sea nulo.

Ejemplo

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to a the "Q" multibyte character.

Requisitos

Routine	Encabezado necesario
wcrtomb_s	<wchar.h>

Consulte también

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres multibyte
mbsinit