freopen_s, _wfreopen_s

Artigo
06/09/2015

Reatribui um ponteiro de arquivo. Essas versões de freopen, _wfreopen têm os aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

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

Parâmetros

[saída] pFile
Um ponteiro para o ponteiro de arquivo a ser fornecido pela chamada.
[entrada] path
Caminho do arquivo novo.
[entrada] mode
Tipo de acesso permitido.
[entrada] stream
Ponteiro a estrutura de FILE .

Valor de retorno

Cada uma dessas funções retorna um código de erro. Se um erro ocorrer, o arquivo original é fechado.

Comentários

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

Se algum de pFile, de path, de mode, ou de stream é NULL, ou se path é uma cadeia de caracteres vazia, essas funções invoca o manipulador inválido do parâmetro, conforme descrito em Validação do parâmetro. Se a execução puder continuar, essas funções definirão errno como EINVAL e retornarão EINVAL.

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tfreopen_s	freopen_s	freopen_s	_wfreopen_s

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

"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, seu conteúdo será destruído.
"a"
Abre gravando no final do arquivo (adicionar) sem remover o marcador de EOF antes de gravar novos dados ao arquivo; cria o arquivo primeiro se não existir.
"r+"
Abre para leitura e gravação. (O arquivo deve existir.)
"w+"
Abre um arquivo vazio para a leitura e gravação. Se o arquivo determinado existir, seu conteúdo será destruído.
"a+"
Abre ler e anexando; anexando a operação inclui a remoção do marcador de EOF antes que os novos dados sejam gravados em um arquivo e o marcador de EOF está sendo restaurado depois de escrever está completo; cria o arquivo primeiro se não existir.

Use os tipos de "w" e de "w+" com cuidado, como podem ser destruído arquivos existentes.

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

O modo de "a" não remove o marcador de EOF antes de anexar ao arquivo. Após a anexação ocorrer, o comando TYPE do MS-DOS mostrará somente os dados até o marcador de EOF original e nenhum dado anexado ao arquivo. O modo de "a+" remove o marcador de EOF antes de anexar ao arquivo. Após a anexação, o comando TYPE do MS-DOS mostra todos os dados no arquivo. O modo "a+" é necessário acrescentar a um arquivo de fluxo que é encerrado com o marcador de CTRL+Z EOF.

Quando "r+","w+", ou o tipo de acesso de "a+" forem especificados, a leitura e gravação são permitidas (o arquivo é aberto para “atualização”). No entanto, quando você alternar entre a leitura e a gravação, deve haver fsetposde intervenção, fseek, ou uma operação de rewind . A posição atual pode ser especificado para a operação de fsetpos ou de fseek , se desejado. Além dos valores acima, um dos seguintes caracteres pode ser incluído na cadeia de caracteres de mode para especificar o modo de conversão de linhas.

t
Abrir no modo de texto traduzido (); as combinações de retorno- avanço de linha de carro (CR-LF) são convertidas em caracteres únicos (LF) de alimentação de linha na entrada; Os 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 participante de Arquivo na entrada. Em arquivos abertos para leitura ou gravação e ler "a+", a biblioteca de tempo de execução verifica se há um CTRL+Z no final do arquivo e solte-o, se possível. Isso é feito como usar fseek e ftell para mover dentro de um arquivo pode fazer com que fseek se com comportamento de forma incorreta próximo do fim do arquivo. A opção de t é uma extensão da Microsoft que não deve ser usada onde a portabilidade de ANSI é desejada.
b
Abrir no modo binário não traduzido (); as traduções acima são suprimida.

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

Para obter uma descrição dos modos de texto e binários, consulte O modo de texto e binários de E/S.

Requisitos

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

O console não tem suporte em aplicativos do Windows Store. Os manipuladores de fluxo padrão associados ao console — stdin, stdout e stderr — devem ser redirecionados antes que as funções de tempo de execução do C possam utilizá-los em aplicativos do Windows Store. Para informações adicionais de 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" );
}