NOMBRE

       mbstowcs - convierte una cadena multibyte en una cadena de caracteres anchos

SINOPSIS

       #include <stdlib.h>

       size_t mbstowcs (wchar_t *dest, const char *src, size_t n);

DESCRIPCIÓN

       Si  dest  no  es  un  puntero NULL, la función mbstowcs convierte la cadena multibyte src a una cadena de
       caracteres anchos que comienza en dest.  Como  mucho,  se  escriben  n  caracteres  anchos  en  dest.  La
       conversión comienza en el estado inicial. La conversión se puede detener por tres razones:

       1. Se ha encontrado una secuencia multibyte inválida. Es este caso, la función devuelve (size_t)(-1).

       2.  Se han almacenado n caracteres anchos distintos de L'\0' en dest. En este caso, se devuelve el número
       de caracteres anchos escritos en dest, aunque el estado de cambios, en este punto, se pierde.

       3. Se ha convertido toda la cadena multibyte, incluyendo el  '\0'  que  la  termina.  En  esta  caso,  se
       devuelve el número de caracteres anchos escritos en dest, excluyendo el carácter L'\0' terminador.

       El programador debe asegurar que hay espacio en dest para, al menos, n caracters anchos.

       Si  dest  es  NULL,  n  se  ignora,  y  la conversión procede como antes, salvo que los caracteres anchos
       obtenidos no se escriben en memoria y que no hay límite de longitud.

       Para evitar el caso 2 anterior, el programador  debería  asegurarse  de  que  n  es  mayor  o  igual  que
       mbstowcs(NULL,src,0)+1.

VALOR DEVUELTO

       La función mbstowcs devuelve el número de caracteres anchos que componen la parte convertida de la cadena
       de  caracteres  anchos,  sin  incluir  el  carácter  ancho nulo terminador. Si se encuentra una secuencia
       multibyte inválida, devuelve (size_t)(-1).

CONFORME A

        ISO/ANSI C, UNIX98

VÉASE TAMBIÉN

       mbsrtowcs(3)

OBSERVACIONES

       El comportamiento de mbstowcs depende de la categoría LC_CTYPE de la localización actual.

       La función mbsrtowcs proporciona una interfaz mejor con la misma funcionalidad.

GNU                                               25 julio 1999                                      MBSTOWCS(3)