fopen, _wfopen

Artigo
03/12/2013

Abre um arquivo.Versões mais seguros dessas funções estão disponíveis; consulte fopen_s, _wfopen_s.

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

Parâmetros

filename
Nome de arquivo.
mode
Tipo de acesso que está ativado.

Valor de retorno

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

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

Comentários

A função de fopen abre o arquivo especificado por filename._wfopen é uma versão de largo- caractere de fopen; os argumentos a _wfopen são cadeias de caracteres de largo- caractere.Caso contrário, _wfopen e fopen se comportam de forma idêntica.Apenas usar _wfopen não tem efeito no conjunto de caracteres codificado que é usado no fluxo de arquivo.

fopen aceita os caminhos que são válidas no sistema de arquivos no ponto de execução; fopen aceita os caminhos UNC e caminhos que envolvem unidades de rede mapeada como o sistema que executa o código tem acesso ao compartilhamento ou a unidade mapeada no momento de execução.Quando você constrói caminhos para fopen, certifique-se que as unidades, os caminhos, ou os compartilhamentos de rede estarão disponíveis no ambiente de execução.Você pode usar barra (/) ou barras invertidas (\) como separadores do diretório no caminho.

Sempre verificar o valor de retorno para ver se o ponteiro é NULO antes que você execute todas as operações adicionais no arquivo.Se ocorrer um erro, a variável global errno está definido e pode ser usado para obter informações de erro específica.Para obter mais informações, consulte errno, _doserrno, _sys_errlist e _sys_nerr.

Suporte a Unicode

fluxos de arquivo Unicode de suporte defopen .Para abrir um arquivo Unicode, passe um sinalizador de ccs que especifica a codificação desejada a fopen, como segue.

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

Os valores permitidos de encoding são UNICODE, UTF-8, e UTF-16LE.

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 sinalizador de ccs .A codificação de ccs é usada somente quando nenhum BOM presente ou o arquivo é um novo arquivo.

Observação
Detecção de BOM 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 que são usados para os vários sinalizadores de ccs dados a fopen e as 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

Escrevendo arquivos abertos no modo Unicode têm um BOM escrito a ele automaticamente.

Se mode é “a, ccs=<encoding>”, fopen tenta primeiro abra o arquivo com ambos acesso de leitura e gravação.Se isso for bem sucedida, a função ler o BOM para determinar a codificação para o arquivo; se isso falhar, a função usa a codificação padrão para o arquivo.Em ambos os casos, fopen reabrirá o arquivo com acesso somente leitura.(Isso se aplica a a o modo somente, não no modo de a+ .)

Mapeamentos da rotina de Genérico- texto

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

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 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 (acrescentar) sem remova o marcador de fim de Arquivo (EOF) antes que os novos dados serem gravados no 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 acrescentar inclui a remoção marcador de EOF antes que os novos dados serem gravados no arquivo.O marcador de EOF não é 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 o tipo de acesso 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 é executada.Portanto, os dados existentes não podem ser substituídos.

O modo de "a" não remove o marcador de EOF antes que acrescenta o arquivo.Após acrescentar ocorreu, o comando de TIPO de MS-DOS mostra somente dados até o marcador de EOF de original e não nenhum dado anexado ao arquivo.Antes que acrescenta ao arquivo, o modo de "a+" remove o marcador de EOF.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 com 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 de posicionamento do arquivo.Funções de posicionamento de arquivo 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 de posicionamento do arquivo.

Além dos valores anteriores, os caracteres a seguir podem ser anexados a 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 EOF na entrada.Em arquivos que estão abertos ler/escrever usando "a+", fopen verifica um CTRL+Z no final do arquivo e remova-o, se possível.Isso é feito como usar fseek e ftell mover dentro de um arquivo que termine com CTRL+Z pode fazer com que fseek se comporta incorretamente próximo da o final do arquivo.

No modo de texto, as combinações de retorno- alimentação de carro são traduzidas em únicas alimentação de entrada, e os caracteres de alimentação de linha são traduzidas as combinações de retorno- alimentação de carro em 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 Texto e o modo binário e/S de arquivo e Unicode fluxo e/S no texto e modos binários.

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
Especifica o conjunto de caracteres codificadas para usar (UTF-8, UTF-16LE, ou UNICODE) para esse arquivo.Deixar não especificado se você deseja a codificação ANSI.

Caracteres válidos para mode caracteres que é usado em fopen e _fdopen corresponde aos argumentos de oflag que são 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 precisa mover o código, e o espera ler a maioria de um arquivo grande ou não estiver preocupado sobre o desempenho de rede, você também pode considerar usar a memória mapeou arquivos Win32 como uma opção.

Requisitos

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

Para obter mais informações sobre a compatibilidade, consulte Compatibilidade.

c, n, t, S, R, T, e opções de Dmode são extensões da Microsoft para fopen e _fdopen e não devem ser usados onde a portabilidade ANSI é desejada.

Exemplo

O seguinte programa abre dois arquivos.Usa fclose para fechar o primeiro arquivo e _fcloseall para fechar todos os outros arquivos.

// 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 );
}

O programa seguir cria um arquivo (ou substitui um se existir), no modo de texto que possui a codificação Unicode.Então escreve duas cadeias de caracteres no arquivo e feche o arquivo.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;
}