sub-rotina mbsrtowcs

Propósito

Converta uma sequência de caracteres em uma cadeia de caracteres ampla (reiniciável).

Biblioteca

Biblioteca Padrão (libc.a)

Sintaxe

#include <wchar.h>

size_t mbsrtowcs ((wchar_t * dst, const char ** src, size_t len, mbstate_t * ps) ;

Descrição

A função mbsrtowcs converte uma sequência de caracteres, começando no estado de conversão descrito pelo objeto apontado por ps, a partir da matriz indiretamente apontada por src em uma sequência de caracteres de largura correspondente. Se dst não for um ponteiro nulo, os caracteres convertidos são armazenados na matriz apontada por dst. A conversão continua até e incluindo um caractere nulo terminante, que também é armazenado. A conversão pára cedo em qualquer um dos seguintes casos:

• Quando uma sequência de bytes é encontrada que não forma um caractere válido.
• Quando os códigos len foram armazenados na matriz apontada por dst (e dst não é um ponteiro nulo).

Cada conversão ocorre como se por uma chamada para a função mbrtowc .

Se dst não for um ponteiro nulo, o objeto do ponteiro apontado por src é atribuído ou um ponteiro nulo (se a conversão parou devido a atingir um caractere nulo terminante) ou o endereço acabado de passar o último caractere convertido (se houver). Se a conversão parou devido a atingir um caractere nulo terminante, e se dst não for um ponteiro nulo, o estado resultante descrito é o estado de conversão inicial.

Se ps for um ponteiro nulo, a função mbsrtowcs usa o seu próprio objeto mbstate_t interno, que é inicializado na inicialização do programa para o estado de conversão inicial. Caso contrário, o objeto mbstate_t apontado por ps é usado para descrever completamente o estado de conversão atual da sequência de caracteres associados. A implementação se comportará como se nenhuma função definida nesta especificação chamar mbsrtowcs.

O comportamento desta função é afetado pela categoria LC_CTYPE do locale atual.

Valores De Retorno

Se a conversão de entrada encontrar uma sequência de bytes que não formam um caractere válido, ocorrerá um erro de codificação. Neste caso, a função mbsrtowcs armazena o valor do macro EILSEQ em errno e retorna (size_t) -1); o estado de conversão é indefinido. Caso contrário, ele retorna o número de caracteres convertidos com sucesso, não incluindo o terminating null (se houver).

Códigos De Erro

A função mbsrtowcs pode falhar se: