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.

GNU                                               25 julio 1999                                     MBSRTOWCS(3)