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.