fopen_s, _wfopen_s

Artigo
03/12/2013

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

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

[out] pFile
Um ponteiro para o ponteiro do arquivo que receberá o ponteiro para o arquivo aberto.
[in] filename
Nome de arquivo.
[in] mode
Tipo de acesso permitido.

Valor de retorno

Zero se com êxito; um código de erro em caso de falha.Consulte errno, _doserrno, _sys_errlist e _sys_nerr para obter mais informações sobre esses códigos de erro.

Condições de erro

pFile	filename	mode	Retornar valor	ConteúdodepFile
NULL	alguns	alguns	EINVAL	inalterado
alguns	NULL	alguns	EINVAL	inalterado
alguns	alguns	NULO	EINVAL	inalterado

Comentários

Os arquivos que estão abertos por fopen_s e por _wfopen_s não são compartilháveis.Se você requer que um arquivo é compartilhável, use _fsopen, _wfsopen com o modo compartilhando apropriado constante- por exemplo, _SH_DENYNO para compartilhar de leitura/gravação.

A função de fopen_s abre o arquivo que é especificado por filename._wfopen_s é uma versão de largo- caractere de fopen_s; os argumentos para _wfopen_s são cadeias de caracteres de largo- caractere._wfopen_s e fopen_s se comportam de forma idêntica.

fopen_s aceita os caminhos que são válidas no sistema de arquivos no ponto de execução; Caminhos UNC e caminhos que envolvem unidades de rede mapeada são aceitados por fopen_s como o sistema que está executando o código tem acesso ao compartilhamento ou a unidade de rede mapeada no momento de execução.Quando você constrói caminhos para fopen_s, não faça suposições sobre a disponibilidade unidades, os caminhos, ou compartilhamento de rede no ambiente de execução.Você pode usar barra (/) ou barras invertidas (\) como separadores do diretório no caminho.

Essas funções validam seus parâmetros.Se pFile, filename, ou mode são um ponteiro zero, essas funções gera uma exceção de parâmetro inválido, como descrito em Validação de parâmetro.

Sempre verificar o valor de retorno para ver se a função teve êxito antes que você execute todas as operações adicionais no arquivo.Se ocorrer um erro, o código de erro é retornado e a variável global errno é definido.Para obter mais informações, consulte errno, _doserrno, _sys_errlist e _sys_nerr.

Suporte a Unicode

fluxos de arquivo Unicode de suporte defopen_s .Para abrir um novo arquivo existente ou Unicode, passe um sinalizador de ccs que especifica a codificação desejada a fopen_s:

fopen_s(&fp, "newfile.txt", "rw, ccs=encoding");

Os valores permitidos de encoding são UNICODE, UTF-8, e UTF-16LE.Se nenhum valor é especificado existem para encoding, fopen_s usa a codificação ANSI.

Se o arquivo existe e é aberto já ler ou concatenar, a marca de pedido de byte (BOM), se presente no arquivo, determina a codificação.A codificação de BOM tem precedência sobre a codificação que é especificado pelo parâmetro de ccs .A codificação de ccs é usada somente quando nenhum BOM estiver presente ou se o arquivo é um novo arquivo.

Observação
a BOM- detecção se aplica somente a arquivos que estão abertos no modo Unicode; isto é, passando o sinalizador de ccs .

A tabela a seguir resume os modos para os vários sinalizadores de ccs que são dados a fopen_s e para marcas de pedido de byte no arquivo.

As codificações usaram-se baseado no sinalizador de ccs e em BOM

sinalizador deccs	Nenhum novo arquivo BOM (ou)	BOM: UTF-8	BOM: UTF-16
UNICODE	UTF-16LE	UTF-8	UTF-16LE
UTF-8	UTF-8	UTF-8	UTF-16LE
UTF-16LE	UTF-16LE	UTF-8	UTF-16LE

Os arquivos que estão abertos no modo escrevendo Unicode têm um BOM escrito a ele automaticamente.

Se mode é “a, ccs=<encoding>”, fopen_s primeiro tenta abrir o arquivo com acesso de leitura e acesso de gravação.Se bem-sucedida, a função lê o BOM para determinar a codificação para o arquivo; se malsucedido, a função usa a codificação padrão para o arquivo.Em ambos os casos, fopen_s então reabra o arquivo com acesso somente leitura.(Isso se aplica a a o modo somente, não a+.)

Mapeamentos da rotina de Genérico- texto

Rotina de TCHAR.H	_UNICODE & _MBCS não definidos	_MBCS definido	_UNICODE definido
_tfopen_s	fopen_s	fopen_s	_wfopen_s

A cadeia de caracteres mode especifica o tipo de acesso que é solicitado para o arquivo, como segue.

"r"
Abre ler.Se o arquivo não existe ou não pode ser encontrado, a chamada de fopen_s falhar.
"w"
Abre um arquivo vazio para gravação.Se o arquivo existe, seu conteúdo são destruídos.
"a"
Escrevendo abre no final do arquivo () sem anexar remova o marcador de EOF antes de gravar novos dados para o arquivo.Cria o arquivo se ele não existir.
"r+"
Abre para a leitura e gravação.(O arquivo deve existir.)
"w+"
Abre um arquivo vazio para a leitura e gravação.Se o arquivo existe, seu conteúdo são destruídos.
"a+"
Abrir e ler acrescentando.A operação acrescentando inclui a remoção de marcador de EOF antes que os novos dados serem gravados no arquivo e o marcador de EOF é restaurado depois que escrever concluída.Cria o arquivo se ele não existir.

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.O ponteiro do arquivo pode ser reposicionado usando fseek ou rewind, mas é movido sempre de volta ao final do arquivo antes que qualquer operação de gravação é realizada de modo que os dados existentes não possam ser substituídos.

