NOMBRE

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

SINOPSIS

       #include <wchar.h>

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

DESCRIPCIÓN

       La  función mbsnrtowcs es como la función mbsrtowcs, salvo que el número de bytes a convertir, comenzando
       en *src, está limitado a nms.

       Si dest no es un puntero NULL, la función mbsnrtowcs convierte,  como  mucho,  nms  bytes  de  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 incrementa a continuación dest en uno  y  *src  en  el  número  de  bytes  consumidos.  La
       conversión se puede detener por tres motivos:

       1.  Se ha encontrado 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. El límite nms fuerza una parada, o se han almacenado len caracteres anchos distintos de L'\0' en dest.
       En este caso, se deja *src apuntando 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 esta caso, se asigna a *src un 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  los  caracteres  anchos
       obtenidos no se escriben en memoria y que no existe límite de longitud en el destino.

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

       Los programadores deben garantizar que hay espacio suficiente en dest  para,  al  menos,  len  caracteres
       anchos.

VALOR DEVUELTO

       La  función  mbsnrtowcs  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, la función devuelve (size_t)(-1) y asigna a errno el valor EILSEQ.

CONFORME A

       Esta función es una extensión de GNU.

VÉASE TAMBIÉN

       mbsrtowcs(3), iconv(3)

OBSERVACIONES

       El comportamiento de mbsnrtowcs 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                                    MBSNRTOWCS(3)