.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" Traducida por Pedro Pablo Fábrega <pfabrega@arrakis.es>
.\" Esto es documentación libre; puede redistribuirla y/o
.\" modificarla bajo los términos de la Licencia Pública General GNU
.\" publicada por la Free Software Foundation; bien la versión 2 de
.\" la Licencia o (a su elección) cualquier versión posterior.
.\"
.\" Referencias consultadas:
.\"   código fuente y manual de glibc-2 GNU
.\"   referencia de la bibliote C Dinkumware http://www.dinkumware.com/
.\"   Especificaciones Single Unix de OpenGroup http://www.UNIX-systems.org/onl
.\"
.\" Translation revised Wed Aug  2 2000 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH WCSNRTOMBS 3  "25 julio 1999" "GNU" "Manual del Programador Linux"
.SH NOMBRE
wcsnrtombs \- convierte una cadena de caracteres anchos a una cadena mulibyte
.SH SINOPSIS
.nf
.B #include <wchar.h>
.sp
.BI "size_t wcsnrtombs (char *" dest ", const wchar_t **" src ", size_t " nwc ,
.BI "                   size_t " len ", mbstate_t *" ps );
.fi
.SH DESCRIPCIÓN
La función \fBwcsnrtombs\fP es como la función \fBwcsrtombs\fP, salvo 
que el número de caracteres anchos a convertir, empezando  
en \fI*src\fP, está limitado a \fInwc\fP.
.PP
Si \fIdest\fP no es un puntero NULL, la función \fBwcsnrtombs\fP convierte 
a lo sumo \fInwc\fP caracteres anchos de la cadena de caracteres 
anchos \fI*src\fP en una cadena multibyte comenzando en \fIdest\fP. 
En \fIdest\fP se escriben, como mucho, \fIlen\fP bytes.
El estado de cambios \fI*ps\fP se acualiza. La conversión se realiza
de forma efectiva llamando repetidamente a
wcrtomb(\fIdest\fP,\fI*src\fP,\fIps\fP), tantas veces como la 
llamada sea efectiva e incrementando \fIdest\fP con el 
número de bytes escritos y \fI*src\fP en uno. La conversión puede 
pararse por tres razones:
.PP
1. Se ha encontrado un carácter ancho que no se puede representar 
como una secuencia multibyte (de acuerdo con la localización actual). En este 
caso \fI*src\fP se deja apuntando al carácter ancho inválido, 
se devuelve (size_t)(-1) y \fBerrno\fP toma el valor \fBEILSEQ\fP.
.PP
2. Se han convertido \fInwc\fP caracteres anchos
sin encontrar un  L'\\0', o el límite de longitud fuerza la parada. En 
este caso \fI*src\fP se deja apuntando al siguiente carácter 
ancho para convertir y devuelve el número de bytes escritos 
en \fIdest\fP.
.PP
3. Se ha completado la conversión de la cadena de caracteres anchos,
incluyendo la terminación  L'\\0' (que tiene el efecto de 
devolver \fI*ps\fP al estado inicial). En este caso \fI*src\fP 
se pone como NULL y devuelve el número de bytes escritos en \fIdest\fP, 
excluyendo el byte terminador '\\0'.
.PP
Si \fIdest\fP es NULL, \fIlen\fP se ignora, y la conversión procede
como arriba, salvo que los bytes convertidos no se escriben en
memoria, y no existe límite de longitud.
.PP
En los dos casos anteriores, si \fIps\fP es un puntero NULL 
se usa en su lugar un estado privado anónimo sólo conocido 
por la función wcsnrtombs.
.PP
El programador tiene que asegurarse de que hay espacio para al menos
\fIlen\fP bytes en \fIdest\fP.
.SH "VALOR DEVUELTO"
La función \fBwcsnrtombs\fP devuelve el número de bytes que conforman
la parte de la secuencia multibyte convertida, sin incluir el byte 
nulo terminador. Si encontró un carácter ancho que no pudo convertir, 
devuelve (size_t)(-1) y \fBerrno\fP toma el valor \fBEILSEQ\fP.
.SH "CONFORME A"
Esta función es una extensión GNU.
.SH "VÉASE TAMBIÉN"
.BR wcsrtombs "(3), " iconv (3)
.SH OBSERVACIONES
El comportamiento de \fBwcnrtombs\fP depende de la categoría LC_CTYPE
de la localización actual.
.PP
Pasar NULL como \fIps\fP no es seguro en entornos multihilo.