wcsrtombs_s

Convierte una cadena de caracteres anchos en su representación de cadena de caracteres multibyte. Una versión de wcsrtombs con mejoras de seguridad, como se describe en Características de seguridad en CRT.

Sintaxis

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parámetros

pReturnValue
Tamaño en bytes de la cadena convertida, incluido el terminador nulo.

mbstr
Dirección de un búfer para la cadena de caracteres multibyte convertida resultante.

sizeInBytes
Tamaño del búfer mbstr en bytes.

wcstr
Apunta a la cadena de caracteres anchos que se va a convertir.

count
Número máximo de bytes que se almacenarán en el mbstr búfer o _TRUNCATE.

mbstate
Un puntero a un objeto mbstate_t de estado de la conversión.

Valor devuelto

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

Condición de error	Valor devuelto y errno
mbstr es NULL y sizeInBytes> 0	EINVAL
wcstr es NULL.	EINVAL
El búfer de destino es demasiado pequeño para contener la cadena convertida (a menos que count sea _TRUNCATE; vea la sección Comentarios a continuación)	ERANGE

Si se produce alguna de estas condiciones, se invoca la excepción de parámetro no válida como se describe en Validación de parámetros . Si se permite que la ejecución continúe, la función devuelve un código de error y establece errno como se indica en la tabla.

Comentarios

La función wcsrtombs_s convierte una cadena de caracteres anchos a la que apunta wcstr en caracteres multibyte almacenados en el búfer al que apunta mbstr, mediante el estado de conversión incluido en mbstate. La conversión continuará para cada carácter hasta que se cumpla alguna de estas condiciones:

• Se encuentre un carácter ancho nulo

• Se encuentra un carácter ancho que no se puede convertir.

• El número de bytes almacenados en el búfer mbstr sea igual a count.

La cadena de destino siempre está terminada en null (incluso si se produce un error).

Si count es el valor especial _TRUNCATE, wcsrtombs_s convierte la parte de la cadena que quepa en el búfer de destino, a la vez que deja espacio para un carácter null final.

Si wcsrtombs_s convierte correctamente la cadena de origen, coloca el tamaño en bytes de la cadena convertida, incluido el terminador NULL, en *pReturnValue (proporcionado pReturnValue no NULLes ). El tamaño se calcula incluso si el mbstr argumento es NULL; proporciona una manera de determinar el tamaño de búfer necesario. Si mbstr es NULL, count se omite.

Si wcsrtombs_s encuentra un carácter ancho que no puede convertir en un carácter multibyte, coloca -1 en , establece el búfer de destino en *pReturnValueuna cadena vacía, establece en errnoEILSEQy devuelve EILSEQ.

Si las secuencias señaladas por wcstr y mbstr se superponen, el comportamiento de wcsrtombs_s no está definido. wcsrtombs_s se ve afectado por la categoría LC_TYPE de la configuración regional actual.

Importante

Asegúrese de que wcstr y mbstr no se superpongan y de que count refleje correctamente el número de caracteres anchos que se van a convertir.

La wcsrtombs_s función difiere de wcstombs_s, _wcstombs_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 estas funciones se simplifica con las sobrecargas de plantilla; las sobrecargas pueden realizar una inferencia automáticamente de 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 wcsrtombs_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_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Requisitos

Routine	Encabezado necesario
wcsrtombs_s	<wchar.h>

Consulte también

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres multibyte
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit