Função CreateFileA (fileapi.h)

Cria ou abre um arquivo ou dispositivo de E/S. Os dispositivos de E/S mais usados são os seguintes: arquivo, fluxo de arquivos, diretório, disco físico, volume, buffer de console, unidade de fita, recurso de comunicação, emaillot e pipe. A função retorna um identificador que pode ser usado para acessar o arquivo ou dispositivo para vários tipos de E/S, dependendo do arquivo ou dispositivo e dos sinalizadores e atributos especificados.

Para executar essa operação como uma operação transacionada, que resulta em um identificador que pode ser usado para E/S transacionada, use a função CreateFileTransacted.

Sintaxe

HANDLE CreateFileA(
  [in]           LPCSTR                lpFileName,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwCreationDisposition,
  [in]           DWORD                 dwFlagsAndAttributes,
  [in, optional] HANDLE                hTemplateFile
);

Parâmetros

[in] lpFileName

O nome do arquivo ou dispositivo a ser criado ou aberto. Você pode usar barras (/) ou barras invertidas (\) nesse nome.

Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres de largura, acrescente "\\?\" ao caminho. Para obter mais informações, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.

Ponta

A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima do comprimento do caminho" de arquivos de nomenclatura, caminhos e namespaces para obter detalhes.

Para obter informações sobre nomes de dispositivos especiais, consulte Definindo umde nome de dispositivo MS-DOS.

Para criar um fluxo de arquivos, especifique o nome do arquivo, um dois-pontos e, em seguida, o nome do fluxo. Para obter mais informações, consulte de Fluxos de Arquivos.

[in] dwDesiredAccess

O acesso solicitado ao arquivo ou dispositivo, que pode ser resumido como leitura, gravação ou 0 para indicar nenhum dos dois).

Os valores mais usados são GENERIC_READ, GENERIC_WRITEou ambos (GENERIC_READ | GENERIC_WRITE). Para obter mais informações, consulte genéricos de direitos de acesso, de direitos de acesso e segurança de arquivos, de direitos de acesso a arquivos e ACCESS_MASK.

Se esse parâmetro for zero, o aplicativo poderá consultar determinados metadados, como atributos de arquivo, diretório ou dispositivo sem acessar esse arquivo ou dispositivo, mesmo se GENERIC_READ acesso tivesse sido negado.

Não é possível solicitar um modo de acesso que entre em conflito com o modo de compartilhamento especificado pelo parâmetro dwShareMode em uma solicitação aberta que já tenha um identificador aberto.

Para obter mais informações, consulte a seção Comentários deste tópico e Criando e abrindo arquivos.

[in] dwShareMode

O modo de compartilhamento solicitado do arquivo ou dispositivo, que pode ser lido, gravar, ambos, excluir, todos eles ou nenhum (consulte a tabela a seguir). As solicitações de acesso a atributos ou atributos estendidos não são afetadas por esse sinalizador.

Se esse parâmetro for zero e CreateFile for bem-sucedido, o arquivo ou dispositivo não poderá ser compartilhado e não poderá ser aberto novamente até que o identificador do arquivo ou dispositivo seja fechado. Para obter mais informações, consulte a seção Comentários.

Não é possível solicitar um modo de compartilhamento que entre em conflito com o modo de acesso especificado em uma solicitação existente que tenha um identificador aberto. CreateFile falharia e a função GetLastError retornaria ERROR_SHARING_VIOLATION.

Para habilitar um processo para compartilhar um arquivo ou dispositivo enquanto outro processo tiver o arquivo ou dispositivo aberto, use uma combinação compatível de um ou mais dos valores a seguir. Para obter mais informações sobre combinações válidas desse parâmetro com o parâmetro dwDesiredAccess, consulte Criando e abrindo arquivos.

Observação As opções de compartilhamento para cada identificador aberto permanecem em vigor até que esse identificador seja fechado, independentemente do contexto do processo.
 
Valor Significado
0
0x00000000
Impede que outros processos abram um arquivo ou dispositivo se solicitarem acesso de exclusão, leitura ou gravação.
FILE_SHARE_DELETE
0x00000004
Habilita operações abertas subsequentes em um arquivo ou dispositivo para solicitar acesso de exclusão.

Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem o acesso de exclusão.

Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para exclusão de acesso, a função falhará.

Observação Excluir acesso permite operações de exclusão e renomeação.
 
FILE_SHARE_READ
0x00000001
Permite que as operações abertas subsequentes em um arquivo ou dispositivo solicitem acesso de leitura.

Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem acesso de leitura.

Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para acesso de leitura, a função falhará.

FILE_SHARE_WRITE
0x00000002
Habilita operações abertas subsequentes em um arquivo ou dispositivo para solicitar acesso de gravação.

Caso contrário, outros processos não poderão abrir o arquivo ou o dispositivo se solicitarem acesso de gravação.

Se esse sinalizador não for especificado, mas o arquivo ou dispositivo tiver sido aberto para acesso de gravação ou tiver um mapeamento de arquivo com acesso de gravação, a função falhará.

[in, optional] lpSecurityAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que contém dois membros de dados separados, mas relacionados: um descritor de segurança opcional e um valor booliano que determina se o identificador retornado pode ser herdado por processos filho.

Esse parâmetro pode ser NULL.

Se esse parâmetro for NULL, o identificador retornado por CreateFile não poderá ser herdado por nenhum processo filho que o aplicativo possa criar e o arquivo ou dispositivo associado ao identificador retornado obterá um descritor de segurança padrão.

