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.
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.