WCSRTOMBS(3)

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

SINÓPSE
#include <wchar.h>

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

DESCRIÇÃO
Se dest não é um ponteiro NULL, a função wcsrtombs converte a seqüencia de caracteres largos *src para uma seqüencia multibyte iniciando em dest. No máximo len bytes são escritos em dest. O estado de transição *ps é atualizado. A conversão é efetivamente realizada repetindo a chamada wcrtomb(dest,*src,ps), enquanto essa chamada tem sucesso, e então incrementando dest pelo número de bytes escritos e *src de um. A conversão pode parar por três motivos:

1. Um caractere largo foi encontrado que não pode ser representado como uma seqüência multibyte (de acordo com o locale atual). Neste caso *src é devolvido apontando para o caractere largo inválido, (size_t)(-1) é retornado e errno é definido para EILSEQ.

2. O limite de tamanho força uma parada. Neste caso *src é devolvido apontando para o próximo caractere largo a ser convertido, e o número de bytes escritos para dest é retornado.

3. A seqüencia de caracteres largos foi completamente convertida, incluindo o terminador L'\0' (o qual tem o efeito colateral de trazer de volta *ps para o estado inicial). Neste caso *src é ajustado para NULL e o número de bytes escritos em dest, excetuando-se o byte terminador '\0', é retornado.

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

Em quaisquer dos casos acima, se ps é um ponteiro NULL, um estado anônimo estático apenas conhecido para a função wcsrtombs é usado em seu lugar.

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

VALORES RETORNADOS
A função wcsrtombs 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 que não pôde ser convertido, (size_t)(-1) é retornado, e errno ajustado par EILSEQ.

DE ACORDO COM
ISO/ANSI C, UNIX98.

VEJA TAMBÉM
wcstombs(3), iconv(3).

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

Passar NULO como ps não é seguro para multi-thread.

TRADUZIDO POR LDP-BR em 28/05/2001.

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

  Revisão.:
Ricardo C.O.Freitas <english.quest@best-service.com>