O lpSecurityDescriptor membro da estrutura especifica um SECURITY_DESCRIPTOR para um arquivo ou dispositivo. Se esse membro estiver NULL, o arquivo ou dispositivo associado ao identificador retornado recebe um descritor de segurança padrão.

CreateFile ignora o membro lpSecurityDescriptor ao abrir um arquivo ou dispositivo existente, mas continua a usar o membro bInheritHandle.

O bInheritHandle membro da estrutura especifica se o identificador retornado pode ser herdado.

Para obter mais informações, consulte a seção Comentários.

[in] dwCreationDisposition

Uma ação a ser tomada em um arquivo ou dispositivo que existe ou não existe.

Para dispositivos que não sejam arquivos, esse parâmetro geralmente é definido como OPEN_EXISTING.

Para obter mais informações, consulte a seção Comentários.

Esse parâmetro deve ser um dos seguintes valores, que não podem ser combinados:

Valor Significado
CREATE_ALWAYS
2
Cria um novo arquivo, sempre.

Se o arquivo especificado existir e for gravável, a função truncará o arquivo, a função terá êxito e o código de último erro será definido como ERROR_ALREADY_EXISTS (183).

Se o arquivo especificado não existir e for um caminho válido, um novo arquivo será criado, a função será bem-sucedida e o código de último erro será definido como zero.

Para obter mais informações, consulte a seção Comentários deste tópico.

CREATE_NEW
1
Cria um novo arquivo, somente se ele ainda não existir.

Se o arquivo especificado existir, a função falhará e o código de último erro será definido como ERROR_FILE_EXISTS (80).

Se o arquivo especificado não existir e for um caminho válido para um local gravável, um novo arquivo será criado.

OPEN_ALWAYS
4
Abre um arquivo, sempre.

Se o arquivo especificado existir, a função terá êxito e o código de último erro será definido como ERROR_ALREADY_EXISTS (183).

Se o arquivo especificado não existir e for um caminho válido para um local gravável, a função criará um arquivo e o código de último erro será definido como zero.

OPEN_EXISTING
3
Abre um arquivo ou dispositivo, somente se ele existir.

Se o arquivo ou dispositivo especificado não existir, a função falhará e o código de último erro será definido como ERROR_FILE_NOT_FOUND (2).

Para obter mais informações sobre dispositivos, consulte a seção Comentários.

TRUNCATE_EXISTING
5
Abre um arquivo e trunca-o para que seu tamanho seja zero bytes, somente se ele existir.

Se o arquivo especificado não existir, a função falhará e o código do último erro será definido como ERROR_FILE_NOT_FOUND (2).

O processo de chamada deve abrir o arquivo com o GENERIC_WRITE bit definido como parte do parâmetro dwDesiredAccess .

[in] dwFlagsAndAttributes

Os atributos e sinalizadores de arquivo ou dispositivo, FILE_ATTRIBUTE_NORMAL sendo o valor padrão mais comum para arquivos.

Esse parâmetro pode incluir qualquer combinação dos atributos de arquivo disponíveis (FILE_ATTRIBUTE_*). Todos os outros atributos de arquivo substituem FILE_ATTRIBUTE_NORMAL.

Esse parâmetro também pode conter combinações de sinalizadores (FILE_FLAG_*) para controle do comportamento de cache de arquivo ou dispositivo, modos de acesso e outros sinalizadores de finalidade especial. Elas combinam-se com quaisquer valores de FILE_ATTRIBUTE_*.

Esse parâmetro também pode conter informações de SQOS (Qualidade de Serviço de Segurança) especificando o sinalizador SECURITY_SQOS_PRESENT. Informações adicionais de sinalizadores relacionados ao SQOS são apresentadas na tabela seguindo as tabelas de atributos e sinalizadores.

Observação Quando CreateFile abre um arquivo existente, geralmente combina os sinalizadores de arquivo com os atributos de arquivo do arquivo existente e ignora todos os atributos de arquivo fornecidos como parte de dwFlagsAndAttributes. Os casos especiais são detalhados em criando e abrindo arquivos.
 
Alguns dos atributos e sinalizadores de arquivo a seguir só podem se aplicar a arquivos e não necessariamente a todos os outros tipos de dispositivos que CreateFile podem abrir. Para obter informações adicionais, consulte a seção Comentários deste tópico e Criando e abrindo arquivos.

Para obter acesso mais avançado a atributos de arquivo, consulte SetFileAttributes. Para obter uma lista completa de todos os atributos de arquivo com seus valores e descrições, consulte Constantes de Atributo de Arquivo.

Atributo Significado
FILE_ATTRIBUTE_ARCHIVE
32 (0x20)
O arquivo deve ser arquivado. Os aplicativos usam esse atributo para marcar arquivos para backup ou remoção.
FILE_ATTRIBUTE_ENCRYPTED
16384 (0x4000)
O arquivo ou diretório é criptografado. Para um arquivo, isso significa que todos os dados no arquivo são criptografados. Para um diretório, isso significa que a criptografia é o padrão para arquivos e subdiretórios recém-criados. Para obter mais informações, consulte de Criptografia de Arquivo.

Esse sinalizador não terá efeito se FILE_ATTRIBUTE_SYSTEM também for especificado.

Esse sinalizador não tem suporte nas edições Home, Home Premium, Starter ou ARM do Windows.

