NOMBRE

       mbstowcs - convierte una cadena multibyte en una cadena de caracteres anchos

SINOPSIS

       #include <stdlib.h>

       size_t mbstowcs (wchar_t *dest, const char *src, size_t n);

DESCRIPCIÓN

       Si dest no es un puntero NULL, la función mbstowcs convierte la cadena multibyte src a una
       cadena de caracteres anchos que comienza en dest.  Como mucho, se  escriben  n  caracteres
       anchos  en  dest.  La  conversión  comienza  en  el estado inicial. La conversión se puede
       detener por tres razones:

       1. Se ha encontrado una secuencia multibyte inválida. Es este caso,  la  función  devuelve
       (size_t)(-1).

       2.  Se  han  almacenado  n  caracteres anchos distintos de L'\0' en dest. En este caso, se
       devuelve el número de caracteres anchos escritos en dest, aunque el estado de cambios,  en
       este punto, se pierde.

       3.  Se  ha convertido toda la cadena multibyte, incluyendo el '\0' que la termina. En esta
       caso, se devuelve el número de caracteres anchos escritos en dest, excluyendo el  carácter
       L'\0' terminador.

       El programador debe asegurar que hay espacio en dest para, al menos, n caracters anchos.

       Si dest es NULL, n se ignora, y la conversión procede como antes, salvo que los caracteres
       anchos obtenidos no se escriben en memoria y que no hay límite de longitud.

       Para evitar el caso 2 anterior, el programador debería asegurarse de  que  n  es  mayor  o
       igual que mbstowcs(NULL,src,0)+1.

VALOR DEVUELTO

       La  función  mbstowcs  devuelve  el  número  de  caracteres  anchos  que componen la parte
       convertida de la  cadena  de  caracteres  anchos,  sin  incluir  el  carácter  ancho  nulo
       terminador. Si se encuentra una secuencia multibyte inválida, devuelve (size_t)(-1).

CONFORME A

        ISO/ANSI C, UNIX98

VÉASE TAMBIÉN

       mbsrtowcs(3)

OBSERVACIONES

       El comportamiento de mbstowcs depende de la categoría LC_CTYPE de la localización actual.

       La función mbsrtowcs proporciona una interfaz mejor con la misma funcionalidad.