WCSTOMBS(3)

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

SINÓPSE
#include <stdlib.h>

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

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

1. Um caractere largo foi encontrado e não pode ser representado como uma seqüência multibyte (de acordo com o locale atual). Neste caso (size_t)(-1) é retornado.

2. O limite de tamanho força uma parada. Neste caso o número de bytes escritos para dest é retornado, mas o estado de transição neste ponto é perdido.

3. A seqüência de caracteres largos foi completamente convertida, incluindo o terminador L'\0'. Neste caso a conversão termina no estado inicial. O número de bytes escritos para dest, excluindo o byte terminador

O programador deve garantir que há espaço para pelo menos n bytes em dest.

Se dest é NULO, n é ignorado, e a conversão prossegue como acima, exceto que os bytes convertidos não são gravados para a memória, e que nenhum limite de tamanho existe.

A fim de evitar o caso 2 acima, o programador deveria ter certeza que n é maior ou igual a wcstombs(NULO,src,0)+1.

VALORES RETORNADOS
A função wcstombs retorna o número de bytes que perfazem a parte convertida da seqüência multibyte, não incluindo o byte terminador nulo. Se um caractere largo foi encontrado e não pode ser convertido, (size_t)(-1) é retornado.

DE ACORDO COM
ISO/ANSI C, UNIX98.

VEJA TAMBÉM
wcsrtombs(3).

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

A função wcsrtombs oferece uma interface segura para threads com a mesma funcionalidade.

TRADUZIDO POR LDP-BR em 14/03/2001.

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

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