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.