SETBUF(3)

NOME
setbuf, setbuffer, setlinebuf, setvbuf - operações de fluxo de buffers

SINÓPSE
#include <stdio.h>

void setbuf(FILE *fluxo, char *buf);
void setbuffer(FILE *fluxo, char *buf, size_tsize);
void setlinebuf(FILE *fluxo);
int setvbuf(FILE *fluxo, char *buf, int modo , size_t tamanho);

DESCRIÇÃO
Os três tipos de fluxo de 'buffers' disponíveis são: sem 'buffer', 'buffer' de bloco e 'buffer' de linha. Quando um fluxo de saída está sem 'buffer', as informações aparecem no arquivo destino ou terminal assim que são escritas; quando ele está em modo de 'buffer' de bloco muitos caracteres são salvos com um bloco; quando ele está em modo de 'buffer' de linha os caracteres são salvos até que um retorno de carro seja enviado ou recebido de algum fluxo de dados conectado ao dispositivo terminal (tipicamente a entrada padrão [stdin]). A função fflush(3) pode ser utilizada para forçar a saída antecipada do bloco. (Veja fclose(3).) Normalmente todos os arquivos estão em modo de 'buffer' de bloco. Quando a primeira operação de E/S ocorre em um arquivo, malloc(3) é chamada e um 'buffer' é obtido. Se um fluxo se refere a um terminal (como stdout geralmente é), ele está em modo de 'buffer' de linha. O fluxo de erro padrão stderr está sempre em modo 'sem buffer' por padrão.

A função setvbuf pode ser usada em qualquer fluxo aberto para alterar seu 'buffer'. O parâmetro modo precisa ser uma das três macros a seguir:

    _IONBF
        sem 'buffer'

    _IOLBF
        é um 'buffer' de linha

    _IOFBF
        é um 'buffer' completo

Exceto para arquivos sem 'buffers', o argumento buf precisa apontar para um 'buffer' de ao menos tamanho bytes de comprimento; este 'buffer' será usado no lugar do 'buffer' atual. Se o argumento buf for NULL, apenas o modo será afetado; um novo 'buffer' será alocado na próxima operação de leitura ou escrita. A função setvbuf pode ser usada apenas após a abertura de um fluxo e antes que outras operações sejam executadas nele.

As outras três chamadas são, de fato, simples aliases para chamadas a setvbuf. A função setbuf é exatamente equivalente à chamada

    setvbuf(fluxo, buf, buf ? _IOFBF : _IONBF, BUFSIZ);

A função setbuffer é a mesma, exceto que o tamanho do 'buffer' é determinado pelo código que a chama, ao invés de ser determinado pelo BUFSIZpadrão. A função setlinebuf é exatamente equivalente à chamada

    setvbuf(stream, (char *)NULL, _IOLBF, 0);

VALORES RETORNADOS
Em caso de sucesso setvbuf, devolve 0. Caso contrário, pode retornar qualquer valor, mas não um diferente de 0 quando mode é inválido ou a requisição não foi feita. Pode selecionar errno em caso de falha. As outras funções são ignoradas.

DE ACORDO COM
As funções setbuf e setvbuf estão em conformidade com o ANSI X3.159-1989 ('ANSI C').

PROBLEMAS
As funções setbuffer e setlinebuf não são portáveis para versões do BSD antes da BSD 4.2, e podem não estar disponíveis no Linux. Em sistemas BSD 4.2 e BSD 4.3, a setbuf nunca usa um tamanho ideal de 'buffer', e deve ser evitada.

Você deve se assegurar que tanto buf como o espaço ao qual ele aponta ainda existam no momento que o fluxo seja fechado, o que também acontece quando do término do programa.

Por exemplo, é ilegal fazer:

#include <stdio.h>
int main()
{
    char buf[BUFSIZ];
    setbuf(stdin, buf);
    printf("Olá, mundo!!\n");
    return 0;
}

VEJA TAMBÉM
fclose(3), fflush(3), fopen(3), fread(3), malloc(3), printf(3), puts(3).

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

  Tradução:
E. A. Tacão <tacao@conectiva.com.br>

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