NOMBRE¶
mbsrtowcs - convierte una cadena multibyte a una cadena de caracteres anchos
SINOPSIS¶
#include <wchar.h>
size_t mbsrtowcs (wchar_t *dest, const char **src,
size_t len, mbstate_t *ps);
DESCRIPCIÓN¶
Si
dest no es un puntero NULL, la función
mbsrtowcs
convierte la cadena multibyte
*src a una cadena de caracteres anchos
que comienza en
dest. Como mucho, se escriben
len caracteres
anchos en
dest. El estado de cambios
*ps se actualiza. La
conversión se realiza en realidad llamando repetidamente a mbrtowc(
dest,
*src,
n,
ps), donde
n es algún
número positivo tal que esta llamada tenga éxito, e
incrementando a continuación
dest en uno y
*src en el
número de bytes consumidos. La conversión se puede detener por
tres razones:
1. Se encuentar una secuencia multibyte inválida. En este caso se deja
*src apuntando a la secuencia multibyte inválida, la
función devuelve (size_t)(-1) y se asigna a
errno el valor
EILSEQ.
2. Se han almacenado
len caracteres anchos distintos de L'\0' en
dest. En este caso,
*src se deja apuntado a la siguiente
secuencia multibyte a convertir y la función devuelve el número
de caracteres anchos escritos en
dest.
3. Se ha convertido completamente la cadena multibyte, incluyendo el
carácter terminador '\0' (que tiene el efecto colateral de devolver a
*ps al estado inicial). En este caso, se asigna a
*src el valor
NULL y la función devuelve el número de caracteres anchos
escritos en
dest, excluyendo el carácter terminador L'\0'.
Si
dest es NULL, se ignora
len y la conversión procede como
antes salvo que no se escriben en memoria los caracteres anchos obtenidos y
que no existe límite en la longitud.
En los dos casos anteriores, si
ps es un puntero NULL, se utiliza en su
lugar un estado anónimo privado, sólo conocido por la
función
mbsrtowcs.
El programador debe garantizar que hay espacio suficiente en
dest para,
al menos,
len caracteres anchos.
VALOR DEVUELTO¶
La función
mbsrtowcs devuelve el número de caracteres
anchos que componen la parte convertida de la cadena de caracteres anchos, sin
incluir el carácter ancho terminador nulo. Si se encuentra una
secuencia multibyte inválida, se devuelve (size_t)(-1) y se asigna a
errno el valor
EILSEQ.
ISO/ANSI C, UNIX98
VÉASE TAMBIÉN¶
mbstowcs(3),
mbsnrtowcs(3),
iconv(3)
OBSERVACIONES¶
El comportamiento de
mbsrtowcs depende de la categoría LC_CTYPE de
la localización actual.
Pasar NULL como valor de
ps no es seguro en un entorno multihilos.