.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" References consulted:
.\"   GNU glibc-2 source code and manual
.\"   Dinkumware C library reference http://www.dinkumware.com/
.\"   OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
.\"   ISO/IEC 9899:1999
.\"
.\" Translated into Spanish Tue Mar  3 15:21:17 CET 1998 by Gerardo
.\" Aburruzaga García <gerardo.aburruzaga@uca.es>
.\" Translation revised Sun Aug  6 2000 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH MBSTOWCS 3  "25 julio 1999" "GNU" "Manual del Programador de linux"
.SH NOMBRE
mbstowcs \- convierte una cadena multibyte en una cadena de caracteres
anchos
.SH SINOPSIS
.nf
.B #include <stdlib.h>
.sp
.BI "size_t mbstowcs (wchar_t *" dest ", const char *" src ", size_t " n );
.fi
.SH DESCRIPCIÓN
Si \fIdest\fP no es un puntero NULL, la función \fBmbstowcs\fP convierte la
cadena multibyte \fIsrc\fP a una cadena de caracteres anchos que comienza en
\fIdest\fP.
Como mucho, se escriben \fIn\fP caracteres anchos en \fIdest\fP. La
conversión comienza en el estado inicial. La conversión se puede detener por
tres razones:
.PP
1. Se ha encontrado una secuencia multibyte inválida. Es este caso, la
función devuelve (size_t)(-1).
.PP
2. Se han almacenado \fIn\fP caracteres anchos distintos de L'\\0' en
\fIdest\fP. En este caso, se devuelve el número de caracteres anchos
escritos en \fIdest\fP, aunque el estado de cambios, en este punto, se
pierde.
.PP
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 \fIdest\fP, excluyendo el carácter L'\\0' terminador.
.PP
El programador debe asegurar que hay espacio en \fIdest\fP para, al menos,
\fIn\fP caracters anchos.
.PP
Si \fIdest\fP es NULL, \fIn\fP 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.
.PP
Para evitar el caso 2 anterior, el programador debería asegurarse de que
\fIn\fP es mayor o igual que \fImbstowcs(NULL,src,0)+1\fP.
.SH "VALOR DEVUELTO"
La función \fBmbstowcs\fP 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).
.SH "CONFORME A"
 ISO/ANSI C, UNIX98
.SH "VÉASE TAMBIÉN"
.BR mbsrtowcs (3)
.SH OBSERVACIONES
El comportamiento de \fBmbstowcs\fP depende de la categoría LC_CTYPE de la
localización actual.
.PP
La función \fBmbsrtowcs\fP proporciona una interfaz mejor con la misma
funcionalidad.