FILE_ATTRIBUTE_HIDDEN
2 (0x2)
O arquivo está oculto. Não inclua-o em uma listagem de diretório comum.
FILE_ATTRIBUTE_NORMAL
128 (0x80)
O arquivo não tem outros atributos definidos. Esse atributo é válido somente se usado sozinho.
FILE_ATTRIBUTE_OFFLINE
4096 (0x1000)
Os dados de um arquivo não estão disponíveis imediatamente. Esse atributo indica que os dados do arquivo são movidos fisicamente para o armazenamento offline. Esse atributo é usado pelo Armazenamento Remoto, o software de gerenciamento de armazenamento hierárquico. Os aplicativos não devem alterar esse atributo arbitrariamente.
FILE_ATTRIBUTE_READONLY
1 (0x1)
O arquivo é somente leitura. Os aplicativos podem ler o arquivo, mas não podem gravá-lo ou excluí-lo.
FILE_ATTRIBUTE_SYSTEM
4 (0x4)
O arquivo faz parte ou é usado exclusivamente por um sistema operacional.
FILE_ATTRIBUTE_TEMPORARY
256 (0x100)
O arquivo está sendo usado para armazenamento temporário.

Para obter mais informações, consulte a seção Comportamento de Cache deste tópico.

 
Bandeira Significado
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
O arquivo está sendo aberto ou criado para uma operação de backup ou restauração. O sistema garante que o processo de chamada substitua as verificações de segurança de arquivo quando o processo tiver privilégios de SE_BACKUP_NAME e SE_RESTORE_NAME. Para obter mais informações, consulte Alterando privilégios em um token.

Você deve definir esse sinalizador para obter um identificador para um diretório. Um identificador de diretório pode ser passado para algumas funções em vez de um identificador de arquivo. Para obter mais informações, consulte a seção Comentários.

FILE_FLAG_DELETE_ON_CLOSE
0x04000000
O arquivo deve ser excluído imediatamente depois que todos os seus identificadores forem fechados, o que inclui o identificador especificado e quaisquer outras alças abertas ou duplicadas.

Se houver identificadores abertos existentes em um arquivo, a chamada falhará, a menos que todas elas tenham sido abertas com o modo de compartilhamento FILE_SHARE_DELETE.

As solicitações abertas subsequentes para o arquivo falham, a menos que o modo de compartilhamento FILE_SHARE_DELETE seja especificado.

FILE_FLAG_NO_BUFFERING
0x20000000
O arquivo ou dispositivo está sendo aberto sem cache do sistema para leituras e gravações de dados. Esse sinalizador não afeta o cache de disco rígido ou os arquivos mapeados de memória.

Há requisitos estritos para trabalhar com êxito com arquivos abertos com CreateFile usando o sinalizador FILE_FLAG_NO_BUFFERING, para obter detalhes, consulte de Buffer de Arquivos.

FILE_FLAG_OPEN_NO_RECALL
0x00100000
Os dados do arquivo são solicitados, mas devem continuar localizados no armazenamento remoto. Ele não deve ser transportado de volta para o armazenamento local. Esse sinalizador é usado por sistemas de armazenamento remoto.
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
O ponto de nova análise normal processamento não ocorrerá; CreateFile tentará abrir o ponto de nova análise. Quando um arquivo é aberto, um identificador de arquivo é retornado, independentemente de o filtro que controla o ponto de nova análise estar operacional.

Esse sinalizador não pode ser usado com o sinalizador CREATE_ALWAYS.

Se o arquivo não for um ponto de nova análise, esse sinalizador será ignorado.

Para obter mais informações, consulte a seção Comentários.

FILE_FLAG_OVERLAPPED
0x40000000
O arquivo ou dispositivo está sendo aberto ou criado para E/S assíncrona.

Quando as operações de E/S subsequentes forem concluídas nesse identificador, o evento especificado na estrutura OVERLAPPED será definido como o estado sinalizado.

Se esse sinalizador for especificado, o arquivo poderá ser usado para operações simultâneas de leitura e gravação.

Se esse sinalizador não for especificado, as operações de E/S serão serializadas, mesmo que as chamadas para as funções de leitura e gravação especifiquem uma estrutura OVERLAPPED.

Para obter informações sobre considerações ao usar um identificador de arquivo criado com esse sinalizador, consulte a seção Identificadores de E/S Síncronos e Assíncronos seção deste tópico.

FILE_FLAG_POSIX_SEMANTICS
0x01000000
O acesso ocorrerá de acordo com as regras POSIX. Isso inclui permitir vários arquivos com nomes, diferentes apenas no caso, para sistemas de arquivos que dão suporte a essa nomenclatura. Use cuidado ao usar essa opção, pois os arquivos criados com esse sinalizador podem não estar acessíveis por aplicativos que são gravados para o Windows de MS-DOS ou de 16 bits.
FILE_FLAG_RANDOM_ACCESS
0x10000000
O acesso destina-se a ser aleatório. O sistema pode usar isso como uma dica para otimizar o cache de arquivos.

Esse sinalizador não terá efeito se o sistema de arquivos não der suporte a E/S armazenada em cache e FILE_FLAG_NO_BUFFERING.

Para obter mais informações, consulte a seção Comportamento de Cache deste tópico.

FILE_FLAG_SESSION_AWARE
0x00800000
O arquivo ou dispositivo está sendo aberto com reconhecimento de sessão. Se esse sinalizador não for especificado, os dispositivos por sessão (como um dispositivo que usa o Redirecionamento USB RemoteFX) não poderão ser abertos por processos em execução na sessão 0. Esse sinalizador não tem efeito para os chamadores que não estão na sessão 0. Esse sinalizador tem suporte apenas em edições de servidor do Windows.

