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.

GNU                                             22 noviembre 2001                                     MBRTOWC(3)