fopen_s, _wfopen_s

Abre um arquivo. Essas versões do , _wfopentêm aprimoramentos defopen 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 de arquivo que recebe o ponteiro para o arquivo aberto.

filename
O nome do arquivo a ser aberto.

mode
Tipo de acesso permitido.

Valor retornado

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

Condições de erro

pFile	filename	mode	Valor de retorno	Conteúdo de pFile
NULL	any	any	EINVAL	inalterado
any	NULL	any	EINVAL	inalterado
any	any	NULL	EINVAL	inalterado

Comentários

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 o compartilhamento de leitura/gravação.

A fopen_s função 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 se comportar de forma idêntica, caso contrário.

fopen_s aceita caminhos válidos no sistema de arquivos no ponto de execução; caminhos UNC e caminhos que envolvem unidades de rede mapeadas são aceitas por fopen_s desde que o sistema que executa o código tenha acesso ao compartilhamento ou à unidade de rede mapeada no momento da execução. Quando construir caminhos para fopen_s, não faça pressuposiçõ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.

Essas funções validam seus parâmetros. Se pFile, filename, ou mode for um ponteiro nulo, essas funções gerarão uma exceção de parâmetro inválida, conforme descrito em Validação de parâmetro.

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

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

Suporte de Unicode

O fopen_s oferece suporte a fluxos de arquivo Unicode. Para abrir um arquivo Unicode novo ou existente, passe um sinalizador ccs que especifique 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-8 e UTF-16LE. Se não existir um valor especificado para ccs, fopen_s usará a codificação ANSI.

Se o arquivo já existir e for aberto para ler ou anexar, a BOM (marca de ordem de byte), se presente no arquivo, determinará a codificação. A codificação da BOM tem precedência sobre a codificação especificada pelo sinalizador ccs. A codificação ccs é usada apenas quando nenhuma BOM estiver presente ou se o arquivo for um novo arquivo.

Observação

A detecção da BOM só se aplica a arquivos abertos no modo Unicode, ou seja, passando o sinalizador ccs.

A tabela a seguir resume os modos para vários valores de sinalizador de ccs fornecidos a fopen_s e marcas de ordem de byte no arquivo.

Codificações usadas com base no sinalizador ccs e na marca de ordem de byte

Sinalizador ccs	Nenhuma BOM (ou novo arquivo)	BOM: UTF-8	BOM: UTF-16
UNICODE	UTF-8	UTF-8	UTF-16LE
UTF-8	UTF-8	UTF-8	UTF-16LE
UTF-16LE	UTF-16LE	UTF-8	UTF-16LE

Arquivos abertos para gravação no modo Unicode têm uma BOM gravada neles automaticamente.

Se mode for "a, ccs=UNICODE", "a, ccs=UTF-8" ou "a, ccs=UTF-16LE", fopen_s tentará primeiro abrir o arquivo com acesso de leitura e gravação. Se isso for bem-sucedido, a função lê a BOM para determinar a codificação para o arquivo; se não for bem-sucedido, a função usa a codificação padrão para o arquivo. Em todo caso, fopen_s reabrirá o arquivo com acesso somente gravação. (Esse comportamento se aplica apenas ao modo a, não a a+.)

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

mode	Access
"r"	Abre para leitura. Se o arquivo não existir ou não puder ser encontrado, a chamada fopen_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.

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

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

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ê alterna de leitura para gravação, a operação de entrada deve se deparar com um marcador EOF. Se não houver marcador de EOF, você deverá usar uma chamada intermediária para uma função de posicionamento de arquivo. As funções do posicionamento de arquivo são fsetpos, fseek e rewind. Ao trocar de gravação para leitura, você precisa usar uma chamada intermediária para fflush ou uma função de posicionamento de arquivo.

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.

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

Modificador mode	Modo de conversão
t	Abra no modo de texto (convertido). As combinações de alimentação de linha de retorno de carro (CR-LF) são convertidas em alimentações de linha única (LF) na entrada e os caracteres LF são convertidos em combinações CR-LF na saída. CTRL+Z é interpretado como um caractere de fim de arquivo na entrada.
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 CTRL+de texto (traduzido), Z é interpretado como um caractere de fim de arquivo na entrada. Para arquivos abertos para leitura/gravação com "a+", fopen_s verifica se há umCTRL+ Z no final do arquivo e o remove, se possível. Ele é removido porque usar fseek e ftell mover dentro de um arquivo que termina com umCTRL+ Z pode fazer com fseek que o comportamento seja inadequado perto do final do arquivo.

Além disso, no modo de texto, combinações de retorno de carro/alimentação de linha (CRLF) são convertidas em caracteres únicos de alimentação de linha (LF) na entrada e os caracteres de LF são convertidos 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), presume-se que o fluxo de origem ou destino é uma sequência de caracteres multibyte. As funções de entrada de fluxo do Unicode convertem caracteres multibyte em caracteres largos (como por uma chamada à função mbtowc). Pelo mesmo motivo, as funções de saída de fluxo do Unicode convertem caracteres largos para caracteres multibyte (como por uma chamada à função wctomb).

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 obter mais informações sobre como usar os modos de texto e binário em E/S de fluxo multibyte e Unicode, consulte E/S de arquivo de texto e modo binário e E/S de fluxo Unicode nos modos de texto e binário.

Modificador mode	Comportamento
c	Habilite o sinalizador de confirmação para o filename associado de modo que os conteúdos do buffer de arquivo sejam gravados diretamente no disco, se fflush ou _flushall for chamado.
n	Redefina o sinalizador de confirmação para o filename como "no-commit". Esse sinalizador é o padrão. Também substitui o sinalizador de confirmação global se você vincular o programa a COMMODE.OBJ. O padrão do sinalizador de confirmação global é "no-commit", a menos que você vincule explicitamente seu programa a COMMODE.OBJ (consulte Opções de link).
N	Especifica que o arquivo não é herdado por processos filhos.
S	Especifica que o cache é otimizado para acesso sequencial do disco, mas não se restringe a isso.
R	Especifica que o cache é otimizado para acesso aleatório do disco, mas não se restringe a isso.
T	Especifica um arquivo que não é gravado no disco, a menos que a pressão da memória o exija.
D	Especifica um arquivo temporário que é excluído quando o último ponteiro de arquivo para ele é fechado.
ccs=UNICODE	Especifica UNICODE como o conjunto de caracteres codificado a ser usado para esse arquivo. Deixe não especificado se desejar codificação ANSI.
ccs=UTF-8	Especifica UTF-8 como o conjunto de caracteres codificado a ser usado para esse arquivo. Deixe não especificado se desejar codificação ANSI.
ccs=UTF-16LE	Especifica UTF-16LE como o conjunto de caracteres codificado a ser usado para esse arquivo. Deixe não especificado se desejar codificação ANSI.

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

Caracteres mode na cadeia de caracteres	Valor de oflag equivalente a _open/_sopen
a	_O_WRONLY | _O_APPEND(geralmente _O_WRONLY | _O_CREAT | _O_APPEND)
a+	_O_RDWR | _O_APPEND(geralmente _O_RDWR | _O_APPEND | _O_CREAT)
R	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY(geralmente _O_WRONLY | _O_CREAT | _O_TRUNC)
w+	_O_RDWR (geralmente **_O_RDWR | _O_CREAT | _O_TRUNC)
b	_O_BINARY
t	_O_TEXT (traduzido)
c	Nenhum
n	Nenhum
D	_O_TEMPORARY
R	_O_RANDOM
S	_O_SEQUENTIAL
T	_O_SHORTLIVED
ccs=UNICODE	_O_WTEXT
ccs=UTF-8	_O_UTF8
ccs=UTF-16LE	_O_UTF16

As copções , n, R, S, t, T, e D mode são extensões da Microsoft para fopen_s e _wfopen_s não devem ser usadas quando você deseja portabilidade ANSI.

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

DEm relação e T :

• T evita gravar o arquivo no disco, desde que a pressão da memória não exija isso. Para obter mais informações, consulte FILE_ATTRIBUTE_TEMPORARY em Constantes de atributo de arquivo e também esta postagem no 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.

Requisitos

Função	Cabeçalho necessário	Cabeçalho C++
fopen_s	<stdio.h>	<cstdio>
_wfopen_s	<stdio.h> ou <wchar.h>	<cstdio>

Para obter mais informações sobre as convenções de conformidade e de nomenclatura de padrões na biblioteca de runtime C, confira Compatibilidade.

Mapeamentos de rotina de texto genérico

Rotina <tchar.h>	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tfopen_s	fopen_s	fopen_s	_wfopen_s

Bibliotecas

Todas as versões das bibliotecas em tempo de execução 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

Confira também

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