Provided by:
manpages-es_1.55-3_all 
NOMBRE
mbrtowc - convierte una secuencia multibyte a un carácter ancho
SINOPSIS
#include <wchar.h>
size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);
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 mbrtowc inspecciona, como mucho, n
bytes de la cadena multibyte que comienza en s, extrae el siguiente
carácter multibyte completo, lo convierte a un carácter ancho y lo
almacena en *pwc. La función actualiza el estado de cambios *ps. Si el
carácter ancho obtenido no es L’\0’, devuelve el número de bytes que se
han consumido de s. Si el carácter ancho obtenido es L’\0’, restablece
el estado de cambios *ps al estado inicial y devuelve 0.
Si los n bytes que comienzan en s no contienen un carácter multibyte
completo, mbrtowc devuelve (size_t)(-2). Esto puede ocurrir incluso si
n >= MB_CUR_MAX, si la cadena multibyte contiene secuencias de cambios
redundantes.
Si la cadena multibyte que comienza en s contiene una secuencia
multibyte inválida antes del siguiente carácter completo, mbrtowc
devuelve (size_t)(-1) y asigna a errno el valor EILSEQ. En este caso,
los efectos sobre *ps son indefinidos.
Un caso diferente se da cuando s no es NULL pero pwc es NULL. En este
caso, la función mbrtowc se comporta como antes, excepto que 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. Si el estado de conversión representado por *ps indica una
conversión incompleta de carácteres multibyte, la función mbrtowc
devuelve (size_t)(-1), asigna a errno el valor EILSEQ, y deja *ps en un
estado indefinido. En otro caso, la función mbrtowc coloca *ps en el
estado inicial y devuelve 0.
En todos los casos anteriores, si ps es un puntero NULL, en su lugar se
usa un estado anónimo privado sólo conocido por la función mbrtowc. En
caso contrario, *ps debe ser un objeto mbstate_t válido. Un objeto
mbstate_t a puede ser incializado al estado inicial rellenándolo con
ceros, usando por ejemplo:
memset(&a, 0, sizeof(a));
VALOR DEVUELTO
La función mbrtowc devuelve el número de bytes analizados de la
secuencia multibyte que comienza en s, si se ha reconocido un carácter
ancho distinto de L’\0’. Devuelve 0 si se ha reconocido un carácter
ancho L’\0’. Devuelve (size_t)(-1) y asigna a errno el valor EILSEQ si
se ha encontrado una secuencia multibyte inválida. Devuelve
(size_t)(-2) si no se ha podido analizar un carácter multibyte
completo, indicando esto que se debería incrementar n.
CONFORME A
ISO/ANSI C, UNIX98
VÉASE TAMBIÉN
mbsrtowcs(3)
OBSERVACIONES
El comportamiento de mbrtowc depende de la categoría LC_CTYPE de la
localización actual.