fopen_s, _wfopen_s

Artigo
06/09/2015

Abre um arquivo. Essas versões de fopen, _wfopen têm os aprimoramentos de segurança, conforme 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

[saída] pFile
Um ponteiro para o ponteiro de arquivo que receberá o ponteiro para um arquivo aberto.
[entrada] filename
Nome do arquivo.
[entrada] mode
Tipo de acesso permitido.

Valor de retorno

Zero se tiver êxito; um código de erro em 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	Valor de Retorno	ConteúdodepFile
NULL	any	any	EINVAL	inalterado
any	NULL	any	EINVAL	inalterado
any	any	NULL	EINVAL	inalterado

Comentários

Os arquivos que são abertos por fopen_s e por _wfopen_s não são compartilháveis. Se você precisar que um arquivo seja compartilhável, use _fsopen, _wfsopen com o modo de compartilhamento apropriado de constante para o 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 caractere largo de fopen_s; os argumentos para _wfopen_s são cadeias de caractere amplo. Caso contrário, _wfopen_s e fopen_s, ao contrário, se comportam de forma idêntica.

fopen_s aceita os caminhos que são válidos no sistema de arquivos no momento da execução; Os caminhos UNC e os caminhos que envolvem unidades de rede mapeadas são aceitos por fopen_s como o sistema que está executando o código tem acesso ao compartilhamento ou a unidade de rede mapeada no momento da execução. Quando você constrói caminhos para fopen_s, não faça suposições sobre a disponibilidade das unidades, os caminhos, ou compartilhamentos de rede no ambiente de execução. É possível usar as barras (/) ou as 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 para gerenciar uma exceção inválido do parâmetro, conforme descrito em Validação do parâmetro.

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

Suporte de Unicode

fopen_s oferece suporte aos fluxos de arquivo Unicode. 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 for especificado para encodinglá, fopen_s usa a codificação ANSI.

Se o arquivo existe e é aberto para leitura ou anexando, a marca de ordem de byte (BOM), se presente no arquivo, determina a codificação. A codificação de BOM tem precedência sobre a codificação especificada pelo sinalizador de ccs . A codificação de ccs é usada apenas quando não há BOM estiver presente ou se o arquivo é um arquivo novo.

Dica

a detecção BOM- se aplica apenas aos arquivos que estão abertos no modo de Unicode; ou seja, passando o sinalizador de ccs .

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

Codificações usadas com base no sinalizador de css e BOM

sinalizador de ccs	Nenhuma BOM (ou arquivo novo)	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 são abertos gravando no modo Unicode têm um BOM gravado nela automaticamente.

Se mode é “a, ccs=<encoding>”, fopen_s tenta primeiro abra o arquivo com acesso de leitura e acesso de gravação. Se bem-sucedido, a função leiam a BOM para determinar a codificação para o arquivo; se tiver êxito, a função usa a codificação padrão para o arquivo. Em ambos os casos, fopen_s reabrir o arquivo com acesso somente leitura. (Isso se aplica a a o modo somente online, não a+.)

Mapeamentos da rotina de texto genérico

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

A cadeia de caracteres mode 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 fopen_s falhará.
"w"
Abre um arquivo vazio para gravação. Se o arquivo 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 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 existir, seu conteúdo será destruído.
"a+"
Abre para leitura e acréscimo. 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á cheio. Cria o arquivo se não existir.

Quando um arquivo é aberto usando o tipo de acesso de "a" ou de "a+" , todas as operações de gravação ocorrem no final do arquivo. O ponteiro de arquivo pode ser reposicionado usando fseek ou rewind, mas sempre é movido de volta ao final do arquivo antes que qualquer operação de gravação seja feita de forma que 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 anexar ocorreu, os dados do do comando SORT MS-DOS apenas até o marcador de EOF originais e não dados que estão anexados 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 de "a+" é necessário adicionar a um arquivo do fluxo que é encerrada usando o marcador de EOF CTRL+Z.

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ê alterna de leitura para escrita, a operação de entrada deve encontrar um marcador de EOF. Se não houver nenhum EOF, você deve usar uma chamada de intervenção a uma função de arquivo posicionamento. As funções de arquivo posicionamento são fsetpos, fseek, e rewind. Quando você alterna a gravação da leitura, você deve usar uma chamada de intervenção a fflush ou a uma função de arquivo posicionamento.

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