Windows Server 2008 R2 e Windows Server 2008: Esse sinalizador não tem suporte antes do Windows Server 2012.

FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
O acesso destina-se a ser sequencial do início ao fim. O sistema pode usar isso como uma dica para otimizar o cache de arquivos.

Esse sinalizador não deverá ser usado se o read-behind (ou seja, verificações inversa) for usado.

Esse sinalizador não terá efeito se o sistema de arquivos não der suporte a E/S armazenada em cache e FILE_FLAG_NO_BUFFERING.

Para obter mais informações, consulte a seção Comportamento de Cache deste tópico.

FILE_FLAG_WRITE_THROUGH
0x80000000
As operações de gravação não passarão por nenhum cache intermediário, elas irão diretamente para o disco.

Para obter informações adicionais, consulte a seção comportamento de cache deste tópico.

 

O parâmetro dwFlagsAndAttributes também pode especificar informações do SQOS. Para obter mais informações, consulte níveis de representação. Quando o aplicativo de chamada especifica o sinalizador SECURITY_SQOS_PRESENT como parte de dwFlagsAndAttributes, ele também pode conter um ou mais dos valores a seguir.

Sinalizador de segurança Significado
SECURITY_ANONYMOUS
Representa um cliente no nível de representação anônima.
SECURITY_CONTEXT_TRACKING
O modo de acompanhamento de segurança é dinâmico. Se esse sinalizador não for especificado, o modo de controle de segurança será estático.
SECURITY_DELEGATION
Representa um cliente no nível de representação de delegação.
SECURITY_EFFECTIVE_ONLY
Somente os aspectos habilitados do contexto de segurança do cliente estão disponíveis para o servidor. Se você não especificar esse sinalizador, todos os aspectos do contexto de segurança do cliente estarão disponíveis.

Isso permite que o cliente limite os grupos e privilégios que um servidor pode usar ao representar o cliente.

SECURITY_IDENTIFICATION
Representa um cliente no nível de representação de identificação.
SECURITY_IMPERSONATION
Represente um cliente no nível de representação. Esse é o comportamento padrão se nenhum outro sinalizador for especificado junto com o sinalizador SECURITY_SQOS_PRESENT.

[in, optional] hTemplateFile

Um identificador válido para um arquivo de modelo com o GENERIC_READ direito de acesso. O arquivo de modelo fornece atributos de arquivo e atributos estendidos para o arquivo que está sendo criado.

Esse parâmetro pode ser NULL.

Ao abrir um arquivo existente, CreateFile ignora esse parâmetro.

Ao abrir um novo arquivo criptografado, o arquivo herda a lista de controle de acesso discricionário de seu diretório pai. Para obter informações adicionais, consulte de Criptografia de Arquivo.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será um identificador aberto para o arquivo, dispositivo, pipe nomeado ou slot de email especificado.

Se a função falhar, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.

Observações

CreateFile foi originalmente desenvolvido especificamente para interação de arquivos, mas desde então foi expandido e aprimorado para incluir a maioria dos outros tipos de dispositivos e mecanismos de E/S disponíveis para desenvolvedores do Windows. Esta seção tenta abordar os diversos problemas que os desenvolvedores podem enfrentar ao usar CreateFile em contextos diferentes e com diferentes tipos de E/S. O texto tenta usar a palavra arquivo somente ao se referir especificamente aos dados armazenados em um arquivo real em um sistema de arquivos. No entanto, alguns usos de arquivo podem estar se referindo de forma mais geral a um objeto de E/S que dá suporte a mecanismos semelhantes a arquivos. Esse uso liberal do termo de arquivo é particularmente predominante em nomes constantes e nomes de parâmetros devido às razões históricas mencionadas anteriormente.

Quando um aplicativo for concluído usando o identificador de objeto retornado por CreateFile, use a função CloseHandle para fechar o identificador. Isso não só libera recursos do sistema, mas pode ter maior influência em itens como compartilhar o arquivo ou dispositivo e confirmar dados em disco. As especificações são indicadas neste tópico conforme apropriado.

Windows Server 2003 e Windows XP: Uma violação de compartilhamento ocorrerá se for feita uma tentativa de abrir um arquivo ou diretório para exclusão em um computador remoto quando o valor do parâmetro dwDesiredAccess for o DELETE sinalizador de acesso (0x00010000) OU'ed com qualquer outro sinalizador de acesso, sinalizador de acesso e o arquivo ou diretório remoto não foi aberto com FILE_SHARE_DELETE. Para evitar a violação de compartilhamento nesse cenário, abra o arquivo remoto ou o diretório com o DELETE acesso somente direito ou chame DeleteFile sem abrir primeiro o arquivo ou o diretório para exclusão.

Alguns sistemas de arquivos, como o sistema de arquivos NTFS, dão suporte à compactação ou criptografia para arquivos e diretórios individuais. Em volumes que têm um sistema de arquivos montado com esse suporte, um novo arquivo herda os atributos de compactação e criptografia de seu diretório.

Você não pode usar CreateFile para controlar a compactação, a descompactação ou a descriptografia em um arquivo ou diretório. Para obter mais informações, consulte Criando e abrindo arquivos, de compactação e descompactação de arquivos e de criptografia de arquivo.

