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.