_open, _wopen

Abre um arquivo. Essas funções foram preteridas porque há versões mais seguras disponíveis; confira _sopen_s, _wsopen_s.

Sintaxe

int _open(
   const char *filename,
   int oflag [,
   int pmode]
);
int _wopen(
   const wchar_t *filename,
   int oflag [,
   int pmode]
);

Parâmetros

filename
Nome do arquivo.

oflag
Os tipos de operações permitidas.

pmode
Modo de permissão.

Valor retornado

Cada uma destas funções mostra um descritor de arquivo do arquivo aberto. Se o valor retornado for -1, é sinal de que há um erro. Nesse caso, a função errno é definida com um dos valores a seguir.

Para obter mais informações sobre esses e outros códigos de retorno, confira errno, _doserrno, _sys_errlist e _sys_nerr.

Comentários

A função _open abre o arquivo especificado por filename e o prepara para leitura ou gravação, como especificado pelo parâmetro oflag. A função _wopen é uma versão de caractere largo da função _open; o argumento filename para _wopen é uma cadeia de caracteres larga. Caso contrário, _wopen e _open se comportam de forma idêntica.

Mapeamentos de rotina de texto genérico

oflag é uma expressão inteira formada por uma ou mais constantes manifestas ou combinações de constantes a seguir, definidas em <fcntl.h>.

Para especificar o modo de acesso ao arquivo, você deve especificar _O_RDONLY, _O_RDWR ou _O_WRONLY. Não há valor padrão para o modo de acesso.

Se a constante _O_WTEXT for usada para abrir um arquivo para leitura, a função _open lê o início do arquivo e verifica se há uma BOM (marca de ordem de byte). Quando há BOM, o arquivo é tratado como UTF-8 ou UTF-16LE, de acordo com a BOM identificada. Quando não há BOM, o arquivo é tratado como ANSI. Quando o arquivo é aberto com a constante _O_WTEXT para gravação, o formato UTF-16 é usado. Independente da configuração ou da marca de ordem de byte anterior, se a constante _O_U8TEXT for usada, o arquivo sempre será aberto como UTF-8; se a constante _O_U16TEXT for usada, o arquivo sempre será aberto como UTF-16.

Quando o arquivo é aberto no modo Unicode com a constante _O_WTEXT, _O_U8TEXT ou _O_U16TEXT, as funções de entrada convertem os dados 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 uma quantidade í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 _open for chamado com _O_WRONLY | _O_APPEND (modo de acréscimo) e _O_WTEXT, _O_U16TEXT ou _O_U8TEXT, ele primeiro tentará abrir o arquivo para leitura e gravação, lerá a BOM e, em seguida, reabrirá o arquivo somente para gravação. Se uma falha impedir de abrir o arquivo para leitura e gravação, ele será aberto somente para gravação e usará o valor padrão na configuração do modo Unicode.

Quando duas ou mais constantes manifestas são usadas para formar o argumento oflag, as constantes são combinadas ao operador OR bit a bit ( | ). Para saber mais sobre os modos de texto e binário, confira E/S de arquivo nos modos de texto e binário.

O argumento pmode só é necessário quando _O_CREAT é especificada. Se o arquivo já existir, o argumento pmode será ignorado. Caso contrário, o argumento pmode especificará as configurações de permissões do arquivo, que são definidas quando o novo arquivo é fechado pela primeira vez. A função _open aplica a máscara de permissão do arquivo ao argumento pmode antes da definição das permissões. Para obter mais informações, consulte _umask. pmode é uma expressão inteiro que contém uma ou ambas as seguintes constantes de manifesto, que são definidas em <sys\stat.h>.

Quando as duas constantes são informadas, elas são ingressadas com o operador OR bit-a-bit (|). Todos os arquivos podem ser lidos no Windows; não há permissão somente gravação. Portanto, os modos _S_IWRITE e _S_IREAD | _S_IWRITE são equivalentes.

Se algum outro valor diferente da combinação de _S_IREAD e _S_IWRITE for especificado para o argumento pmode (mesmo que esse valor especifique um pmode válido em outro sistema operacional) ou se algum outro valor que não os valores permitidos no parâmetro oflag for especificado, a função gera uma asserção no modo de depuração e invoca um manipulador de parâmetros inválido, como descrito em Validação de parâmetro. Se a execução puder continuar, a função retornará um valor -1 e definirá errno como EINVAL.

Requisitos

_open e _wopen são extensões da Microsoft. Para obter informações sobre compatibilidade, consulte Compatibilidade.

Bibliotecas

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

Exemplo

// crt_open.c
// compile with: /W3
/* This program uses _open to open a file
* named CRT_OPEN.C for input and a file named CRT_OPEN.OUT
* for output. The files are then closed.
*/
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <io.h>
#include <stdio.h>

int main( void )
{
   int fh1, fh2;

   fh1 = _open( "CRT_OPEN.C", _O_RDONLY ); // C4996
   // Note: _open is deprecated; consider using _sopen_s instead
   if( fh1 == -1 )
      perror( "Open failed on input file" );
   else
   {
      printf( "Open succeeded on input file\n" );
      _close( fh1 );
   }

   fh2 = _open( "CRT_OPEN.OUT",
                _O_WRONLY | _O_CREAT,
                _S_IREAD | _S_IWRITE ); // C4996
   if( fh2 == -1 )
      perror( "Open failed on output file" );
   else
   {
      printf( "Open succeeded on output file\n" );
      _close( fh2 );
   }
}

Saída

Open succeeded on input file
Open succeeded on output file

Confira também

E/S de baixo nível
_chmod, _wchmod
_close
_creat, _wcreat
_dup, _dup2
fopen, _wfopen
_sopen, _wsopen