Windows Server 2003 e Windows XP: Para fins de compatibilidade com versões anteriores, CreateFile não aplica regras de herança quando você especifica um descritor de segurança em lpSecurityAttributes. Para dar suporte à herança, as funções que posteriormente consultam o descritor de segurança desse arquivo podem determinar e relatar heuristicamente que a herança está em vigor. Para obter mais informações, consulte Propagação automática de ACEs herdáveis.

Conforme indicado anteriormente, se o parâmetro lpSecurityAttributes for NULL, o identificador retornado por CreateFile não poderá ser herdado por nenhum processo filho que seu aplicativo possa criar. As seguintes informações sobre esse parâmetro também se aplicam:

  • Se a variável bInheritHandle membro não for FALSE, que é qualquer valor diferente de zero, o identificador poderá ser herdado. Portanto, é fundamental que esse membro da estrutura seja inicializado corretamente para FALSE se você não pretende que o identificador seja herdável.
  • As ACL (listas de controle de acesso) no descritor de segurança padrão para um arquivo ou diretório são herdadas de seu diretório pai.
  • O sistema de arquivos de destino deve dar suporte à segurança em arquivos e diretórios para que o membro lpSecurityDescriptor tenha um efeito sobre eles, o que pode ser determinado usando GetVolumeInformation.
No Windows 8 e no Windows Server 2012, essa função é compatível com as tecnologias a seguir.
Tecnologia Suportado
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0 Sim
TFO (Failover Transparente) do SMB 3.0 Ver comentários
SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO) Ver comentários
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS) Sim
ReFS (Sistema de Arquivos Resiliente) Sim
 

Observe que CreateFile com disposição substituída falhará se executado em um arquivo em que já há um fluxo de dados alternativo aberto.

comportamento simbólico de vínculo

Se a chamada para essa função criar um arquivo, não haverá nenhuma alteração no comportamento. Além disso, considere as seguintes informações sobre FILE_FLAG_OPEN_REPARSE_POINT:
  • Se FILE_FLAG_OPEN_REPARSE_POINT for especificado:
    • Se um arquivo existente for aberto e for um link simbólico, o identificador retornado será um identificador para o link simbólico.
    • Se TRUNCATE_EXISTING ou FILE_FLAG_DELETE_ON_CLOSE forem especificados, o arquivo afetado será um link simbólico.
  • Se FILE_FLAG_OPEN_REPARSE_POINT não for especificado:
    • Se um arquivo existente for aberto e for um link simbólico, o identificador retornado será um identificador para o destino.
    • Se CREATE_ALWAYS, TRUNCATE_EXISTINGou FILE_FLAG_DELETE_ON_CLOSE forem especificados, o arquivo afetado será o destino.

comportamento de cache

Vários dos valores possíveis para o parâmetro dwFlagsAndAttributes são usados por CreateFile para controlar ou afetar como os dados associados ao identificador são armazenados em cache pelo sistema. Eles são:
  • FILE_FLAG_NO_BUFFERING
  • FILE_FLAG_RANDOM_ACCESS
  • FILE_FLAG_SEQUENTIAL_SCAN
  • FILE_FLAG_WRITE_THROUGH
  • FILE_ATTRIBUTE_TEMPORARY
Se nenhum desses sinalizadores for especificado, o sistema usará um esquema de cache de uso geral padrão. Caso contrário, o cache do sistema se comportará conforme especificado para cada sinalizador.

Alguns desses sinalizadores não devem ser combinados. Por exemplo, combinar FILE_FLAG_RANDOM_ACCESS com FILE_FLAG_SEQUENTIAL_SCAN é autodestrutivo.

Especificar o sinalizador FILE_FLAG_SEQUENTIAL_SCAN pode aumentar o desempenho de aplicativos que leem arquivos grandes usando acesso sequencial. Os ganhos de desempenho podem ser ainda mais perceptíveis para aplicativos que leem arquivos grandes principalmente sequencialmente, mas ocasionalmente pulam para frente em pequenos intervalos de bytes. Se um aplicativo mover o ponteiro de arquivo para acesso aleatório, o melhor desempenho de cache provavelmente não ocorrerá. No entanto, a operação correta ainda está garantida.

Os sinalizadores FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING são independentes e podem ser combinados.

Se FILE_FLAG_WRITE_THROUGH for usado, mas FILE_FLAG_NO_BUFFERING também não for especificado, para que o cache do sistema esteja em vigor, os dados serão gravados no cache do sistema, mas liberados para o disco sem atraso.

Se FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING forem especificados, para que o cache do sistema não esteja em vigor, os dados serão imediatamente liberados para o disco sem passar pelo cache do sistema Windows. O sistema operacional também solicita uma gravação do cache de hardware local do disco rígido para mídia persistente.

Observação Nem todo o hardware de disco rígido dá suporte a essa funcionalidade de gravação.
 
O uso adequado do sinalizador de FILE_FLAG_NO_BUFFERING requer considerações especiais sobre o aplicativo. Para obter mais informações, consulte de Buffer de Arquivos.

Uma solicitação de gravação por meio de FILE_FLAG_WRITE_THROUGH também faz com que o NTFS libere quaisquer alterações de metadados, como uma atualização de carimbo de data/hora ou uma operação de renomeação, resultante do processamento da solicitação. Por esse motivo, o sinalizador FILE_FLAG_WRITE_THROUGH geralmente é usado com o sinalizador FILE_FLAG_NO_BUFFERING como uma substituição para chamar a função FlushFileBuffers após cada gravação, o que pode causar penalidades de desempenho desnecessárias. Usar esses sinalizadores juntos evita essas penalidades. Para obter informações gerais sobre o cache de arquivos e metadados, consulte Cache de Arquivos.

