fopen_s, _wfopen_s

Abre um arquivo. Essas versões do fopen, _wfopen têm aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

errno_t fopen_s(
   FILE** pFile,
   const char *filename,
   const char *mode
);
errno_t _wfopen_s(
   FILE** pFile,
   const wchar_t *filename,
   const wchar_t *mode
);

Parâmetros

pFile
Um ponteiro para o ponteiro do arquivo que recebe o ponteiro para o arquivo aberto.

filename
O nome do arquivo a ser aberto.

mode
Tipo de acesso permitido.

Valor de retorno

Zero se for bem-sucedido; um código de erro em caso de falha. Para obter mais informações sobre esses códigos de erro, consulte errno, _doserrno, _sys_errliste _sys_nerr.

Condições de erro

Observações

As funções fopen_s e _wfopen_s não podem abrir um arquivo para compartilhamento. Se você precisar compartilhar o arquivo, use _fsopen ou _wfsopen com a constante de modo de compartilhamento apropriada — por exemplo, use _SH_DENYNO para compartilhamento de leitura/gravação.

A função fopen_s abre o arquivo especificado por filename. _wfopen_s é uma versão de caracteres largos de fopen_s e os argumentos para _wfopen_s são cadeias de caracteres largos. _wfopen_s e fopen_s comportam-se de forma idêntica, caso contrário.

fopen_s aceita caminhos que são válidos no sistema de arquivos no ponto de execução; Caminhos UNC e caminhos que envolvem unidades de rede mapeadas são aceitos por fopen_s desde que o sistema que está executando o código tenha acesso ao compartilhamento ou unidade de rede mapeada no momento da execução. Ao construir caminhos para fopen_s, não faça suposições sobre a disponibilidade de unidades, caminhos ou compartilhamentos de rede no ambiente de execução. Você pode usar barras (/) ou barras invertidas (\) como separadores de diretório em um caminho.

Estas funções validam os seus parâmetros. Se pFile, filenameou mode for um ponteiro nulo, essas funções gerarão uma exceção de parâmetro inválida, conforme descrito em Parameter validation.

Sempre verifique o valor de retorno para ver se a função foi bem-sucedida antes de fazer qualquer outra operação no arquivo. Se ocorrer um erro, o código de erro é retornado e a variável global errno é definida. Para obter mais informações, consulte errno, _doserrno, _sys_errliste _sys_nerr.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterá-lo, consulte estado global noCRT .

Suporte a Unicode

fopen_s suporta fluxos de arquivos Unicode. Para abrir um arquivo Unicode novo ou existente, passe um sinalizador de ccs que especifica a codificação desejada para fopen_s, por exemplo:

fopen_s(&fp, "newfile.txt", "w+, ccs=UNICODE");

Os valores permitidos do sinalizador ccs são UNICODE, UTF-8e UTF-16LE. Se nenhum valor for especificado para ccs, fopen_s usará codificação ANSI.

Se o arquivo já existir e estiver aberto para leitura ou acréscimo, a marca de ordem de bytes (BOM), se presente no arquivo, determinará a codificação. A codificação BOM tem precedência sobre a codificação especificada pelo sinalizador ccs. A codificação ccs só é usada quando nenhuma lista técnica está presente ou se o arquivo é um novo arquivo.

A tabela a seguir resume os modos para vários valores de sinalizador de ccs que são dados a fopen_s e para listas técnicas no arquivo.

Codificações usadas com base no sinalizador ccs e na lista técnica

Os arquivos que são abertos para gravação no modo Unicode têm uma lista técnica gravada neles automaticamente.

Se mode for "a, ccs=UNICODE", "a, ccs=UTF-8"ou "a, ccs=UTF-16LE", fopen_s primeiro tenta abrir o arquivo com acesso de leitura e acesso de gravação. Se for bem-sucedida, a função lê a lista técnica para determinar a codificação do arquivo; Se não tiver êxito, a função usa a codificação padrão para o arquivo. Em ambos os casos, fopen_s reabre o arquivo com acesso somente gravação. (Este comportamento aplica-se apenas ao modo a, não a+.)

A cadeia de caracteres mode especifica o tipo de acesso solicitado para o arquivo, da seguinte maneira.

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

O modo "a" não remove o marcador EOF antes de anexar ao arquivo. Após o acréscimo, o comando MS-DOS TYPE mostra apenas os dados até o marcador EOF original e não os dados anexados ao arquivo. O modo "a+" remove o marcador EOF antes de anexar ao arquivo. Depois de anexar, o comando MS-DOS TYPE mostra todos os dados no arquivo. O modo de "a+" é necessário para anexar a um arquivo de fluxo que é encerrado com o marcador CTRL+Z EOF.

