freopen, _wfreopen

Reatribui um ponteiro de arquivo. Versões mais seguras das funções estão disponíveis; veja freopen_s, _wfreopen_s.

Sintaxe

FILE *freopen(
   const char *path,
   const char *mode,
   FILE *stream
);
FILE *_wfreopen(
   const wchar_t *path,
   const wchar_t *mode,
   FILE *stream
);

Parâmetros

path
Caminho do novo arquivo.

mode
Tipo de acesso permitido.

stream
Ponteiro para a estrutura FILE.

Valor retornado

Cada uma dessas funções retorna um ponteiro para o arquivo recém-aberto. Se ocorrer um erro, o arquivo original será fechado e a função retornará um NULL valor de ponteiro. Se path, mode, ou stream for um ponteiro nulo ou se filename for uma cadeia de caracteres vazia, essas funções invocarão o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções definirão errno como EINVAL e retornarão NULL.

Para obter mais informações sobre códigos de erro, consulte errno, _doserrno, _sys_errliste _sys_nerr.

Comentários

Existem versões mais seguras dessas funções, consulte freopen_s, _wfreopen_s.

A freopen função fecha o arquivo atualmente associado stream e reatribui stream ao arquivo especificado por path. _wfreopen é uma versão de caractere largo de _freopen; os argumentos path e mode para _wfreopen são cadeias de caracteres largos. Caso contrário, _wfreopen e _freopen se comportam de forma idêntica.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tfreopen	freopen	freopen	_wfreopen

freopen normalmente é usado para redirecionar os arquivos abertos previamente stdin, stdout e stderr para arquivos especificados pelo usuário. O novo arquivo associado é stream aberto com mode, que é uma cadeia de caracteres que especifica o tipo de acesso solicitado para o arquivo, da seguinte maneira:

mode	Access
"r"	Abre para leitura. Se o arquivo não existir ou não puder ser encontrado, a chamada freopen falhará.
"w"	Abre um arquivo vazio para gravação. Se o arquivo determinado existir, seus conteúdos são destruídos.
"a"	Abre para gravação no fim do arquivo (conexão) sem remover o marcador de EOF (Fim de arquivo) antes de novos dados serem gravados no arquivo. Cria o arquivo se ele não existir.
"r+"	Abre para leitura e gravação. O arquivo deve existir.
"w+"	Abre um arquivo vazio para leitura e gravação. Se o arquivo existir, seus conteúdos são destruídos.
"a+"	Abre para leitura e conexão. A operação de conexão inclui a remoção do marcador de EOF antes de os novos dados serem gravados no arquivo. O marcador de EOF não é restaurado após a gravação ser concluída. Cria o arquivo se ele não existir.

Use os tipos "w" e "w+" com cuidado, pois eles podem destruir arquivos existentes. Começando com C11, você pode acrescentar "x" a "w" ou "w+" para causar falha na função se o arquivo existir, em vez de substituí-lo.

Quando um arquivo é aberto com o tipo de acesso "a" ou "a+", todas as operações de gravação ocorrem no fim do arquivo. Embora o ponteiro do arquivo possa ser reposicionado usando fseek ou rewind, o ponteiro do arquivo é sempre movido de volta para o final do arquivo antes que qualquer operação de gravação seja executada. Portanto, os dados existentes não podem ser substituídos.

O modo "a" não remove o marcador de EOF antes de ser acrescentado ao arquivo. Depois de a conexão ter ocorrido, o comando MS-DOS TYPE só mostra dados até o marcador de EOF original, e não qualquer dado anexado ao arquivo. O modo "a+" remove o marcador de EOF antes de ser acrescentado ao arquivo. Depois de anexar, o comando MS-DOS TYPE mostra todos os dados no arquivo. O modo "a+" é exigido para conexão com um arquivo de fluxo terminado com o marcador de EOF CTRL+Z.

Quando o tipo de acesso "r+", "w+" ou "a+" é especificado, são permitidas leitura e gravação (diz-se que o arquivo está aberto para "atualização"). No entanto, quando você muda entre leitura e gravação, precisa haver uma operação fsetpos, fseek ou rewind intermediária. A posição atual pode ser especificada para a operação fsetpos ou fseek, se quiser. Além dos valores acima, um dos caracteres seguintes pode ser incluído na cadeia de caracteres mode para especificar o modo de conversão para novas linhas.

Modificador mode	Modo de conversão
t	Abra no modo de texto (convertido).
b	Abra em um modo binário (não convertido); as conversões envolvendo caracteres de retorno de carro e avanço de linha são suprimidas.

No modo de texto (convertido), combinações de CR-LF (retorno de carro – avanço de linha) são convertidas em caracteres de LF (avanço de linha) simples na entrada; caracteres de LF são convertidos em combinações de CR-LF na saída. Além disso, CTRL+Z é interpretado como um caractere de fim do arquivo na entrada. Em arquivos abertos para leitura ou para leitura e gravação com "a+", a biblioteca em tempo de execução verifica se há um CTRL+Z no fim do arquivo e o remove, se possível. Ele é removido porque usar fseek e mover dentro de um arquivo pode fazer com que fseek você se comporte ftell de maneira inadequada perto do final do arquivo. Não use a opção t se quiser portabilidade ANSI porque é uma extensão da Microsoft.

Se t ou b não for fornecido em mode, o modo de conversão padrão será definido pela variável global _fmode. Se t ou b for prefixado para o argumento, a função falha e retorna NULL.

Para saber mais sobre os modos de texto e binário, consulte E/S de texto e arquivo de modo binário.

Requisitos

Função	Cabeçalho necessário
freopen	<stdio.h>
_wfreopen	<stdio.h> ou <wchar.h>

Não há suporte para o console em aplicativos UWP (Plataforma Universal do Windows). Os identificadores de fluxo padrão associados ao console, stdin, stdout e stderr, devem ser redirecionados antes que as funções em tempo de execução C possam usá-los em aplicativos UWP. Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// crt_freopen.c
// compile with: /W3
// This program reassigns stderr to the file
// named FREOPEN.OUT and writes a line to that file.
#include <stdio.h>
#include <stdlib.h>

FILE *stream;

int main( void )
{
   // Reassign "stderr" to "freopen.out":
   stream = freopen( "freopen.out", "w", stderr ); // C4996
   // Note: freopen is deprecated; consider using freopen_s instead

   if( stream == NULL )
      fprintf( stdout, "error on freopen\n" );
   else
   {
      fprintf( stdout, "successfully reassigned\n" ); fflush( stdout );
      fprintf( stream, "This will go to the file 'freopen.out'\n" );
      fclose( stream );
   }
   system( "type freopen.out" );
}

successfully reassigned
This will go to the file 'freopen.out'

Confira também

E/S de fluxo
fclose, _fcloseall
_fdopen, _wfdopen
_fileno
fopen, _wfopen
_open, _wopen
_setmode