fopen, _wfopen

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

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

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.

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

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

Equivalência do .NET Framework

• System::IO::File::Open

• System::IO::FileStream::FileStream

Consulte também

Referência

Fluxo de i/O

Interpretação de seqüências de caracteres Multibyte

fclose, _fcloseall

_fdopen, _wfdopen

ferror

_fileno

freopen, _wfreopen

Open, _wopen

_setmode

_sopen, _wsopen