Ubuntu manuals

Provided by: manpages-es_1.55-10_all

NOMBRE

       mbsrtowcs  -  convierte una cadena multibyte a una cadena de caracteres
       anchos

SINOPSIS

       #include <wchar.h>

       size_t mbsrtowcs (wchar_t *dest, const char **src,
                         size_t len, mbstate_t *ps);

DESCRIPCI'ON

       Si dest no es un puntero NULL, la funcion mbsrtowcs convierte la cadena
       multibyte  *src a una cadena de caracteres anchos que comienza en dest.
       Como mucho, se escriben len caracteres anchos en  dest.  El  estado  de
       cambios *ps se actualiza. La conversion se realiza en realidad llamando
       repetidamente  a  mbrtowc(dest,*src,n,ps),  donde  n  es  algun  numero
       positivo   tal   que  esta  llamada  tenga  exito,  e  incrementando  a
       continuacion dest en uno y *src en el numero de  bytes  consumidos.  La
       conversion se puede detener por tres razones:

       1.  Se encuentar una secuencia multibyte invalida. En este caso se deja
       *src apuntando a la secuencia multibyte invalida, la  funcion  devuelve
       (size_t)(-1) y se asigna a errno el valor EILSEQ.

       2.  Se han almacenado len caracteres anchos distintos de L'\0' en dest.
       En este caso, *src se deja apuntado a la siguiente secuencia  multibyte
       a  convertir  y  la  funcion  devuelve  el  numero de caracteres anchos
       escritos en dest.

       3. Se ha convertido completamente la cadena  multibyte,  incluyendo  el
       caracter  terminador  '\0' (que tiene el efecto colateral de devolver a
       *ps al estado inicial). En este caso, se asigna a *src el valor NULL  y
       la  funcion  devuelve  el numero de caracteres anchos escritos en dest,
       excluyendo el caracter terminador L'\0'.

       Si dest es NULL, se ignora len y la conversion procede como antes salvo
       que  no se escriben en memoria los caracteres anchos obtenidos y que no
       existe limite en la longitud.

       En los dos casos anteriores, si ps es un puntero NULL, se utiliza en su
       lugar   un  estado  anonimo  privado,  solo  conocido  por  la  funcion
       mbsrtowcs.

       El programador debe garantizar que hay espacio suficiente en dest para,
       al menos, len caracteres anchos.

VALOR DEVUELTO

       La  funcion  mbsrtowcs  devuelve  el  numero  de  caracteres anchos que
       componen la parte convertida de la cadena  de  caracteres  anchos,  sin
       incluir  el  caracter  ancho  terminador  nulo.  Si  se  encuentra  una
       secuencia multibyte invalida, se devuelve (size_t)(-1) y  se  asigna  a
       errno el valor EILSEQ.

CONFORME A

       ISO/ANSI C, UNIX98

V'EASE TAMBI'EN

       mbstowcs(3), mbsnrtowcs(3), iconv(3)

OBSERVACIONES

       El  comportamiento  de mbsrtowcs depende de la categoria LC_CTYPE de la
       localizacion actual.

       Pasar NULL como valor de ps no es seguro en un entorno multihilos.