MBSRTOWCS(3)

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

SINÓPSE
#include <wchar.h>

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

DESCRIÇÃO
Se dest não é um ponteiro NULO, a função mbsrtowcs converte a cadeia de caracteres multibyte *src para uma cadeia de caracteres largos 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 chamando repetitivamente 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 do número de bytes consumidos. A conversão pode parar por três razões:

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

2. len caracteres largos diferentes de L'\0' foram gravados em dest. Neste caso *src é deixado apontando para a próxima seqüência multibyte a ser convertida, e o número de caracteres largos escritos 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 gravados na memória, e que não há limite de tamanho.

Em ambos os casos acima, se ps é um ponteiro NULO, um estado estático anônimo conhecido apenas pela função mbsrtowcs é usado em seu lugar.

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

VALORES RETORNADOS
A função mbsrtowcs retorna o número de caracteres que perfazem a parte convertida da cadeia de caracteres de caracteres largos, não incluindo o caractere largo terminador nulo. Se uma seqüência multibyte inválida foi encontrada, (size_t)(-1) é devolvido, e errno ajustado para EILSEQ.

DE ACORDO COM
ISO/ANSI C, UNIX98.

VEJA TAMBÉM
mbstowcs(3), mbsnrtowcs(3), iconv(3).

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

Passar 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>