fopen, _wfopen

Abre um arquivo. Estão disponíveis versões mais seguras destas funções que executam mais validação de parâmetros e códigos de erro de retorno; ver 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 de retorno

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 acionarão o manipulador de parâmetros inválido, que é descrito em Parameter validation. Se a execução for permitida para continuar, essas funções retornarão NULL e definirão errno como EINVAL.

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

Observações

A função fopen abre o arquivo especificado por filename. Por padrão, uma cadeia de caracteres filename estreita é interpretada usando a página de código ANSI (CP_ACP). Em aplicativos da área de trabalho do Windows, ele pode ser alterado para a página de código OEM (CP_OEMCP) usando a função SetFileApisToOEM. Você pode usar a função AreFileApisANSI 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 comportar-se de forma idêntica. O simples uso do _wfopen não afeta o conjunto de caracteres codificados usado no fluxo de arquivos.

fopen aceita caminhos que são válidos no sistema de arquivos no ponto de execuçã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 fopen, certifique-se de que unidades, caminhos ou compartilhamentos de rede estejam disponíveis no ambiente de execução. Você pode usar barras (/) ou barras invertidas (\) como separadores de diretório em um caminho.

Sempre verifique o valor de retorno para ver se o ponteiro é NULL antes de executar quaisquer outras operações no arquivo. Se ocorrer um erro, a variável global errno é definida e pode ser usada para obter informações de erro específicas. Para obter mais informações, consulte errno, _doserrno, _sys_errliste _sys_nerr.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterá-lo, consulte estado global noCRT .

Suporte a Unicode

fopen suporta fluxos de arquivos Unicode. Para abrir um arquivo Unicode, passe um sinalizador de ccs=encoding que especifica a codificação desejada para fopen, da seguinte maneira.

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

Os valores permitidos para codificação ccs são UNICODE, UTF-8e 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. As funções que gravam em um arquivo aberto no modo Unicode esperam buffers que contenham dados UTF-16 armazenados como tipo wchar_t. Se o arquivo for codificado como UTF-8, os dados UTF-16 serão convertidos em UTF-8 quando forem gravados. O conteúdo codificado em UTF-8 do arquivo é traduzido para UTF-16 quando é lido. Uma tentativa de ler ou gravar um número ímpar de bytes no modo Unicode causa um erro de de validação de parâmetro. Para ler ou gravar dados armazenados em seu programa como UTF-8, use um modo de texto ou arquivo binário em vez de um modo Unicode. Você é responsável por qualquer tradução de codificação necessária.

Se o arquivo já existir e estiver aberto para leitura ou acréscimo, qualquer marca de ordem de bytes (BOM) no arquivo determinará a codificação. A codificação BOM tem precedência sobre a codificação especificada pelo sinalizador ccs. A codificação ccs só é usada quando nenhuma lista técnica está presente ou o arquivo é um novo arquivo.

A tabela a seguir resume os modos usados para vários sinalizadores de ccs dados a marcas de ordem de fopen e bytes no arquivo.

Codificações usadas com base no sinalizador ccs e na lista técnica

Os arquivos abertos para gravação no modo Unicode têm uma lista técnica gravada neles automaticamente.

Se mode for a, ccs=encoding para algum valor encoding, fopen primeiro tenta abrir o arquivo usando o acesso de leitura e gravação. Se essa ação for bem-sucedida, a função lê a lista técnica para determinar a codificação do arquivo. Se falhar, a função usa a codificação padrão para o arquivo. Em ambos os casos, fopen reabre o arquivo usando o acesso somente gravação. (Este comportamento aplica-se apenas ao modo "a", não ao modo "a+".)

Mapeamentos de rotina de texto genérico

A cadeia de caracteres mode especifica o tipo de acesso que é solicitado para o arquivo, da seguinte maneira.

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 final 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 executada. Portanto, os dados existentes não podem ser substituídos.

O modo "a" não remove o marcador EOF antes de ser anexado ao arquivo. Após o acréscimo, o comando MS-DOS TYPE mostra apenas os dados até o marcador EOF original e não os dados anexados ao arquivo. Antes de anexar ao arquivo, o modo "a+" remove o marcador EOF. Depois de acrescentar, o comando MS-DOS TYPE mostra todos os dados no arquivo. O modo de "a+" é necessário para anexar a um arquivo de fluxo que é encerrado com o marcador CTRL+Z EOF.

Quando o tipo de acesso "r+", "w+"ou "a+" é especificado, tanto a leitura quanto a gravação são habilitadas (o arquivo é dito estar aberto para "atualização"). No entanto, quando você alterna de leitura para escrita, a operação de entrada deve encontrar um marcador EOF. Se não houver EOF, você deve usar uma chamada intermediária para uma função de posicionamento de arquivo. As funções de posicionamento de arquivo são fsetpos, fseeke rewind. Ao mudar da escrita para a leitura, você deve usar uma chamada intermediária para fflush ou para uma função de posicionamento de arquivo.

Além dos valores anteriores, os seguintes caracteres podem ser acrescentados a mode para especificar o modo de tradução para caracteres de nova linha.

No modo de texto, CTRL+ Z é interpretado como um caractere EOF na entrada. Em arquivos que são abertos para leitura/gravação usando "a+", fopen verifica se há umZ de CTRL+ no final do arquivo e o remove, se possível. Ele é removido porque usar fseek e ftell para mover dentro de um arquivo que termina com CTRL+Z pode fazer com que fseek se comporte incorretamente perto do final do arquivo.

No modo de texto, as combinações de alimentação de linha de retorno de carro (CRLF) são convertidas em caracteres de alimentação de linha única (LF) na entrada e os caracteres LF são traduzidos 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), o fluxo de origem ou destino é assumido como uma sequência de caracteres multibyte. Portanto, as funções de entrada de fluxo Unicode convertem caracteres multibyte em caracteres largos (como se fosse uma chamada para a função mbtowc). Pela mesma razão, as funções de saída de fluxo Unicode convertem caracteres largos em caracteres multibyte (como se fosse por uma chamada para a função wctomb).

Se t ou b não for fornecido no mode, o modo de conversão padrão será definido pela variável global _fmode. Se t ou b estiver prefixado ao argumento, a função falhará e retornará NULL.

Para obter mais informações sobre como usar os modos de texto e binário em Unicode e E/S de fluxo multibyte, consulte E/S de arquivo de texto e modo binário e E/S de fluxo Unicode nos modos de texto e binário.

As opções a seguir podem ser anexadas ao mode para especificar mais comportamentos.

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

Se você estiver usando o modo rb, não precisa portar seu código e, se espera ler a maioria de um arquivo grande ou não está preocupado com o desempenho da rede, também pode considerar se deve usar arquivos Win32 mapeados de memória como uma opção.

Relativamente à T e D:

• T evita gravar o arquivo no disco, desde que a pressão da memória não exija. Para obter mais informações, consulte FILE_ATTRIBUTE_TEMPORARY em constantes de atributo Filee também esta postagem de 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 opções c, n, R, S, t, Te Dmode são extensões da Microsoft para fopen e _wfopen e não devem ser usadas quando você quiser portabilidade ANSI.

Requerimentos

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

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

Exemplo 1

O programa a seguir 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 tem codificação Unicode. Em seguida, ele grava duas cadeias de caracteres no arquivo e fecha 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;
}

Ver também

de 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