MBSNRTOWCS(3)

NOME
mbsnrtowcs - converte uma cadeia de caracteres multibyte para uma cadeia de caracteres largos

SINÓPSE
#include <wchar.h>

size_t mbsnrtowcs (wchar_t *dest, const char **src,
                   size_t nms, size_t len, mbstate_t *ps);

DESCRIÇÃO
A função mbsnrtowcs é como a função mbsrtowcs, exceto que o número de bytes a serem convertidos, iniciando em *src, é limitado em nms.

Se dest não é um ponteiro NULO, a função mbsnrtowcs converte no máximo nms bytes da cadeia de caracteres multibyte *src para uma cadeia de caractere largo iniciando em dest. No máximo len caracteres largos são escritos em dest. O estado de transição *ps é atualizado. A conversão é efetivamente realizada através de chamadas repetitivas a mbrtowc(dest,*src,n,ps) onde n é um número positivo, enquanto essa chamada tiver sucesso, e então incrementando dest de um e *src pelo número de bytes consumidos. A conversão pode parar por três razões:

1. Um seqüência multibyte inválida foi encontrada. Neste caso *src é deixado apontando para a seqüência inválida, (size_t)(-1) é devolvido, e errno é ajustado para EILSEQ.

2. O limite nms força uma parada, ou len caracteres largos diferentes de L'\0' foram armazenados em dest. Neste caso *src é deixado apontando para a próxima seqüência multibyte a ser convertida, e o número de caracteres largos gravados em dest é devolvido.

3. A cadeia de caracteres multibyte foi completamente convertida, incluindo o terminador '\0' (o qual tem o efeito colateral de trazer *ps de volta ao estado inicial). Neste caso *src é ajustado para NULO, e o número de caracteres largos gravados em dest, excluindo o caractere terminador L'\0', é devolvido.

Se dest é NULO, len é ignorado, e a conversão prossegue como acima, exceto que os caracteres largos convertidos não são escritos para a memória e que não existe tamanho limite no destino.

Em ambos dos casos acima, se ps é um ponteiro NULO, um estado anônimo estático conhecido apenas para a função mbsnrtowcs é usado no seu lugar.

O programador deve garantir que existe espaço para no mínimo len caracteres largos em dest.

VALORES RETORNADOS
A função mbsnrtowcs devolve o número de caracteres largos que constituem a parte convertida da cadeia de caracteres largos, não incluindo o caractere largo terminador nulo. Se uma seqüência multibyte for encontrada, (size_t)(-1) é retornado, e errno ajustado para EILSEQ.

DE ACORDO COM
Esta função é uma extensão GNU.

VEJA TAMBÉM
mbsrtowcs(3), iconv(3).

NOTAS
O comportamento de mbsnrtowcs depende da categoria LC_CTYPE da localização atual.

Passando NULO como ps não é seguro em multi-thread.

TRADUZIDO POR LDP-BR em 28/05/2001.

  Tradução:
Felipe M Pereira <Felipe.Pereira@ic.unicamp.br>

  Revisão.:
André Luiz Fassone <lonely_wolf@ig.com.br>