NOMBRE¶
mbsnrtowcs - convierte una cadena multibyte a una cadena de caracteres anchos
SINOPSIS¶
#include <wchar.h>
size_t mbsnrtowcs (wchar_t *dest, const char **src,
size_t nms, size_t len, mbstate_t *ps);
DESCRIPCIÓN¶
La función
mbsnrtowcs es como la función
mbsrtowcs,
salvo que el número de bytes a convertir, comenzando en
*src,
está limitado a
nms.
Si
dest no es un puntero NULL, la función
mbsnrtowcs
convierte, como mucho,
nms bytes de la cadena multibyte
*src a
una cadena de caracteres anchos que comienza en
dest. Como mucho, se
escriben
len caracteres anchos en
dest. El estado de cambios
*ps se actualiza. La conversión se realiza en realidad llamando
repetidamente a mbrtowc(
dest,
*src,
n,
ps), donde
n es algún número positivo tal que esta llamada tenga
éxito, e incrementa a continuación
dest en uno y
*src
en el número de bytes consumidos. La conversión se puede detener por
tres motivos:
1. Se ha encontrado una secuencia multibyte inválida. En este caso se deja
*src apuntando a la secuencia multibyte inválida, la función
devuelve (size_t)(-1) y se asigna a
errno el valor
EILSEQ.
2. El límite
nms fuerza una parada, o se han almacenado
len
caracteres anchos distintos de L'\0' en
dest. En este caso, se deja
*src apuntando a la siguiente secuencia multibyte a convertir y la
función devuelve el número de caracteres anchos escritos en
dest.
3. Se ha convertido completamente la cadena multibyte, incluyendo el
carácter terminador '\0' (que tiene el efecto colateral de devolver a
*ps al estado inicial). En esta caso, se asigna a
*src un NULL y
la función devuelve el número de caracteres anchos escritos en
dest, excluyendo el carácter terminador L'\0.
Si
dest es NULL, se ignora
len, 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.
En los dos casos anteriores, si
ps es un puntero NULL pointer, en su
lugar se usa un estado anónimo privado, sólo conocido por la
función
mbsnrtowcs.
Los programadores deben garantizar que hay espacio suficiente en
dest
para, al menos,
len caracteres anchos.
VALOR DEVUELTO¶
La función
mbsnrtowcs 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
errno el valor
EILSEQ.
Esta función es una extensión de GNU.
VÉASE TAMBIÉN¶
mbsrtowcs(3),
iconv(3)
OBSERVACIONES¶
El comportamiento de
mbsnrtowcs depende de la categoría LC_CTYPE de
la localización actual.
Pasar NULL como valor de
ps no es seguro en un entorno multihilos.