freopen_s, _wfreopen_s

Fecha o arquivo atualmente associado a oldStream e reatribui stream ao arquivo especificado por fileName.

Essas versões do , _wfreopentêm aprimoramentos defreopen segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

errno_t freopen_s(
   FILE ** stream,
   const char * fileName,
   const char * mode,
   FILE* oldStream
);

errno_t _wfreopen_s(
   FILE ** stream,
   const wchar_t * fileName,
   const wchar_t * mode,
   FILE * oldStream
);

Parâmetros

stream
Um parâmetro out que apontará para o fluxo reaberto quando a função retornar.

fileName
Caminho do arquivo a ser reaberto.

mode
O modo do fluxo reaberto.

oldStream
O fluxo a ser reaberto. Ele é liberado e todos os arquivos associados a ele são fechados.

Valor retornado

Zero se for bem-sucedido; caso contrário, um código de erro. Se ocorrer um erro, o arquivo original será fechado e NULL gravado em stream unless stream também NULL

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

Comentários

A função freopen_s normalmente é usada para anexar os fluxos pré-abertos associados a stdin, stdout e stderr a outro arquivo.

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

Se qualquer um dos , path, , modeou stream for NULL, ou se path for uma cadeia de caracteres vazia, essas funções invocarão o manipulador de parâmetro inválido, conforme descrito em Validação de pFileparâmetro. Se a execução tiver permissão para continuar, essas funções definirão errno como EINVAL e retornarão EINVAL.

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_s	freopen_s	freopen_s	_wfreopen_s

freopen_s 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_s 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ê poderá 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 quando 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_s	<stdio.h>
_wfreopen_s	<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_s.c
// 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 )
{
   errno_t err;
   // Reassign "stderr" to "freopen.out":
   err = freopen_s( &stream, "freopen.out", "w", stderr );

   if( err != 0 )
      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

Stream I/O
freopen, _wfreopen
fclose, _fcloseall
_fdopen, _wfdopen
_fileno
fopen, _wfopen
_open, _wopen
_setmode