MBSTOWCS(3)

NOME
mbstowcs - converte uma seqüencia multibyte para uma seqüencia de caracteres largos

SINÓPSE
#include <stdlib.h>

size_t mbstowcs (wchar_t *dest, const char *src, size_t n);

DESCRIÇÃO
Se dest não é um ponteiro NULL, a função mbstowcs converte a seqüencia multibyte src para uma seqüencia de caracteres largos iniciando em dest. No máximo n caracteres largos são gravados em dest. A conversão começa no estado inicial. A conversão pode parar por três razões:

1. Uma seqüência multibyte inválida foi encontrada. Neste caso, (size_t)(-1) é devolvido.

2. n caracteres largos diferentes de L'\0' foram gravados em dest. Neste caso o número de caracteres largos gravados em dest é retornado, mas o estado de transição neste ponto é perdido.

3. A seqüencia multibyte foi completamente convertida, incluindo o terminador '\0'. Neste caso o número de caracteres largos gravados em dest, excluindo o caractere terminador L'\0', é retornado.

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

Se dest é NULL, n é 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.

A fim de evitar o caso 2 acima, o programador deve garantir que n é maior ou igual a mbstowcs(NULL,src,0)+1.

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

DE ACORDO COM
ISO/ANSI C, UNIX98.

VEJA TAMBÉM
mbsrtowcs(3).

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

A função mbsrtowcs 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>