NOMBRE
mbtowc − convierte una secuencia multibyte en un carácter ancho
SINOPSIS
#include <stdlib.h>
int mbtowc (wchar_t *pwc, const char *s, size_t n);
DESCRIPCIÓN
El principal caso para esta función se da cuando s no es NULL y pwc no es NULL. En este caso, la función mbtowc inspecciona, como mucho, n bytes de la cadena multibyte s, extrae el siguiente carácter multibyte completo, lo convierte a un carácter ancho y lo almacena en *pwc. Actualiza un estado de cambios interno sólo conocido por la función mbtowc. Si s no apunta aun byte ’\0’, la función devuelve el número de bytes consumidos de s. En otro caso, devuelve 0.
Si los primeros n bytes de s no contienen un carácter multibyte completo, o si contiene una secuencia multibyte inválida, mbtowc devuelve -1. Esto puede ocurrir incluso sif n >= MB_CUR_MAX, si la cadena multibyte contiene secuencias de cambios redundantes.
Un caso diferente se da cuando s no es NULL pero pwc sí lo es. En este caso, la función mbtowc se comporta como antes pero no almacena el carácter ancho obtenido en memoria.
Un tercer caso se da cuando s es NULL. En este caso, pwc y n se ignoran. La función mbtowc devuelve el estado de cambios, sólo conocido por esta función, a su estado inicial y devuelve un valor distinto de cero si la condificación posee un estado de cambios no trivial o cero si es una codificación sin estado.
VALOR DEVUELTO
Si s no es NULL, la función mbtowc devuelve el número de bytes consumidos de s, 0 si s apunta a un byte nulo o −1 en caso de fallo.
Si s es NULL, la función mbtowc devuelve un valor distinto de cero si la codificación posee un estado de cambios no trivial o cero si es una codificación sin estado.
CONFORME A
ISO/ANSI C, UNIX98
VÉASE TAMBIÉN
mbrtowc(3), mbstowcs(3), MB_CUR_MAX(3)
OBSERVACIONES
El comportamiento de mbtowc depende de la categoría LC_CTYPE de la localización actual.
Esta función no es segura en un entorno multihilos. La función mbrtowc proporciona una interfaz mejor con la misma funcionalidad.