t
Abrir no modo de texto (traduzido). Nesse modo, CTRL+Z é interpretado como um caractere de participante de Arquivo na entrada. Em arquivos abertos leitura/gravação com "a+", fopen_s verifica se há um CTRL+Z no final do arquivo e solte-o, se possível. Isso é feito porque usando fseek e ftell para mover dentro de um arquivo que termina com um CTRL+Z, pode fazer com que fseek se com comportamento de forma incorreta próximo do fim do arquivo.

Além disso, no modo de texto, as combinações de retorno- avanço de linha de carro são convertidas em únicas avanço de linha na entrada, e os caracteres de alimentação de linha são convertidos em combinações de retorno- avanço de linha de carro na saída. Quando uma função Unicode stream-I/O opera no modo de texto (o padrão), o fluxo de destino e fonte é assumido como uma sequência de caracteres de vários bytes. Portanto, as funções de entrada de fluxo Unicode convertem os caracteres multibytes em caracteres amplos (como uma chamada para a função mbtowc. Pelo mesmo motivo, as funções de saída de fluxo Unicode convertem os caracteres largos em caracteres multibyte (como uma chamada para a função wctomb.

b
Abrir no modo binário (não traduzido); translações envolvendo caracteres de retorno e de alimentação de linha são suprimidos.

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 mais informações sobre como usar os modos de texto e binários em Unicode e em vários stream-I/O, consulte O modo de texto e binários de E/S e Fluxo de E/S Unicode nos modos de texto e binários.

c
Habilite o sinalizador de confirmação para o filename associado de modo que o conteúdo do buffer do arquivo seja gravado diretamente no disco se fflush ou _flushall for chamado.
n
Redefinir o sinalizador de confirmação o filename associado a “sem confirmação”. Esse é o padrão. Também substitui o sinalizador global de confirmação se você vincular seu programa com COMMODE.OBJ. O padrão do sinalizador de confirmação global é "sem confirmação" a não ser que você vincule explicitamente seu programa com o MOMMODE.OBJ (consulte Opções de link).
N
Especifica que o arquivo não é herdado por processos filho.
S
Especifica que armazenar em cache é otimizado para, mas não restrito ao acesso sequencial de disco.
R
Especifica que armazenar em cache é otimizado para, mas não restrito ao acesso aleatório de disco.
T
Especifica um arquivo como temporário. Se possível, não é transmitido ao disco.
D
Especifica um arquivo como temporário. É excluído quando o último ponteiro do arquivo é fechado.
ccs=ENCODING
Especifique o conjunto de caracteres codificado para usar (UTF-8, UTF-16LE, e UNICODE) para esse arquivo. Deixe esse não for especificado se desejar que a codificação ANSI.

Os 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 a seguir.

Caracteres no modo de cadeia de caracteres	Valor de oflag equivalente para _open/_sopen
a	_O_WRONLY \| _O_APPEND (normalmente _O_WRONLY \| _O_CREAT \|_O_APPEND)
a+	_O_RDWR \| _O_APPEND (normalmente _O_RDWR \| _O_APPEND \| _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY (normalmente _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 , o não precisará mover seu código, e o espera ler e/ou muito arquivo não precisa se preocupar com o desempenho da rede, os arquivos mapeados na memória do Win32 podem também ser um padrão.

Requisitos

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

Para informações adicionais de compatibilidade, consulte Compatibilidade na Introdução.

Bibliotecas

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

c, n, e as opções de tmode são extensões da Microsoft para fopen_s e _fdopen e não devem ser usados onde a portabilidade de 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 );
}