O modo de "a" não remove o marcador de EOF antes de acrescentar o arquivo.Após acrescentar ocorreu, os dados mostra o comando de TIPO de MS-DOS até o marcador de EOF de original e não quaisquer dados que são acrescentados para o arquivo.O modo de "a+" remove o marcador de EOF antes de acrescentar o arquivo.Após acrescentar, o comando de TIPO de MS-DOS mostra todos os dados no arquivo.O modo de "a+" é necessário acrescentar a um arquivo de fluxo que é encerrado usando o marcador de CTRL+Z EOF.

Quando "r+","w+", ou o tipo de acesso de "a+" são especificados, a leitura e gravação são permitidas.(O arquivo é aberto para “atualizar”). No entanto, quando você alterna de leitura a escrita, a operação de entrada deve encontrar um marcador de EOF.Se não houver nenhum EOF, você deve usar uma chamada interveniente a uma função particular de posicionamento.As funções do arquivo posicionamento são fsetpos, fseek, e rewind.Quando você alterna a gravação ler, você deve usar uma chamada interveniente a fflush ou a uma função particular de posicionamento.

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

t
Abra no modo de texto (traduzido).Nesse modo, CTRL+Z é interpretado como um caractere de final de Arquivo na entrada.Em arquivos abertos ler/escrever com "a+", fopen_s verifica um CTRL+Z no final do arquivo e remova-o, se possível.Isso é feito usando porque fseek e ftell para mover um arquivo que termine com um CTRL+Z, pode fazer com que fseek se comporta de modo inadequado do final do arquivo.

Além disso, no modo de texto, as combinações de retorno- alimentação de linha de carro são traduzidas em únicas alimentação de linha na entrada, e os caracteres de alimentação de linha são traduzidas as combinações de retorno- alimentação de linha de carro na saída.Quando uma função Unicode stream-I/O opera no modo de texto (o padrão), a origem ou o fluxo de destino é assumido ser uma sequência de caracteres de multibyte.Como consequência, as funções de entrada livre de caracteres Unicode convertem de multibyte para caracteres largos (como se por uma chamada para a função de mbtowc ).Pela mesma razão, as funções livre de saída Unicode para converter caracteres de caracteres de multibyte (como se por uma chamada para a função de wctomb ).

b
Abra no modo (a binário;) as traduções que envolvem caracteres de retorno e de alimentação de linha são suprimidas.

Se t ou b não são dados em mode, o modo padrão de translação é definido pela variável global _fmode.Se t ou b são prefixados para o argumento, a função falha e retorna NULL.

Para obter mais informações sobre como usar modos de texto e de binário em Unicode e em multibyte stream-I/O, consulte O modo de texto e binário E/S de arquivos e Fluxo de E/S Unicode em modos de texto e de binário.

c
Habilitar o sinalizador de confirmação para filename associado para que o conteúdo do buffer de arquivo são gravados diretamente no disco se fflush ou _flushall são chamados.
n
Redefinir o sinalizador de confirmação para filename associado “sem confirmação.” Esse é o padrão.Ela sobrescreve o sinalizador global de confirmação se você vincula seu programa com COMMODE.OBJ.A opção global do sinalizador de confirmação é “sem confirmação” vincular a menos que você explicitamente seu programa com COMMODE.OBJ Opções de link(consulte).
N
Especifica que o arquivo não é herdado por processos filho.
S
Especifica que o cache é otimizado para, mas não restrito, sequencial de acesso a disco.
R
Especifica que o cache é otimizado para, mas não restrito a, de acesso aleatório no disco.
T
Especifica como um arquivo temporário.Se possível, não é solto no disco.
D
Especifica como um arquivo temporário.É excluído quando o ponteiro do arquivo o último é fechado.
ccs=ENCODING
Especificar o conjunto de caracteres codificada para usar (UTF-8, UTF-16LE, e UNICODE) para esse arquivo.Deixe este não especificado se você desejar que a codificação ANSI.

Caracteres válidos para a cadeia de caracteres de mode usada em fopen_s e em _fdopen correspondem aos argumentos de oflag usados em _open e em _sopen, como segue.

Caracteres na cadeia de caracteres de modo	Valor equivalente de oflag para _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
c	Nenhum
n	Nenhum
S	_O_SEQUENTIAL
R	_O_RANDOM
T	_O_SHORTLIVED
D	_O_TEMPORARY
ccs=UNICODE	_O_WTEXT
ccs=UTF-8	_O_UTF8
ccs=UTF-16LE	_O_UTF16

Se você estiver usando o modo de rb , não precisará mover o seu código, e o espera ler muito arquivo e/ou se não importa com o desempenho de rede, os arquivos mapeados memória do Win32 podem também ser uma opção.

Requisitos

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

Para informações extras de compatibilidade Compatibilidade na introdução, consulte.

Bibliotecas

Todas as versões de Bibliotecas em tempo de execução de C.

c, n, e opções de tmode são extensões de O para fopen_s e _fdopen e não devem ser usados onde a portabilidade ANSI é desejada.

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" does not 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+" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it is not 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 );
}