FOPEN(3)

NOME
fopen, fdopen, freopen - funções de abertura de fluxo

SINÓPSE
#include <stdio.h>

FILE *fopen (const char *path, const char *mode);
FILE *fdopen (int fildes, const char *mode);
FILE *freopen (const char *path, const char *mode, FILE *stream);

DESCRIÇÃO
A função fopen abre o arquivo cujo nome é a seqüencia apontada por path e associa um fluxo com ele.

O argumento mode aponta para uma seqüencia que começa com uma ou mais sequências (Caracteres adicionais podem seguir essas sequências.):

r   Abre arquivo de texto para leitura. O fluxo é posicionado no começo do arquivo.

r+  Abre para leitura e escrita. O fluxo é posicionado no começo do arquivo.

w   Trunca o arquivo para comprimento zero, ou cria arquivo de texto para escrita. O fluxo é posicionado no começo do arquivo.

w+  Abre para leitura e escrita. O arquivo é criado se não existir, caso contrário ele é truncado. O fluxo é posicionado no começo do arquivo.

a   Abre para escrita. O arquivo é criado se não existir. O fluxo é posicionado no fim do arquivo.

a+  Abre para leitura e escrita. O arquivo é criado se não existir. O fluxo é posicionado no fim do arquivo.

A seqüencia de mode também pode incluir a letra 'b' como um último caractere ou como um caractere entre os caracteres em qualquer uma das seqüencias de dois caracteres descritas acima. Isto é estritamente para compatibilidade com ANSI X3.159-1989 ('ANSI C') e não tem efeito; o 'b' é ignorado em todos os sistemas conformes com POSIX, incluindo o Linux. (Outros sistemas podem tratar arquivos de texto e arquivos binários de formas diferentes, e o acréscimo de 'b' pode ser uma boa idéia se você faz E/S para um arquivo binário e espera que seu programa possa ser portado para ambientes não-Unix.)

Quaisquer arquivos criados terão o modo S_IRUSR|S_IWUSR|S_IRGRP|S_IWGRP|S_IROTH|S_IWOTH (0666), conforme modificado pelo valor de 'umask' do processo, veja umask(2).

Leitura e escrita pode ser mescladas em fluxos de leitura/escrita em qualquer ordem. Note que o C ANSI requer que uma função de posicionamento de arquivo intercale-se entre a saída e a entrada, a menos que uma operação de entrada encontre o fim do arquivo. (Se esta condição não é encontrada, então uma leitura é permitida para retornar o resultado de escritas que não sejam a mais recente.) Portanto é uma boa prática (e de fato necessário sob o Linux, às vezes) colocar uma operação fseek ou fgetpos entre operações de escrita e leitura em tais fluxos. Esta operação pode ser um aparente no-op ('no operation', como em fseek(..., 0L, SEEK_CUR) chamado para seu efeito colateral de sincronismo.

A função fdopen associa um fluxo com o descritor de arquivos existente, fildes. O modo do fluxo (um dos valores 'r', 'r+', 'w', 'w+', 'a', 'a+') precisa ser compatível com o modo do descritor de arquivo. O indicador de posição do arquivo do novo fluxo é selecionado para aquele pertencente ao fildes, e os indicadores de erro e fim de arquivo são limpos. Os modos 'w' ou 'w+' não provocam truncamento do arquivo. O descritor de arquivo não sofre um 'dup', e será fechado quando o fluxo criado por fdopen for fechado. O resultado da aplicação de fdopen para um objeto de memória compartilhado é indefinido.

A função freopen abre o arquivo cujo nome é a seqüencia apontada por path e associa o fluxo apontado por stream a ele. O fluxo original (se existir) é encerrado. O argumento mode é usado apenas como na função fopen. O uso primário da função freopen é mudar o arquivo associado com o fluxo de texto padrão (stderr, stdin, ou stdout).

VALORES RETORNADOS
Em caso de término bem sucedido, fopen, fdopen e freopen retornam um ponteiro para FILE. Caso contrário, é retornado um NULO e a variável global errno é selecionada adequadamente.

ERROS

EINVAL
    O mode fornecido para fopen, fdopen, ou freopen era inválido.

As funções fopen, fdopen e freopen também podem falhar e selecionar errno para quaisquer dos erros especificados para a rotina malloc(3).

A função fopen também pode falhar e selecionar errno para quaisquer dos erros especificados para a rotina open(2).

A função fdopen também pode falhar e selecionar errno para quaisquer dos erros especificados para a rotina fcntl(2).

A função freopen também pode falhar e selecionar errno para quaisquer dos erros especificados para as rotinas open(2), fclose(3) e fflush(3).

DE ACORDO COM
As funções fopen e freopen estão em conformidade com ANSI X3.159-1989 ('ANSI C'). A função fdopen está em conformidade com IEEE Std1003.1-1988 ('POSIX.1').

VEJA TAMBÉM
open(2), fclose(3), fileno(3).

TRADUZIDO POR LDP-BR em 21/08/2000.

  Tradução:
Rubens de Jesus Nogueira <darkseid99@usa.net>

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