Quando FILE_FLAG_NO_BUFFERING é combinado com FILE_FLAG_OVERLAPPED, os sinalizadores dão o máximo de desempenho assíncrono, pois a E/S não depende das operações síncronas do gerenciador de memória. No entanto, algumas operações de E/S levam mais tempo, pois os dados não estão sendo mantidos no cache. Além disso, os metadados de arquivo ainda podem ser armazenados em cache (por exemplo, ao criar um arquivo vazio). Para garantir que os metadados sejam liberados para o disco, use a função FlushFileBuffers.

Especificar o atributo FILE_ATTRIBUTE_TEMPORARY faz com que os sistemas de arquivos evitem gravar dados de volta no armazenamento em massa se houver memória de cache suficiente disponível, pois um aplicativo exclui um arquivo temporário depois que um identificador é fechado. Nesse caso, o sistema pode evitar totalmente a gravação dos dados. Embora não controle diretamente o cache de dados da mesma forma que os sinalizadores mencionados anteriormente, o atributo FILE_ATTRIBUTE_TEMPORARY diz ao sistema para manter o máximo possível no cache do sistema sem gravar e, portanto, pode ser preocupante para determinados aplicativos.

Arquivos

Se você renomear ou excluir um arquivo e restaurá-lo pouco depois, o sistema pesquisará no cache informações de arquivo para restaurar. As informações armazenadas em cache incluem seu par de nomes curto/longo e tempo de criação.

Se você chamar CreateFile em um arquivo que está pendente de exclusão como resultado de uma chamada anterior para DeleteFile, a função falhará. O sistema operacional atrasa a exclusão de arquivos até que todos os identificadores do arquivo sejam fechados. GetLastError retorna ERROR_ACCESS_DENIED.

O parâmetro dwDesiredAccess pode ser zero, permitindo que o aplicativo consulte atributos de arquivo sem acessar o arquivo se o aplicativo estiver em execução com configurações de segurança adequadas. Isso é útil para testar a existência de um arquivo sem abri-lo para acesso de leitura e/ou gravação ou para obter outras estatísticas sobre o arquivo ou diretório. Consulte Obter e definir informações de arquivo e getFileInformationByHandle.

Se CREATE_ALWAYS e FILE_ATTRIBUTE_NORMAL forem especificados, CreateFile falhar e definirá o último erro para ERROR_ACCESS_DENIED se o arquivo existir e tiver o atributo FILE_ATTRIBUTE_HIDDEN ou FILE_ATTRIBUTE_SYSTEM. Para evitar o erro, especifique os mesmos atributos que o arquivo existente.

Quando um aplicativo cria um arquivo em uma rede, é melhor usar GENERIC_READ | GENERIC_WRITE para dwDesiredAccess do que usar GENERIC_WRITE sozinho. O código resultante é mais rápido, pois o redirecionador pode usar o gerenciador de cache e enviar menos SMBs com mais dados. Essa combinação também evita um problema em que gravar em um arquivo em uma rede pode ocasionalmente retornar ERROR_ACCESS_DENIED.

Para obter mais informações, consulte Criando e abrindo arquivos.

identificadores de E/S síncronos e assíncronos

CreateFile fornece a criação de um identificador de arquivo ou dispositivo que seja síncrono ou assíncrono. Um identificador síncrono se comporta de modo que as chamadas de função de E/S usando esse identificador sejam bloqueadas até que sejam concluídas, enquanto um identificador de arquivo assíncrono possibilita que o sistema retorne imediatamente das chamadas de função de E/S, independentemente de terem concluído a operação de E/S ou não. Conforme indicado anteriormente, esse comportamento síncrono versus assíncrono é determinado especificando FILE_FLAG_OVERLAPPED dentro do parâmetro dwFlagsAndAttributes. Há várias complexidades e possíveis armadilhas ao usar E/S assíncrona; para obter mais informações, consulte de E/S síncrono e assíncrono.

fluxos de arquivos

Em sistemas de arquivos NTFS, você pode usar CreateFile para criar fluxos separados em um arquivo. Para obter mais informações, consulte de Fluxos de Arquivos.

Diretórios de

Um aplicativo não pode criar um diretório usando CreateFile, portanto, somente o valor OPEN_EXISTING é válido para dwCreationDisposition para esse caso de uso. Para criar um diretório, o aplicativo deve chamar CreateDirectory ou CreateDirectoryEx.

Para abrir um diretório usando CreateFile, especifique o sinalizador FILE_FLAG_BACKUP_SEMANTICS como parte de dwFlagsAndAttributes. As verificações de segurança apropriadas ainda se aplicam quando esse sinalizador é usado sem privilégios de SE_BACKUP_NAME e SE_RESTORE_NAME.

Ao usar CreateFile para abrir um diretório durante a desfragmentação de um volume de sistema de arquivos FAT ou FAT32, não especifique o direito de acesso MAXIMUM_ALLOWED. O acesso ao diretório será negado se isso for feito. Em vez disso, especifique o acesso GENERIC_READ direito.

Para obter mais informações, consulte About Directory Management.

discos físicos e volumes

O acesso direto ao disco ou a um volume é restrito.

Windows Server 2003 e Windows XP: acesso direto ao disco ou a um volume não é restrito dessa maneira.

