MBTOWC(3)

NOME
mbtowc - converte uma seqüência multibyte para uma caractere largo

SINÓPSE
#include <stdlib.h>

int mbtowc (wchar_t *pwc, const char *s, size_t n);

DESCRIÇÃO
O caso principal para esta função é quando s não é NULO e pwc não é NULO. Neste caso, a função mbtowc inspeciona no máximo n bytes da string multibyte iniciando em s, extrai o próximo caractere multibyte completo, converte-o para um caractere largo e o guarda em *pwc. Ela atualiza um estado interno de transição conhecido apenas pela função mbtowc. Se s não aponta para um byte '\0', ela retorna o número de bytes que foram consumidos de s, caso contrário ela retorna 0.

Se os n bytes iniciando em s não contêm um caractere multibyte completo, ou se eles contêm uma seqüência multibyte inválida, mbtowc retorna -1. Isto pode acontecer até se n >= MB_CUR_MAX, se a string multibyte contém seqüências de transição redundantes.

Um caso diferente é quando s não é NULO mas pwc é NULO. Neste caso a função mbtowc comporta-se como acima, exceto que ela não guarda o caractere largo convertido na memória.

Um terceiro caso é quando s é NULO. Neste caso, pwc e n são ignorados. A função mbtowc reinicializa o estado de transição, conhecido apenas por esta função, ao estado inicial, e retorna um valor diferente de zero se a codificação possui estado de transição não trivial, ou zero se a codificação não possui estado.

VALORES RETORNADOS
Se s não é NULO, a função mbtowc retorna o número de bytes consumidos iniciando em s, ou 0 se s aponta para um byte nulo, ou -1 se falhar.

Se s é NULO, a função mbtowc retorna um valor diferente de zero se a codificação possui estado de transição não trivial, ou zero se a codificação não possui estado.

DE ACORDO COM
ISO/ANSI C, UNIX98.

VEJA TAMBÉM
mbrtowc(3), mbstowcs(3), MB_CUR_MAX(3).

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

Esta função não é segura para multi-thread. A função mbrtowc oferece uma interface melhor para a mesma funcionalidade.

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>