MBRTOWC(3)

NOME
mbrtowc - converte uma seqüência multibyte em um caracter largo

SINÓPSE
#include <wchar.h>

size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

DESCRIÇÃO
A situação para o uso desta função é quando nem s nem pwc são NULO. Nesse caso, a função mbrtowc procura até os n bytes, no máximo, da string multibyte que começa em s, extrai o próximo caracter multibyte completo, converte ele em um caracter largo e o armazena em *pwc. Ela atualiza o estado transitório *ps. Se o caracter largo convertido não for L'\0', ela retorna o número de bytes consumidos de s. Se o caracter largo convertido for L'\0', ela reinicializa o estado transitório *ps ao valor inicial e retorna 0.

Se os n bytes iniciando em s não contiverem um caracter multibyte completo, mbrtowc retorna (size_t)(-2). Isso pode acontecer mesmo se n >= MB_CUR_MAX, se a string multibyte contiver seqüências transitórias redundantes.

Se a string multibyte string começando em s contiver uma seqüência multibyte inválida antes do próximo caracter completo, mbrtowc retorna (size_t)(-1) e define errno para EILSEQ. Neste caso, os efeitos em *ps não podem ser precisados.

Uma situação diferente ocorre quando s não é NULO, mas pwc é NULO. Neste caso, a função mbrtowc se comporta da forma descrita acima, exceto pelo fato de ela não armazenar o caracter largo convertido na memória.

Um terceiro caso é quando s é NULO. Quando isso acontece, pwc e n são ignoradas. A função mbrtowc coloca *ps em seu estado inicial e retorna 0.

Em todos os casos acima, se ps for um ponteiro NULO, será usado um estado anônimo estático apenas conhecido pela função mbrlen.

VALORES RETORNADOS
A função mbrtowc retorna o número de bytes analisados (parsed) da seqüência multibyte começando em s, se um caracter largo diferente de L'\0' for reconhecido. Ela retorna 0 se um caracter largo L'\0' for reconhecido. Ela retorna (size_t)(-1) e define errno para EILSEQ se uma seqüência multibyte inválida for encontrada. Retorna (size_t)(-2) se ela não puder analisar (parse) um caracter multibyte completo, indicando que n deve ser aumentado.

DE ACORDO COM
ISO/ANSI C, UNIX98.

VEJA TAMBÉM
mbsrtowcs(3).

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

TRADUZIDO POR LDP-BR em 18/07/2001.

  Tradução:
E. A. Tacão <tacao@conectiva.com.br>

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