.\" 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
.\"
.\" Translated Tue Apr 25 2000 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH MBSNRTOWCS 3  "25 julio 1999" "GNU" "Manual del Programador de Linux"
.SH NOMBRE
mbsnrtowcs \- convierte una cadena multibyte a una cadena de caracteres
anchos
.SH SINOPSIS
.nf
.B #include <wchar.h>
.sp
.BI "size_t mbsnrtowcs (wchar_t *" dest ", const char **" src ,
.BI "                   size_t " nms ", size_t " len ", mbstate_t *" ps );
.fi
.SH DESCRIPCIÓN
La función \fBmbsnrtowcs\fP es como la función \fBmbsrtowcs\fP, salvo que
el número de bytes a convertir, comenzando en \fI*src\fP, está limitado a
\fInms\fP.
.PP
Si \fIdest\fP no es un puntero NULL, la función \fBmbsnrtowcs\fP convierte,
como mucho, \fInms\fP bytes de 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 incrementa 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 motivos:
.PP
1. Se ha encontrado 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. El límite \fInms\fP fuerza una parada, o se han almacenado \fIlen\fP
caracteres anchos distintos de L'\\0' en \fIdest\fP. En este caso,
se deja \fI*src\fP apuntando 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 esta caso, se asigna a \fI*src\fP un 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 los caracteres anchos obtenidos no se escriben en memoria y
que no existe límite de longitud en el destino.
.PP
En los dos casos anteriores, si \fIps\fP es un puntero NULL pointer, en su
lugar se usa un estado anónimo privado, sólo conocido por la función
\fBmbsnrtowcs\fP.
.PP
Los programadores deben garantizar que hay espacio suficiente en \fIdest\fP
para, al menos, \fIlen\fP caracteres anchos.
.SH "VALOR DEVUELTO"
La función \fBmbsnrtowcs\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, la función devuelve (size_t)(-1) y asigna a \fBerrno\fP el valor
\fBEILSEQ\fP.
.SH "CONFORME A"
Esta función es una extensión de GNU.
.SH "VÉASE TAMBIÉN"
.BR mbsrtowcs "(3), " iconv (3)
.SH OBSERVACIONES
El comportamiento de \fBmbsnrtowcs\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.