.\" 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 Tue Apr 25 2000 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH MBSRTOWCS 3  "25 julio 1999" "GNU" "Manual del Programador de Linux"
.SH NOMBRE
mbsrtowcs \- convierte una cadena multibyte a una cadena de caracteres anchos
.SH SINOPSIS
.nf
.B #include <wchar.h>
.sp
.BI "size_t mbsrtowcs (wchar_t *" dest ", const char **" src ,
.BI "                  size_t " len ", mbstate_t *" ps );
.fi
.SH DESCRIPCIÓN
Si \fIdest\fP no es un puntero NULL, la función \fBmbsrtowcs\fP convierte la
cadena multibyte \fI*src\fP a una cadena de caracteres anchos que comienza
en \fIdest\fP. Como mucho, se escriben \fIlen\fP caracteres anchos en
\fIdest\fP. El estado de cambios \fI*ps\fP se actualiza. La conversión se
realiza en realidad llamando repetidamente a
mbrtowc(\fIdest\fP,\fI*src\fP,\fIn\fP,\fIps\fP), donde \fIn\fP es algún
número positivo tal que esta llamada tenga éxito, e incrementando 
a continuación \fIdest\fP en uno y \fI*src\fP en el número de bytes
consumidos. La conversión se puede detener por tres razones:
.PP
1. Se encuentar una secuencia multibyte inválida. En este caso se deja
\fI*src\fP apuntando a la secuencia multibyte inválida, la función devuelve
(size_t)(-1) y se asigna a \fBerrno\fP el valor \fBEILSEQ\fP.
.PP
2. Se han almacenado \fIlen\fP caracteres anchos distintos de L'\\0' en
\fIdest\fP. En este caso, \fI*src\fP se deja apuntado a la siguiente
secuencia multibyte a convertir y la función devuelve el número de
caracteres anchos escritos en \fIdest\fP.
.PP
3. Se ha convertido completamente la cadena multibyte, incluyendo el
carácter terminador '\\0' (que tiene el efecto colateral de devolver a
\fI*ps\fP al estado inicial). En este caso, se asigna a \fI*src\fP el valor
NULL y la función devuelve el número de caracteres anchos escritos en
\fIdest\fP, excluyendo el carácter terminador L'\\0'.
.PP
Si \fIdest\fP es NULL, se ignora \fIlen\fP y la conversión procede como
antes salvo que no se escriben en memoria los caracteres anchos obtenidos y
que no existe límite en la longitud.
.PP
En los dos casos anteriores, si \fIps\fP es un puntero NULL, se utiliza en
su lugar un estado anónimo privado, sólo conocido por la función
\fBmbsrtowcs\fP.
.PP
El programador debe garantizar que hay espacio suficiente en \fIdest\fP para,
al menos, \fIlen\fP caracteres anchos.
.SH "VALOR DEVUELTO"
La función \fBmbsrtowcs\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 terminador nulo. Si se encuentra una secuencia multibyte
inválida, se devuelve (size_t)(-1) y se asigna a \fBerrno\fP el valor
\fBEILSEQ\fP.
.SH "CONFORME A"
ISO/ANSI C, UNIX98
.SH "VÉASE TAMBIÉN"
.BR mbstowcs "(3), " mbsnrtowcs "(3), " iconv (3)
.SH OBSERVACIONES
El comportamiento de \fBmbsrtowcs\fP depende de la categoría LC_CTYPE de la
localización actual.
.PP
Pasar NULL como valor de \fIps\fP no es seguro en un entorno multihilos.