WCSNRTOMBS(3)

NOME
wcsnrtombs - converte uma seqüencia de caractere largo para uma seqüencia multibyte

SINÓPSE
#include <wchar.h>

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

DESCRIÇÃO
A função wcsnrtombs é como a função wcsrtombs function, a não ser pelo número de caracteres largos a serem convertidos, iniciando em *src, ser limitado a nwc.

Se dest não for um ponteiro NULL, a função wcsnrtombs converte no máximo nwc caracteres largos da string de caracteres largos *src para uma string 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 chamando-se repetidamente wcrtomb(dest,*src,ps), enquanto esta chamada ter sucesso, e então incrementando dest pelo número de bytes escritos e *src de um. 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 (conforme a localização atual). Neste caso *src é devolvido apontando para o caractere inválido, (size_t)(-1) é retornado, e errno é ajustado para EILSEQ.

2. nwc caracteres largos foram convertidos sem encontrar um L'\0', ou 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 em dest é retornado.

3. A string de caracteres largos foi totalmente convertida, incluindo o terminador L'\0' (o qual tem o efeito colateral de fazer *ps voltar ao seu estado inicial). Neste caso *srcé ajustado para NULL, e o número de bytes escritos para dest excluindo o byte terminador '\0', é retornado.

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

Em ambos os casos acima, se ps é um ponteiro NULL, um estado estático anônimo, conhecido apenas da função wcsnrtombs, é usado em seu lugar.

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

VALORES RETORNADOS
A função wcsnrtombs retorna o número de bytes que compõem a parte convertida da seqüência multibyte, não incluindo o byte nulo final. Se um caractere largo foi encontrado o qual não pode ser convertido, (size_t)(-1) é retornado, e errno ajustado para EILSEQ.

DE ACORDO COM
Esta função é uma extensão da GNU.

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

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

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

TRADUZIDO POR LDP-BR em 13/02/2001.

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

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