Quando o tipo de acesso "r+", "w+"ou "a+" é especificado, a leitura e a gravação são permitidas. (Diz-se que o arquivo está aberto para "atualização".) No entanto, quando você muda da leitura para a escrita, a operação de entrada deve se deparar com um marcador EOF. Se não houver nenhum marcador EOF, você deve usar uma chamada intermediária para uma função de posicionamento de arquivo. As funções de posicionamento de arquivo são fsetpos, fseeke rewind. Ao mudar da escrita para a leitura, você deve usar uma chamada intermediária para fflush ou para uma função de posicionamento de arquivo.

A partir de C11, você pode acrescentar "x" a "w" ou "w+" para fazer com que a função falhe se o arquivo existir, em vez de substituí-lo.

Além dos valores anteriores, os seguintes caracteres podem ser incluídos no mode para especificar o modo de tradução para caracteres de nova linha:

No modo de texto (traduzido), CTRL+ Z é interpretado como um caractere de fim de arquivo na entrada. Para arquivos abertos para leitura/gravação com "a+", o fopen_s verifica se há umZ de CTRL+ no final do arquivo e o remove, se possível. Ele é removido porque usar fseek e ftell para mover dentro de um arquivo que termina com um CTRL+Z, pode fazer com que fseek se comporte incorretamente perto do final do arquivo.

Além disso, no modo de texto, as combinações de retorno de carro/alimentação de linha (CRLF) são convertidas em caracteres de alimentação de linha única (LF) na entrada, e os caracteres LF são traduzidos em combinações de CRLF na saída. Quando uma função de E/S de fluxo Unicode opera no modo de texto (o padrão), o fluxo de origem ou destino é assumido como uma sequência de caracteres multibyte. As funções de entrada de fluxo Unicode convertem caracteres multibyte em caracteres largos (como se fosse uma chamada para a função mbtowc). Pela mesma razão, as funções de saída de fluxo Unicode convertem caracteres largos em caracteres multibyte (como se fosse por uma chamada para a função wctomb).

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

Para obter mais informações sobre como usar os modos de texto e binário em Unicode e E/S de fluxo multibyte, consulte de E/S de arquivo de texto e modo binário e E/S de fluxo Unicode nos modos de texto e binário.

Os caracteres válidos para a cadeia de caracteres mode usada em fopen_s e _fdopen correspondem a oflag argumentos usados em _open e _sopen, da seguinte maneira.

As opções c, n, R, S, t, Te Dmode são extensões da Microsoft para fopen_s e _wfopen_s e não devem ser usadas quando você quiser portabilidade ANSI.

Se você estiver usando o modo rb, os arquivos Win32 mapeados pela memória também podem ser uma opção se você não precisar portar seu código, esperar ler grande parte do arquivo ou não se importar com o desempenho da rede.

Relativamente à T e D:

• T evita gravar o arquivo no disco, desde que a pressão da memória não exija. Para obter mais informações, consulte FILE_ATTRIBUTE_TEMPORARY em constantes de atributo Filee também esta postagem de blog É apenas temporário.
• D especifica um arquivo regular que é gravado no disco. A diferença é que ele é excluído automaticamente quando é fechado. Você pode combinar TD para obter ambas as semânticas.

Requerimentos

Para obter mais informações sobre conformidade de padrões e convenções de nomenclatura na biblioteca de tempo de execução C, consulte Compatibility.

Mapeamentos de rotina de texto genérico

Bibliotecas

Todas as versões das bibliotecas de tempo de execução do C.

Exemplo

// crt_fopen_s.c
// This program opens two files. It uses
// fclose to close the first file and
// _fcloseall to close all remaining files.

#include <stdio.h>

FILE *stream, *stream2;

int main( void )
{
   errno_t err;

   // Open for read (will fail if file "crt_fopen_s.c" doesn't exist)
   err  = fopen_s( &stream, "crt_fopen_s.c", "r" );
   if( err == 0 )
   {
      printf( "The file 'crt_fopen_s.c' was opened\n" );
   }
   else
   {
      printf( "The file 'crt_fopen_s.c' was not opened\n" );
   }

   // Open for write
   err = fopen_s( &stream2, "data2", "w+, ccs=UTF-8" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it isn't NULL
   if( stream )
   {
      err = fclose( stream );
      if ( err == 0 )
      {
         printf( "The file 'crt_fopen_s.c' was closed\n" );
      }
      else
      {
         printf( "The file 'crt_fopen_s.c' was not closed\n" );
      }
   }

   // All other files are closed:
   int numclosed = _fcloseall( );
   printf( "Number of files closed by _fcloseall: %u\n", numclosed );
}

The file 'crt_fopen_s.c' was opened
The file 'data2' was opened
Number of files closed by _fcloseall: 1

Ver também

de E/S de fluxo
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode