ICONV(3)

NOME
iconv - efetua conversão de conjunto de caractere

SINÓPSE
#include <iconv.h>

size_t iconv (iconv_t cd,
              const char* * inbuf, size_t * inbytesleft,
              char* * outbuf, size_t * outbytesleft);

DESCRIÇÃO
O argumento cd deve ser um descritor de conversão criado pelo uso da função iconv_open.

O principal caso é quando inbuf não é NULO e *inbuf não é NULO. Nesse caso, a função iconv converte a seqüência multibyte começando em *inbuf para uma seqüência multibyte começando em *outbuf. No máximo *inbytesleft bytes, começando em *inbuf, serão lidos. No máximo *outbytesleft bytes, começando em *outbuf, serão escritos.

A função iconv converte um caractere multibyte de cada vez e, para cada conversão de caractere, ela incrementa *inbuf e decrementa *inbytesleft pelo número de bytes de entrada convertidos, incrementa *outbuf e decrementa *outbytesleft pelo número de bytes de saída convertidos e atualiza o estado de conversão contido em cd. A conversão pode parar por quatro razões:

1. Uma seqüência multibyte inválida foi encontrada na entrada. Nesse caso, ela define errno para EILSEQ e retorna (size_t)(-1). *inbuf é deixado apontando para o início da seqüência multibyte inválida.

2. A seqüência de bytes de entrada foi inteiramente convertida, isto é, *inbytesleft chegou a 0. Nesse caso, iconv retorna o número de conversões não reversíveis realizadas durante esta chamada.

3. Uma seqüência multibyte incompleta foi encontrada na entrada, e a seqüência de bytes de entrada termina após ela. Nesse caso, ela define errno para EINVAL e retorna (size_t)(-1). *inbuf é deixado apontando para o início da seqüência multibyte incompleta.

4. O pedaço de memória de saída não possui mais espaço para o próximo caractere convertido. Nesse caso, ela define errno para E2BIG e retorna (size_t)(-1).

Um caso diferente é quando inbuf é NULO ou *inbuf é NULO, mas outbuf não é NULO e *outbuf não é NULO. Nesse caso, a função iconv tenta definir o estado de conversão de cd para o estado inicial e armazenar uma seqüência de deslocamento correspondente em *outbuf. No máximo *outbytesleft bytes, começando em *outbuf, serão escritos. Se o pedaço de memória de saída não tiver mais espaço para essa seqüência de reinicialização, ela define errno para E2BIG e retorna (size_t)(-1). Caso contrário, ela incrementa *outbuf e decrementa *outbytesleft pelo número de bytes escritos.

Um terceiro caso é quando inbuf é NULO ou *inbuf é NULO, e outbuf é NULO ou *outbuf é NULO. Nesse caso, a função iconv define o estado de conversão de cd para o estado inicial.

VALORES RETORNADOS
A função iconv retorna o número de caracteres convertidos de uma forma não reversível durante esta chamada; conversões reversíveis não são levadas em conta. Em caso de erro, ela define errno e retorna (iconv_t)(-1).

ERROS
O seguintes erros podem ocorrer, entre outros:

E2BIG
    Não há espaço suficiente em *outbuf.

EILSEQ
    Uma seqüência multibyte inválida fora encontrada na entrada.

EINVAL
    Uma seqüência multibyte incompleta fora encontrada na entrada.

DE ACORDO COM
UNIX98.

VEJA TAMBÉM
iconv_open(3), iconv_close(3).

TRADUZIDO POR LDP-BR em 10/06/2001.

  Tradução:
Marcelo M. de Abreu <mmabreu@terra.com.br>

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