NOMBRE

       wcsnrtombs - convierte una cadena de caracteres anchos a una cadena mulibyte

SINOPSIS

       #include <wchar.h>

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

DESCRIPCIÓN

       La función wcsnrtombs es como la función wcsrtombs, salvo que el número de caracteres anchos a convertir,
       empezando en *src, está limitado a nwc.

       Si  dest  no  es  un  puntero NULL, la función wcsnrtombs convierte a lo sumo nwc caracteres anchos de la
       cadena de caracteres anchos *src en una cadena multibyte comenzando en dest.  En dest se  escriben,  como
       mucho,  len  bytes.   El  estado  de  cambios *ps se acualiza. La conversión se realiza de forma efectiva
       llamando repetidamente a wcrtomb(dest,*src,ps), tantas veces como la llamada sea efectiva e incrementando
       dest con el número de bytes escritos y *src en uno. La conversión puede pararse por tres razones:

       1. Se ha encontrado un carácter ancho que no se  puede  representar  como  una  secuencia  multibyte  (de
       acuerdo  con  la localización actual). En este caso *src se deja apuntando al carácter ancho inválido, se
       devuelve (size_t)(-1) y errno toma el valor EILSEQ.

       2. Se han convertido nwc caracteres anchos sin encontrar un  L'\0', o el límite  de  longitud  fuerza  la
       parada.  En  este  caso  *src  se deja apuntando al siguiente carácter ancho para convertir y devuelve el
       número de bytes escritos en dest.

       3. Se ha completado la conversión de la cadena de caracteres anchos,  incluyendo  la  terminación   L'\0'
       (que  tiene  el efecto de devolver *ps al estado inicial). En este caso *src se pone como NULL y devuelve
       el número de bytes escritos en dest, excluyendo el byte terminador '\0'.

       Si dest es NULL, len se ignora, y la conversión procede como arriba, salvo que los bytes  convertidos  no
       se escriben en memoria, y no existe límite de longitud.

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

       El programador tiene que asegurarse de que hay espacio para al menos len bytes en dest.

VALOR DEVUELTO

       La función wcsnrtombs devuelve el número de bytes que  conforman  la  parte  de  la  secuencia  multibyte
       convertida,  sin  incluir  el  byte nulo terminador. Si encontró un carácter ancho que no pudo convertir,
       devuelve (size_t)(-1) y errno toma el valor EILSEQ.

CONFORME A

       Esta función es una extensión GNU.

VÉASE TAMBIÉN

       wcsrtombs(3), iconv(3)

OBSERVACIONES

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

       Pasar NULL como ps no es seguro en entornos multihilo.

GNU                                               25 julio 1999                                    WCSNRTOMBS(3)