fopen, _wfopen

Abre um arquivo. Versões mais seguras dessas funções que executam mais validação de parâmetro e retornam códigos de erro estão disponíveis; confira fopen_s, _wfopen_s.

Sintaxe

FILE *fopen(
   const char *filename,
   const char *mode
);
FILE *_wfopen(
   const wchar_t *filename,
   const wchar_t *mode
);

Parâmetros

filename
Nome do arquivo.

mode
Tipo de acesso habilitado.

Valor retornado

Cada uma dessas funções retorna um ponteiro para o arquivo aberto. Um valor de ponteiro nulo indica um erro. Se filename ou mode for NULL ou uma cadeia de caracteres vazia, essas funções dispararão o manipulador de parâmetro inválido, descrito em Validação de parâmetro. Se a execução puder continuar, essas funções retornarão NULL e definirão errno para EINVAL.

Para obter mais informações, consulte errno, _doserrno, _sys_errlist e _sys_nerr.

Comentários

A fopen função abre o arquivo especificado por filename. Por padrão, uma cadeia de caracteres estreita filename é interpretada usando a página de código ANSI (CP_ACP). Em aplicações de ambiente de trabalho do Windows, pode ser alterado para a página de código OEM (CP_OEMCP) usando a função SetFileApisToOEM. Você pode usar a AreFileApisANSI função para determinar se filename é interpretada usando o ANSI ou a página de código OEM padrão do sistema. _wfopen é uma versão de caracteres largos de fopen; os argumentos _wfopen são cadeias de caracteres largos. Caso contrário, _wfopen e fopen comportam-se de modo idêntico. Apenas usar _wfopen não afeta o conjunto de caracteres codificado usado no fluxo de arquivos.

O fopen aceita caminhos válidos no sistema de arquivos no ponto de execução; o fopen aceita caminhos UNC e caminhos que envolvem unidades de rede mapeadas desde que o sistema que executa o código tenha acesso ao compartilhamento ou à unidade mapeada no momento da execução. Ao construir caminhos para fopeno , certifique-se de que unidades, caminhos ou compartilhamentos de rede estejam disponíveis no ambiente de execução. É possível usar barras (/) ou barras invertidas (\) como separadores de diretório em um caminho.

Sempre verifique o valor retornado para ver se o ponteiro é NULL, antes de realizar qualquer outra operação no arquivo. Se ocorrer um erro, a variável errno global será definida e poderá ser usada para obter informações específicas sobre erros. 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 oferece suporte a fluxos de arquivo Unicode. Para abrir um arquivo Unicode, passe um sinalizador ccs=encodingque especifique a codificação desejada para fopen, da seguinte maneira.

FILE *fp = fopen("newfile.txt", "rt+, ccs=UTF-8");

Os valores permitidos para a codificação ccs são UNICODE, UTF-8 e UTF-16LE.

Quando um arquivo é aberto no modo Unicode, as funções de entrada convertem os dados lidos do arquivo em dados UTF-16 armazenados como tipo wchar_t. Funções que gravam em arquivos abertos no modo Unicode esperam buffers que contenham dados UTF-16 armazenados como tipo wchar_t. Se o arquivo estiver codificado como UTF-8, os dados em UTF-16 serão convertidos em UTF-8 no momento da gravação. O conteúdo codificado em UTF-8 do arquivo é convertido para UTF-16 quando ele é lido. Tentar ler ou gravar um número ímpar de bytes no modo Unicode gera um erro de validação de parâmetro. Para ler ou gravar dados armazenados em seu programa como UTF-8, use um modo de arquivo de texto ou binário em vez do modo Unicode. Você é responsável por toda a conversão de codificação necessária.

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

Observação

A detecção de BOM só se aplica a arquivos abertos no modo Unicode (ou seja, enviando o sinalizador ccs).

A tabela a seguir resume os modos usados para vários sinalizadores ccs dados a fopen e Marcas de Ordem de Byte no arquivo.

Codificações usadas com base em sinalizador ccs e BOM

Sinalizador ccs	Nenhuma BOM (ou novo arquivo)	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

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

Se mode for a, ccs=encoding para algum valor de encoding, fopen primeiro tentará abrir o arquivo usando o acesso de leitura e gravação. Se essa ação tiver êxito, a função lerá a marca de ordem de byte (BOM) para determinar a codificação do arquivo. Se falhar, a função usará a codificação padrão do arquivo. Em ambos os casos, fopen reabre o arquivo usando o acesso somente gravação. (Esse comportamento se aplica apenas ao modo "a" e não ao modo "a+".)

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tfopen	fopen	fopen	_wfopen

A cadeia de caracteres mode especifica o tipo de acesso solicitado para o arquivo como a seguir.

mode	Access
"r"	Abre para leitura. Se o arquivo não existir ou não puder ser encontrado, a chamada fopen 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 o tipo de acesso "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 final do arquivo antes que qualquer operação de gravação seja realizada. Portanto, dados existentes não podem ser substituídos.

