Compartir a través de

wcstombs_s, _wcstombs_s_l

  • Artículo

Convierte una secuencia de caracteres anchos en una secuencia correspondiente de caracteres multibyte. Una versión de , _wcstombs_lcon mejoras de seguridad como se describe en Características de wcstombsseguridad de CRT.

Sintaxis

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count
);

errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);

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

template <size_t size>
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // 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 van a almacenar en el búfer mbstr, sin incluir el carácter nulo de terminación, o _TRUNCATE.

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.

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álido 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 wcstombs_s convierte una cadena de caracteres anchos a la que apunta wcstr en caracteres multibyte almacenados en el búfer al que apunta mbstr. 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, wcstombs_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 la cadena se trunca, el valor devuelto es STRUNCATE y la conversión se considera correcta.

Si wcstombs_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 wcstombs_s encuentra un carácter ancho que no puede convertir en un carácter multibyte, coloca 0 en , establece el búfer de destino en *ReturnValueuna cadena vacía, establece en errno EILSEQy devuelve EILSEQ.

Si las secuencias señaladas por wcstr y mbstr se superponen, el comportamiento de wcstombs_s no está definido.

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.

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

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

Requisitos

Routine Encabezado necesario
wcstombs_s <stdlib.h>

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

Ejemplo

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

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t i;
    char *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    const wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,
               pWCBuffer, (size_t)BUFFER_SIZE - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n", pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
        free(pMBBuffer);
    }
    
    return 0;
}

Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

Consulte también

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