Você pode usar a função CreateFile para abrir uma unidade de disco física ou um volume, que retorna um identificador DASD (dispositivo de armazenamento de acesso direto) que pode ser usado com a função DeviceIoControl. Isso permite que você acesse o disco ou o volume diretamente, por exemplo, metadados de disco como a tabela de partição. No entanto, esse tipo de acesso também expõe a unidade de disco ou o volume a uma possível perda de dados, pois uma gravação incorreta em um disco usando esse mecanismo pode tornar seu conteúdo inacessível ao sistema operacional. Para garantir a integridade dos dados, familiarize-se com DeviceIoControl e como outras APIs se comportam de forma diferente com um identificador de acesso direto em vez de um identificador do sistema de arquivos.

Os seguintes requisitos devem ser atendidos para que essa chamada seja bem-sucedida:

  • O chamador deve ter privilégios administrativos. Para obter mais informações, consulte Em execução com privilégios especiais.
  • O parâmetro dwCreationDisposition deve ter o sinalizador OPEN_EXISTING.
  • Ao abrir um volume ou disquete, o parâmetro dwShareMode deve ter o sinalizador FILE_SHARE_WRITE.
Observação o parâmetro dwDesiredAccess pode ser zero, permitindo que o aplicativo consulte atributos de dispositivo sem acessar um dispositivo. Isso é útil para um aplicativo determinar o tamanho de uma unidade de disco disquete e os formatos aos quais ele dá suporte sem a necessidade de um disquete em uma unidade, por exemplo. Ele também pode ser usado para ler estatísticas sem exigir permissão de leitura/gravação de dados de nível superior.
 
Ao abrir uma unidade física x:, a cadeia de caracteres lpFileName deve ser a seguinte forma: "\\.\PhysicalDriveX". Os números de disco rígido começam em zero. A tabela a seguir mostra alguns exemplos de cadeias de caracteres de unidade física.
Corda Significado
"\\.\PhysicalDrive0" Abre a primeira unidade física.
"\\.\PhysicalDrive2" Abre a terceira unidade física.
 

Para obter o identificador de unidade física para um volume, abra um identificador para o volume e chame a função DeviceIoControl com IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Esse código de controle retorna o número do disco e o deslocamento para cada uma ou mais extensões do volume; um volume pode abranger vários discos físicos.

Para obter um exemplo de como abrir uma unidade física, consulte Chamando DeviceIoControl.

Ao abrir um volume ou uma unidade de mídia removível (por exemplo, uma unidade de disco disquete ou uma unidade de memória flash), o lpFileName cadeia de caracteres deve ser a seguinte forma: "\\.\X:". Não use uma barra invertida à direita (\), que indica o diretório raiz de uma unidade. A tabela a seguir mostra alguns exemplos de cadeias de caracteres de unidade.

Corda Significado
"\\.\A:" Abre a unidade de disco disquete A.
"\\.\C:" Abre o volume C: .
"\\.\C:\" Abre o sistema de arquivos do volume C:.
 

Você também pode abrir um volume referindo-se ao nome do volume. Para obter mais informações, consulte Nomeando um volume.

Um volume contém um ou mais sistemas de arquivos montados. Os identificadores de volume podem ser abertos como não armazenados a critério do sistema de arquivos específico, mesmo quando a opção não em cache não é especificada no CreateFile. Você deve assumir que todos os sistemas de arquivos da Microsoft abrem identificadores de volume como não armazenados em cache. As restrições de E/S não em cache para arquivos também se aplicam a volumes.

Um sistema de arquivos pode ou não exigir alinhamento de buffer mesmo que os dados não sejam armazenados em cache. No entanto, se a opção não armazenada em cache for especificada ao abrir um volume, o alinhamento do buffer será imposto independentemente do sistema de arquivos no volume. É recomendável em todos os sistemas de arquivos que você abra identificadores de volume como não armazenados em cache e siga as restrições de E/S não localizadas.

Observação Para ler ou gravar nos últimos setores do volume, você deve chamar DeviceIoControl e especificar FSCTL_ALLOW_EXTENDED_DASD_IO. Isso sinaliza que o driver do sistema de arquivos não executará nenhuma verificação de limite de E/S em chamadas de leitura ou gravação de partição. Em vez disso, as verificações de limite são executadas pelo driver do dispositivo.
 

Dispositivo changer

Os IOCTL_CHANGER_* códigos de controle para DeviceIoControl aceitar um identificador para um dispositivo de alteração. Para abrir um dispositivo de alteração, use um nome de arquivo do seguinte formulário: "\\.\Changerx" em que x é um número que indica qual dispositivo abrir, começando com zero. Para abrir o dispositivo de alteração zero em um aplicativo escrito em C ou C++, use o seguinte nome de arquivo: "\\.\Changer0".

unidades de fita

Você pode abrir unidades de fita usando um nome de arquivo do seguinte formulário: "\\.\TAPEx" em que x é um número que indica qual unidade abrir, começando com a unidade de fita zero. Para abrir a unidade de fita zero em um aplicativo escrito em C ou C++, use o seguinte nome de arquivo: "\\.\TAPE0".

Para obter mais informações, consulte Backup.

recursos de comunicação

A função CreateFile pode criar um identificador para um recurso de comunicação, como a porta serial COM1. Para recursos de comunicação, o parâmetro
dwCreationDisposition deve ser OPEN_EXISTING, o parâmetro dwShareMode deve ser zero (acesso exclusivo) e o parâmetro hTemplateFile deve ser NULL. O acesso de leitura, gravação ou leitura/gravação pode ser especificado e o identificador pode ser aberto para E/S sobreposta.

