NOMBRE

       mbsrtowcs - convierte una cadena multibyte a una cadena de caracteres anchos

SINOPSIS

       #include <wchar.h>

       size_t mbsrtowcs (wchar_t *dest, const char **src,
                         size_t len, mbstate_t *ps);

DESCRIPCIÓN

       Si  dest  no es un puntero NULL, la función mbsrtowcs convierte la cadena multibyte *src a
       una cadena de caracteres anchos  que  comienza  en  dest.  Como  mucho,  se  escriben  len
       caracteres anchos en dest. El estado de cambios *ps se actualiza. La conversión se realiza
       en realidad llamando repetidamente a mbrtowc(dest,*src,n,ps),  donde  n  es  algún  número
       positivo  tal  que  esta llamada tenga éxito, e incrementando a continuación dest en uno y
       *src en el número de bytes consumidos. La conversión se puede detener por tres razones:

       1. Se encuentar una secuencia multibyte inválida. En este caso se deja *src apuntando a la
       secuencia  multibyte  inválida,  la  función  devuelve (size_t)(-1) y se asigna a errno el
       valor EILSEQ.

       2. Se han almacenado len caracteres anchos distintos de L'\0' en dest. En este caso,  *src
       se  deja  apuntado a la siguiente secuencia multibyte a convertir y la función devuelve el
       número de caracteres anchos escritos en dest.

       3. Se ha convertido completamente la cadena multibyte, incluyendo el  carácter  terminador
       '\0' (que tiene el efecto colateral de devolver a *ps al estado inicial). En este caso, se
       asigna a *src el valor NULL y la función devuelve el número de caracteres anchos  escritos
       en dest, excluyendo el carácter terminador L'\0'.

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

       En los dos casos anteriores, si ps es un puntero NULL, se utiliza en su  lugar  un  estado
       anónimo privado, sólo conocido por la función mbsrtowcs.

       El  programador  debe  garantizar  que  hay espacio suficiente en dest para, al menos, len
       caracteres anchos.

VALOR DEVUELTO

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

CONFORME A

       ISO/ANSI C, UNIX98

VÉASE TAMBIÉN

       mbstowcs(3), mbsnrtowcs(3), iconv(3)

OBSERVACIONES

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

       Pasar NULL como valor de ps no es seguro en un entorno multihilos.