mbstowcs_s, _mbstowcs_s_l

Artículo
02/19/2013

Convierte una secuencia de caracteres multibyte en una secuencia de caracteres anchos correspondiente.Las versiones de mbstowcs, _mbstowcs_l con las mejoras de seguridad como se describe en Características de seguridad en 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
Convierte el número de caracteres.
[out] wcstr
Convertir la dirección del búfer para el resultado de cadena de caracteres anchos.
[in] sizeInWords
El tamaño de la wcstr búfer sin comprobar en las palabras.
[in]mbstr
La dirección de una secuencia de null termina con caracteres multibyte.
[in] count
El número máximo de caracteres anchos para almacenar en el wcstr búfer, sin incluir el valor null de terminación, o _TRUNCATE.
[in] locale
La configuración regional que utilice.

Valor devuelto

Cero si se realiza correctamente, un código de error en caso de error.

Condición de error	Valor devuelto yerrno
wcstris NULL and sizeInWords > 0	EINVAL
El valor de mbstr es NULL.	EINVAL
El búfer de destino es demasiado pequeño para contener la cadena convertida (a menos que count es _TRUNCATE; Consulte la sección comentarios a continuación)	ERANGE
wcstris not NULL and sizeInWords == 0	EINVAL

Si se produce cualquiera 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 la ejecución para continuar, la función devuelve un código de error y establece errno como se indica en la tabla.

Comentarios

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

Se ha encontrado un null de caracteres multibyte
Se encontró un carácter multibyte no válido
El número de caracteres anchos almacenados en el wcstr de búfer es igual a count.

La cadena de destino es siempre 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 se encajan en el búfer de destino, dejando espacio para un terminador null.

Si mbstowcs_s correctamente convierte la cadena de origen, pone el tamaño en caracteres anchos de la cadena convertida, incluido el terminador null, en *pReturnValue (proporcionado pReturnValue no es NULL).Esto ocurre incluso si la wcstr es el argumento NULL y proporciona una manera de determinar el tamaño de búfer requerido.Note that if wcstr is NULL, count is ignored, and sizeInWords must be 0.

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

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

Nota sobre la seguridad
Asegúrese de que wcstr y mbstr no se superponen y que count refleja el número de caracteres multibyte para convertir correctamente.

mbstowcs_sutiliza la configuración regional actual para cualquier comportamiento dependientes de la configuración regional; _mbstowcs_s_les idéntico salvo que utiliza la configuración regional que se pasa en su lugar.Para obtener más información, vea Configuración regional.

En C++, se simplifica utilizando estas funciones las sobrecargas de plantilla; las sobrecargas pueden inferir automáticamente longitud del búfer (lo que elimina la necesidad de especificar un argumento de tamaño) y automáticamente pueden reemplazar las funciones más antiguas y no seguras con sus equivalentes más recientes y seguras.Para obtener más información, vea Sobrecargas de plantilla de seguridad.