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

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.