Para especificar um número de porta COM maior que 9, use a seguinte sintaxe: "\\.\COM10". Essa sintaxe funciona para todos os números de porta e hardware que permitem que os números da porta COM sejam especificados.

Para obter mais informações sobre comunicações, consulte Communications.

Consoles do

A função CreateFile pode criar um identificador para entrada do console (CONIN$). Se o processo tiver um identificador aberto como resultado de herança ou duplicação, ele também poderá criar um identificador para o buffer de tela ativo (CONOUT$). O processo de chamada deve ser anexado a um console herdado ou alocado pela função
AllocConsole. Para identificadores de console, defina os parâmetros CreateFile da seguinte maneira.
Parâmetros Valor
lpFileName Use o valor CONIN$ para especificar a entrada do console.

Use o valor CONOUT$ para especificar a saída do console.

CONIN$ obtém um identificador para o buffer de entrada do console, mesmo que a função SetStdHandle redirecione o identificador de entrada padrão. Para obter o identificador de entrada padrão, use a função GetStdHandle.

CONOUT$ obtém um identificador para o buffer de tela ativo, mesmo que SetStdHandle redirecione o identificador de saída padrão. Para obter o identificador de saída padrão, use GetStdHandle.

dwDesiredAccess GENERIC_READ | GENERIC_WRITE é preferível, mas qualquer um deles pode limitar o acesso.
dwShareMode Ao abrir CONIN$, especifique FILE_SHARE_READ. Ao abrir CONOUT$, especifique FILE_SHARE_WRITE.

Se o processo de chamada herdar o console ou se um processo filho deve ser capaz de acessar o console, esse parâmetro deve ser FILE_SHARE_READ | FILE_SHARE_WRITE.

lpSecurityAttributes Se você quiser que o console seja herdado, o membro bInheritHandle da estrutura SECURITY_ATTRIBUTES deverá ser VERDADEIRO.
dwCreationDisposition Você deve especificar OPEN_EXISTING ao usar CreateFile para abrir o console.
dwFlagsAndAttributes Ignorado.
hTemplateFile Ignorado.
 

A tabela a seguir mostra várias configurações de dwDesiredAccess e lpFileName.

lpFileName dwDesiredAccess Resultado
"CON" GENERIC_READ Abre o console para entrada.
"CON" GENERIC_WRITE Abre o console para saída.
"CON" GENERIC_READ | GENERIC_WRITE Faz com que CreateFile falhe; GetLastError retorna ERROR_FILE_NOT_FOUND.
 

Emailslots

Se CreateFile abrir o fim do cliente de um emaillot, a função retornará INVALID_HANDLE_VALUE se o cliente do emaillot tentar abrir um emaillot local antes que o servidor de emaillot o tenha criado com a função CreateMailSlot .

Para obter mais informações, consulte Emailslots.

Pipes

Se CreateFile abrir a extremidade do cliente de um pipe nomeado, a função usará qualquer instância do pipe nomeado que esteja no estado de escuta. O processo de abertura pode duplicar o identificador quantas vezes forem necessários, mas depois que ele for aberto, a instância de pipe nomeada não poderá ser aberta por outro cliente. O acesso especificado quando um pipe é aberto deve ser compatível com o acesso especificado no parâmetro
dwOpenMode da função CreateNamedPipe.

Se a função CreateNamedPipe não tiver sido chamada com êxito no servidor antes desta operação, um pipe não existirá e CreateFile falhará com ERROR_FILE_NOT_FOUND.

Se houver pelo menos uma instância de pipe ativo, mas não houver pipes de ouvinte disponíveis no servidor, o que significa que todas as instâncias de pipe estão conectadas no momento, CreateFile falha com ERROR_PIPE_BUSY.

Para obter mais informações, consulte Pipes.

Exemplos

As operações de arquivo de exemplo são mostradas nos seguintes tópicos:

A E/S do dispositivo físico é demonstrada nos seguintes tópicos: Um exemplo usando pipes nomeados está localizado em cliente pipe nomeado.

Trabalhar com um emaillot é mostrado em Escrevendo em umde Emaillot.

Um snippet de código de backup em fita pode ser encontrado em Criando um aplicativo de backup.

Nota

O cabeçalho fileapi.h define CreateFile como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino Windows
cabeçalho fileapi.h (inclua Windows.h)
biblioteca Kernel32.lib
de DLL Kernel32.dll

Consulte também

sobre o gerenciamento de diretórios

sobre o gerenciamento de volume

de Backup do

CloseHandle

de Comunicações

CreateDirectory

CreateDirectoryEx

CreateFileTransacted

CreateMailSlot

CreateNamedPipe

criando, excluindo e mantendo arquivos

DeleteFile

controle de entrada e saída do dispositivo (IOCTL)

DeviceIoControl

de compactação e descompactação de arquivos

de Criptografia de Arquivo

Funções de gerenciamento de arquivos

de Direitos de Acesso e Segurança de Arquivos

de Fluxos de Arquivos

Funções

GetLastError

portas de conclusão de E/S

conceitos de E/S

de Emailslots

obtenção e configuração de informações de arquivo

Tópicos de visão geral

Pipes

ReadFile

ReadFileEx

em execução com privilégios especiais

SetFileAttributes

writefile

WriteFileEx