O modo "a" não remove o marcador de EOF antes que ele seja anexado ao arquivo. Depois de a conexão ter ocorrido, o comando MS-DOS TYPE só mostra dados até o marcador de EOF original, e não qualquer dado anexado ao arquivo. Antes de anexar ao arquivo, o modo "a+" remove o marcador de EOF. Depois de anexar, o comando MS-DOS TYPE mostra 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, a leitura e a gravação são habilitadas (diz-se que o arquivo está aberto para "atualização"). Porém, ao trocar de leitura para gravação, a operação de entrada deve encontrar um marcador de EOF. Se não houver EOF, use uma chamada intermediária para uma função de posicionamento de arquivo. As funções do posicionamento do arquivo são fsetpos, fseek e rewind. Ao trocar de gravação para leitura, você deve usar uma chamada intermediária para fflush ou uma função de posicionamento de arquivo.

Além dos valores anteriores, os seguintes caracteres podem ser anexados ao mode para especificar o modo de conversão para os caracteres newline.

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. Além disso, CTRL+Z é interpretado como um caractere de fim do 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 de texto, CTRL+Z é interpretado como um caractere EOF na entrada. Em arquivos abertos para leitura/gravação usando "a+"o , fopen 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 comCTRL+ Z pode fazer com fseek que o comportamento seja incorreto perto do final do arquivo.

No modo de texto, combinações de retorno de carro e avanço de linha (CRLF) são convertidas em caracteres únicos de avanç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. Portanto, as funções de entrada de fluxo do Unicode convertem caracteres multibyte para 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 Unicode e E/S de fluxo multibyte, confira E/S de arquivo de modo de texto e binário e E/S de fluxo Unicode em modos de texto e binários.

As opções a seguir podem ser acrescentadas em mode para especificar mais comportamentos.

Modificador mode	Comportamento
x	Força a função a falhar se filename já existir. Só pode ser usado com os especificadores "w" ou "w+".
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 é "sem confirmação", a menos que você vincule explicitamente seu programa ao 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=encoding	Especifica o conjunto de caracteres codificado a ser usado (um de UTF-8, UTF-16LE ou UNICODE) nesse arquivo. Deixe não especificado se desejar codificação ANSI. Esse sinalizador é separado dos sinalizadores que o precedem por uma vírgula (,). Por exemplo: FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");

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

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)
x	_O_EXCL
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 rb, não precisará portar o código. Além disso, se você espera ler a maior parte de um arquivo grande ou tem preocupações com o desempenho da rede, também pode considerar usar arquivos Win32 mapeados em memória como uma opção.

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.

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

Requisitos

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

_wfopen é uma extensão da Microsoft. Para obter mais informações sobre compatibilidade, consulte Compatibilidade.

As copções , n, t, S, R, Te D mode são extensões da Microsoft para fopen e _fdopen não devem ser usadas onde a portabilidade ANSI é desejada.

Exemplo 1

O seguinte programa abre dois arquivos. Ele usa fclose para fechar o primeiro arquivo e _fcloseall para fechar todos os arquivos restantes.

// crt_fopen.c
// compile with: /W3
// 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 )
{
   int numclosed;

   // Open for read (will fail if file "crt_fopen.c" does not exist)
   if( (stream  = fopen( "crt_fopen.c", "r" )) == NULL ) // C4996
   // Note: fopen is deprecated; consider using fopen_s instead
      printf( "The file 'crt_fopen.c' was not opened\n" );
   else
      printf( "The file 'crt_fopen.c' was opened\n" );

   // Open for write
   if( (stream2 = fopen( "data2", "w+" )) == NULL ) // C4996
      printf( "The file 'data2' was not opened\n" );
   else
      printf( "The file 'data2' was opened\n" );

   // Close stream if it is not NULL
   if( stream)
   {
      if ( fclose( stream ) )
      {
         printf( "The file 'crt_fopen.c' was not closed\n" );
      }
   }

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

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

Exemplo 2

O programa a seguir cria um arquivo (ou substitui um, se existir) no modo de texto que usa codificação Unicode. Em seguida, ele grava duas cadeias de caracteres no arquivo e o fecha. A saída é um arquivo chamado _wfopen_test.xml, que contém os dados da seção de saída.

// crt__wfopen.c
// compile with: /W3
// This program creates a file (or overwrites one if
// it exists), in text mode using Unicode encoding.
// It then writes two strings into the file
// and then closes the file.

#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>
#include <wchar.h>

#define BUFFER_SIZE 50

int main(int argc, char** argv)
{
    wchar_t str[BUFFER_SIZE];
    size_t  strSize;
    FILE*   fileHandle;

    // Create an the xml file in text and Unicode encoding mode.
    if ((fileHandle = _wfopen( L"_wfopen_test.xml",L"wt+,ccs=UNICODE")) == NULL) // C4996
    // Note: _wfopen is deprecated; consider using _wfopen_s instead
    {
        wprintf(L"_wfopen failed!\n");
        return(0);
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"<xmlTag>\n");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"</xmlTag>");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Close the file.
    if (fclose(fileHandle))
    {
        wprintf(L"fclose failed!\n");
    }
    return 0;
}

Confira também

E/S de fluxo
Interpretação de sequências de caracteres multibyte
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode
_sopen, _wsopen