mbstowcs_s, _mbstowcs_s_l

Artículo
06/09/2015

Convierte una secuencia de caracteres multibyte en una secuencia correspondiente de caracteres anchos. 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 convertido.
[out] wcstr
La dirección de búfer para producir convirtió la cadena de caracteres anchos.
[in] sizeInWords
El tamaño del búfer de wcstr en palabras.
[in]mbstr
La dirección de una secuencia de null finalizó caracteres multibyte.
[in] count
El número máximo de caracteres anchos a almacenar en el búfer de wcstr , sin incluir la null final, 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
wcstr es NULL y 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; vea las notas siguiente)	ERANGE
wcstr no es NULL y == 0 de sizeInWords	EINVAL

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 mbstowcs_s convierte una cadena de caracteres multibyte indicada por mbstr en los caracteres anchos almacenados en el búfer indicada por wcstr. La conversión continuará por cada carácter hasta que una de estas condiciones se cumple:

Se encuentra un carácter null multibyte
Se encuentra un carácter no válido multibyte
El número de caracteres anchos almacenados en el búfer de wcstr 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 mbstowcs_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 mbstowcs_s convierte correctamente la cadena de origen, coloca el tamaño en caracteres anchos de la cadena convertida, incluido el terminador nulo, en *pReturnValue ( pReturnValue proporcionado no es NULL). Esto hace que incluso si el argumento de wcstr es NULL y proporciona una manera de determinar el tamaño de búfer requerido. Tenga en cuenta que si wcstr es NULL, count se omite, y sizeInWords debe ser 0.

Si mbstowcs_s encuentra un carácter no válido 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 mbstr y la superposición de wcstr , el comportamiento de mbstowcs_s no están definidas.

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

mbstowcs_s utiliza la configuración regional actual para cualquier comportamiento configuración regional-dependiente; _mbstowcs_s_l es idéntico 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.