Provided by: manpages-es_1.55-3_all bug

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.