mbstowcs_s, _mbstowcs_s_l

 

Para obtener la documentación más reciente de Visual Studio 2017 RC, consulte Documentación de Visual Studio 2017 RC.

Convierte una secuencia de caracteres multibyte en una secuencia de caracteres anchos correspondiente. Versiones de mbstowcs, _mbstowcs_l con mejoras de seguridad, como se describe en características de seguridad de CRT.

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

Parámetros

[out] pReturnValue
El número de caracteres convertidos.

[out] wcstr
Dirección del búfer de la cadena de caracteres anchos convertido resultante.

[in] sizeInWords
El tamaño de la wcstr búfer en palabras.

[in]mbstr
La dirección de una secuencia de null terminó caracteres multibyte.

[in] count
El número máximo de caracteres anchos a almacenar en el wcstr búfer, sin incluir el carácter null, o _TRUNCATE.

[in] locale
Configuración regional que se va a usar.

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

Condición de errorValor devuelto y errno
wcstris NULL and sizeInWords > 0EINVAL
mbstr es NULLEINVAL
El búfer de destino es demasiado pequeño para contener la cadena convertida (a menos que count es _TRUNCATE; vea la sección comentarios que aparece a continuación)ERANGE
wcstris not NULL and sizeInWords == 0EINVAL

Si ocurre alguna de estas condiciones, se invoca la excepción de parámetro no válido como se describe en validación del parámetro . 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.

El mbstowcs_s función convierte una cadena de caracteres multibyte señalada mbstr en caracteres anchos almacenados en el búfer señalado por wcstr. La conversión continuará para cada carácter hasta que se cumpla alguna de estas condiciones:

  • Se encuentra un carácter multibyte nulo

  • Se encuentra un carácter multibyte no válido

  • El número de caracteres anchos almacenados en el búfer wcstr es igual a count.

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

Si count es el valor especial _TRUNCATE, a continuación, mbstowcs_s convierte tanto de la cadena como caber en el búfer de destino, dejando espacio para un terminador null.

Si mbstowcs_s convierte correctamente la cadena de origen, pone el tamaño en caracteres anchos de la cadena convertida, incluido el terminador nulo, en *``pReturnValue (proporcionan pReturnValue no es NULL). Esto ocurre incluso si la wcstr argumento es NULL y proporciona una manera de determinar el tamaño de búfer necesario. Observe que si wcstr es NULL, count se omite, y sizeInWords debe ser 0.

Si mbstowcs_s encuentra un carácter multibyte no válido, coloca un 0 en *``pReturnValue, Establece el búfer de destino en una cadena vacía, establece errno a EILSEQy devuelve EILSEQ.

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

System_CAPS_ICON_important.jpg Importante

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

mbstowcs_sutiliza la configuración regional actual para cualquier comportamiento dependiente de la configuración regional; _mbstowcs_s_l es idéntico, salvo que usa la configuración regional que se pasa en su lugar. 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, consulta Secure Template Overloads.

RutinaEncabezado necesario
mbstowcs_s<stdlib.h>
_mbstowcs_s_l<stdlib.h>

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

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.

Conversión de datos
Configuración regional
MultiByteToWideChar
Interpretación de secuencias de caracteres Multibyte
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l

Mostrar: