Provided by:
manpages-es_1.55-10_all 
NOMBRE
mbrtowc - convierte una secuencia multibyte a un caracter ancho
SINOPSIS
#include <wchar.h>
size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);
DESCRIPCI'ON
El principal caso para esta funcion se da cuando s no es NULL y pwc no
es NULL. En este caso, la funcion mbrtowc inspecciona, como mucho, n
bytes de la cadena multibyte que comienza en s, extrae el siguiente
caracter multibyte completo, lo convierte a un caracter ancho y lo
almacena en *pwc. La funcion actualiza el estado de cambios *ps. Si el
caracter ancho obtenido no es L'\0', devuelve el numero de bytes que se
han consumido de s. Si el caracter 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 caracter 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 invalida antes del siguiente caracter 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 funcion mbrtowc se comporta como antes, excepto que no
almacena el caracter 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 conversion representado por *ps indica una
conversion incompleta de caracteres multibyte, la funcion mbrtowc
devuelve (size_t)(-1), asigna a errno el valor EILSEQ, y deja *ps en un
estado indefinido. En otro caso, la funcion 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 anonimo privado solo conocido por la funcion mbrtowc. En
caso contrario, *ps debe ser un objeto mbstate_t valido. Un objeto
mbstate_t a puede ser incializado al estado inicial rellenandolo con
ceros, usando por ejemplo:
memset(&a, 0, sizeof(a));
VALOR DEVUELTO
La funcion mbrtowc devuelve el numero de bytes analizados de la
secuencia multibyte que comienza en s, si se ha reconocido un caracter
ancho distinto de L'\0'. Devuelve 0 si se ha reconocido un caracter
ancho L'\0'. Devuelve (size_t)(-1) y asigna a errno el valor EILSEQ si
se ha encontrado una secuencia multibyte invalida. Devuelve
(size_t)(-2) si no se ha podido analizar un caracter multibyte
completo, indicando esto que se deberia incrementar n.
CONFORME A
ISO/ANSI C, UNIX98
V'EASE TAMBI'EN
mbsrtowcs(3)
OBSERVACIONES
El comportamiento de mbrtowc depende de la categoria LC_CTYPE de la
localizacion actual.