mbstowcs_s, _mbstowcs_s_l

Convertir una secuencia de caracteres multibyte en una secuencia correspondiente de caracteres anchos. Versiones de , _mbstowcs_lcon mejoras de seguridad como se describe en Características de mbstowcsseguridad de CRT.

Sintaxis

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

pReturnValue
El número de caracteres convertidos.

wcstr
Dirección del búfer para la cadena de caracteres anchos convertida.

sizeInWords
Tamaño del búfer wcstr en palabras.

mbstr
Dirección de una secuencia de caracteres multibyte terminados en nulo.

count
Número máximo de caracteres anchos a almacenar en el búfer wcstr, sin incluir el carácter nulo de finalizació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
wcstr es NULL y sizeInWords> 0	EINVAL
mbstr 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
wcstr no NULL es y sizeInWords == 0	EINVAL

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 mbstowcs_s convierte una cadena de caracteres multibyte a la que apunta mbstr en caracteres anchos almacenados en el búfer al que apunta 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 si se produce un error).

Si count es el valor especial _TRUNCATE, mbstowcs_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 mbstowcs_s convierte correctamente la cadena de origen, coloca el tamaño en caracteres anchos de la cadena convertida, incluido el terminador NULL, en *pReturnValue (proporcionado pReturnValue no NULLes ). El tamaño se calcula incluso si el wcstr argumento es NULLy proporciona una manera de determinar el tamaño de búfer necesario. Si wcstr es NULL, count se omite y sizeInWords debe ser 0.

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

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

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_s usa la configuración regional actual para cualquier comportamiento dependiente de la configuración regional; _mbstowcs_s_l es igual, 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
mbstowcs_s	<stdlib.h>
_mbstowcs_s_l	<stdlib.h>

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

Consulte también

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