NOMBRE

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

SINOPSIS

       #include <wchar.h>

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

DESCRIPCIÓN

       Si  dest  no  es  un  puntero NULL, la función wcsrtombs convierte 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. 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 wcsrtombs 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

       ISO/ANSI C, UNIX98

VÉASE TAMBIÉN

       wcstombs(3), wcsnrtombs(3), iconv(3)

OBSERVACIONES

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

       Pasar NULL como ps no es seguro en entornos multihilo.