Compartir a través de


wcstombs_s, _wcstombs_s_l

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

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

  • [out] pReturnValue
    El número de caracteres convertido.

  • [out] mbstr
    La dirección de un búfer para producir convirtió la cadena de caracteres multibyte.

  • [in]sizeInBytes
    Tamaño en bytes del búfer de mbstr .

  • [in] wcstr
    Apunta a la cadena de caracteres anchos que se va a convertir.

  • [in] count
    El número máximo de caracteres anchos que se almacenan en el búfer de mbstr , sin incluir el carácter null de terminación, o _TRUNCATE.

  • [in] 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

El valor de wcstr es NULL.

EINVAL

El búfer de destino es demasiado pequeño para contener la cadena convertida (a menos que count es _TRUNCATE; vea las notas siguiente)

ERANGE

Si cualquiera de estas condiciones aparecen, la excepción no válida de parámetros se invoca como se describe en Validación de parámetros . Si la ejecución puede continuar, la función devuelve un código de error y establece errno como se indica en la tabla.

Comentarios

La función de wcstombs_s convierte una cadena de caracteres anchos indicada por wcstr en caracteres multibyte almacenados en el búfer indicada por mbstr. La conversión continuará por cada carácter hasta que una de estas condiciones se cumple:

  • Se encuentra un carácter ancho null

  • Se encuentra un carácter ancho que no puede convertirse

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

La cadena de destino siempre es terminada en null (incluso en el caso de un error).

Si count es el valor especial _TRUNCATE, después wcstombs_s convierte tanto de la cadena que caben en el búfer de destino, mientras todavía deja el sitio para un carácter null final.

Si wcstombs_s convierte correctamente la cadena de origen, coloca el tamaño en bytes de la cadena convertida, incluido el terminador nulo, en *pReturnValue ( pReturnValue proporcionado no es NULL). Esto hace que incluso si el argumento de mbstr es NULL y proporciona una manera de determinar el tamaño de búfer requerido. Tenga en cuenta que si mbstr es NULL, count se omite.

Si wcstombs_s encuentra un carácter ancho que no puede convertir un carácter multibyte, coloca 0 en *pReturnValue, establece el búfer de destino en una cadena vacía, establece errno a EILSEQ, y devuelve EILSEQ.

Si las secuencias designadas por a wcstr y la superposición de mbstr , el comportamiento de wcstombs_s no están definidas.

Nota de seguridadNota sobre la seguridad

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

wcstombs_s utiliza la configuración regional actual para cualquier comportamiento configuración regional-dependiente; _wcstombs_s_l es idéntico a wcstombs pero utiliza la configuración regional pasado en su lugar. Para obtener más información, vea Configuración regional.

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 la necesidad 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, vea Sobrecargas de plantilla seguras.

Requisitos

Rutina

Encabezado necesario

wcstombs_s

<stdlib.h>

Para obtener información adicional de compatibilidad, vea Compatibilidad en la Introducción.

Ejemplo

Este programa muestra el comportamiento de la función de 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 );
    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 );

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

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

Equivalente en .NET Framework

No es aplicable Para llamar a la función estándar de C, use PInvoke. Para obtener más información, vea Ejemplos de invocación de plataforma.

Vea también

Referencia

Conversión de datos

Configuración regional

_mbclen, mblen, _mblen_l

mbstowcs, _mbstowcs_l

mbtowc, _mbtowc_l

wctomb_s, _wctomb_s_l

WideCharToMultiByte