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.