wcrtomb_s

Artículo
06/09/2015

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

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

[out] pReturnValue
Devuelve el número de bytes escritos o -1 si se ha producido un error.
[out] mbchar
El carácter convertidos multibyte resultante.
[in] sizeOfmbchar
El tamaño de la variable de mbchar en bytes.
[in] wchar
Un carácter ancho a convertir.
[in] mbstate
Puntero a un objeto mbstate_t.

Valor devuelto

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

Comentarios

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

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

La función de wcrtomb_s diferencia de wctomb_s, _wctomb_s_l por su restartability. Almacena el estado de la conversión en mbstate para las llamadas subsiguientes igual o a otras funciones reiniciables. Los resultados son indefinidos al mezclar el uso de funciones reiniciables y nonrestartable. Por ejemplo, una aplicación utilizaría wcsrlen en lugar de wcslen, si una llamada subsiguiente a wcsrtombs_s se utilizó en lugar de wcstombs_s.

En C++, mediante esta función es simplificado con sobrecargas de plantilla; las sobrecargas pueden deducir la longitud de búfer automáticamente (que elimina la necesidad de especificar un argumento de tamaño) y automáticamente pueden reemplazar anterior, funciones de no Secure con sus más recientes, seguros homólogos. Para obtener más información, vea Sobrecargas de plantilla seguras.

Excepciones

La función de wcrtomb_s es seguro multiproceso a ninguna función en el subproceso actual llame a setlocale mientras esta función se ejecuta y mbstate es null.

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");
    }
}