Função NtCreateFile (winternl.h)
Cria um novo arquivo ou diretório ou abre um arquivo, dispositivo, diretório ou volume existente.
Essa função é o equivalente do modo de usuário à função ZwCreateFile documentada no WDK (Windows Driver Kit).
Sintaxe
__kernel_entry NTSTATUS NtCreateFile(
[out] PHANDLE FileHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in, optional] PLARGE_INTEGER AllocationSize,
[in] ULONG FileAttributes,
[in] ULONG ShareAccess,
[in] ULONG CreateDisposition,
[in] ULONG CreateOptions,
[in] PVOID EaBuffer,
[in] ULONG EaLength
);
Parâmetros
[out] FileHandle
Um ponteiro para uma variável que recebe o identificador de arquivo se a chamada for bem-sucedida.
[in] DesiredAccess
O valor ACCESS_MASK que expressa o tipo de acesso que o chamador requer para o arquivo ou diretório. O conjunto de sinalizadores de DesiredAccess
Os chamadores de NtCreateFile podem especificar um ou uma combinação do seguinte, possivelmente usando um OR bit a bit com sinalizadores compatíveis adicionais da lista de sinalizadores de DesiredAccess anterior, para qualquer objeto de arquivo que não represente um arquivo de diretório.
O valor FILE_GENERIC_EXECUTE é irrelevante para drivers intermediários e de dispositivo.
Os XXX
Para abrir ou criar um arquivo de diretório, como também indicado com o parâmetro CreateOptions, os chamadores de NtCreateFile podem especificar um ou uma combinação do seguinte, possivelmente usando um bit-OR com um ou mais sinalizadores compatíveis da lista de sinalizadores DesiredAccess anteriores.
| Valor | Significado |
|---|---|
|
Os arquivos no diretório podem ser listados. |
|
O diretório pode ser percorrido: ou seja, pode fazer parte do nome do caminho de um arquivo. |
[in] ObjectAttributes
Um ponteiro para uma estrutura já inicializada com InitializeObjectAttributes. Os membros dessa estrutura para um objeto de arquivo incluem o seguinte.
| Valor | Significado |
|---|---|
|
Especifica o número de bytes de ObjectAttributes dados fornecidos. Esse valor deve ser pelo menos sizeof(OBJECT_ATTRIBUTES). |
|
Opcionalmente, especifica um identificador para um diretório obtido por uma chamada anterior para NtCreateFile. Se esse valor for NULL, o membro ObjectName deverá ser uma especificação de arquivo totalmente qualificada que inclua o caminho completo para o arquivo de destino. Se esse valor não for |
|
Aponta para uma cadeia de caracteres Unicode em buffer que nomeia o arquivo a ser criado ou aberto. Esse valor deve ser uma especificação de arquivo totalmente qualificada ou o nome de um objeto de dispositivo, a menos que seja o nome de um arquivo relativo ao diretório especificado por rootDirectory. Por exemplo, \Device\Floppy1\myfile.dat ou \?? \B:\myfile.dat pode ser a especificação de arquivo totalmente qualificada, desde que o driver disquete e o sistema de arquivos em excesso já estejam carregados. Para obter mais informações, consulte nomes de arquivo, caminhos e namespaces. |
|
É um conjunto de sinalizadores que controla os atributos de objeto de arquivo. Esse valor pode ser zero ou |
|
Opcionalmente, especifica um descritor de segurança a ser aplicado a um arquivo. As ACLs especificadas por esse descritor de segurança são aplicadas ao arquivo somente quando ele é criado. Se o valor for NULL quando um arquivo for criado, a ACL colocada no arquivo dependerá do sistema de arquivos; a maioria dos sistemas de arquivos propaga alguma parte de tal ACL do arquivo de diretório pai combinado com a ACL padrão do chamador. Os drivers intermediários e de dispositivo podem definir esse membro como NULL. |
|
Especifica os direitos de acesso que um servidor deve receber ao contexto de segurança do cliente. Esse valor não éNULL somente quando uma conexão com um servidor protegido é estabelecida, permitindo que o chamador controle quais partes do contexto de segurança do chamador são disponibilizadas para o servidor e se o servidor tem permissão para representar o chamador. |
[out] IoStatusBlock
Um ponteiro para uma variável que recebe o status de conclusão final e informações sobre a operação solicitada. Ao retornar de
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
O tamanho da alocação inicial em bytes para o arquivo. Um valor diferente de zero não tem efeito, a menos que o arquivo esteja sendo criado, substituído ou substituído.
[in] FileAttributes
Os atributos de arquivo. Atributos explicitamente especificados são aplicados somente quando o arquivo é criado, substituído ou, em alguns casos, substituído. Por padrão, esse valor é um FILE_ATTRIBUTE_NORMAL, que pode ser substituído por uma combinação ORed de um ou mais sinalizadores FILE_ATTRIBUTE_xxxx, que são definidos em Wdm.h e NtDdk.h. Para obter uma lista de sinalizadores que podem ser usados com NtCreateFile, consulte CreateFile.
[in] ShareAccess
O tipo de acesso de compartilhamento que o chamador gostaria de usar no arquivo, como zero, ou como uma ou uma combinação dos valores a seguir.
Para obter mais informações, consulte o SDK do Windows.
[in] CreateDisposition
Especifica o que fazer, dependendo se o arquivo já existe, como um dos valores a seguir.
[in] CreateOptions
As opções a serem aplicadas ao criar ou abrir o arquivo, como uma combinação compatível dos sinalizadores a seguir.
[in] EaBuffer
Ponteiro para um buffer EA usado para passar atributos estendidos.
[in] EaLength
Comprimento do buffer EA.
Valor de retorno
NtCreateFile retorna STATUS_SUCCESS ou um status de erro apropriado. Se ele retornar um status de erro, o chamador poderá encontrar mais informações sobre a causa da falha verificando o IoStatusBlock. Para simplificar essa verificação, um aplicativo pode usar as macros NT_SUCCESS, NT_ERRORe NT_WARNING.
Observações
O identificador, fornecido por NtCreateFile, pode ser usado por chamadas subsequentes para manipular dados dentro do arquivo ou do estado ou atributos do objeto de arquivo.
Há duas maneiras alternativas de especificar o nome do arquivo a ser criado ou aberto com NtCreateFile:
- Como um nome de caminho totalmente qualificado, fornecido no ObjectName membro da entrada ObjectAttributes
- Como um nome de caminho relativo ao arquivo de diretório representado pelo identificador no membro
RootDirectory do de entrada ObjectAttributes
Certas DesiredAccess sinalizadores e combinações de sinalizadores têm os seguintes efeitos:
- Para um chamador sincronizar uma conclusão de E/S aguardando o FileHandle retornado, o sinalizador SYNCHRONIZE deve ser definido.
- Passar um zero para desiredFlags não é válido.
- Se apenas os sinalizadores FILE_APPEND_DATA e SYNCHRONIZE estiverem definidos, o chamador poderá gravar somente no final do arquivo e todas as informações de deslocamento sobre gravações no arquivo serão ignoradas. No entanto, o arquivo é automaticamente estendido conforme necessário para esse tipo de operação de gravação.
- Definir o sinalizador de FILE_WRITE_DATA para um arquivo também permite que as gravações além do final do arquivo ocorram. O arquivo também é estendido automaticamente para esse tipo de gravação.
- Se apenas os sinalizadores
FILE_EXECUTE eSYNCHRONIZE estiverem definidos, o chamador não poderá ler ou gravar diretamente nenhum dado no arquivo usando oFileHandleretornado, ou seja, todas as operações no arquivo ocorrem por meio do pager do sistema em resposta a instruções e acessos a dados.
O parâmetro
Para que um arquivo compartilhado seja aberto com êxito, o parâmetro desiredAccess
O valor CreateDispositionFILE_SUPERSEDE requer que o chamador tenha acesso DELETE a um objeto de arquivo existente. Nesse caso, uma chamada bem-sucedida para NtCreateFile com FILE_SUPERSEDE em um arquivo existente exclui efetivamente esse arquivo e o recria. Isso implica que, se o arquivo já tiver sido aberto por outro thread, ele abriu o arquivo especificando um parâmetro ShareAccess com o conjunto de sinalizadores FILE_SHARE_DELETE.
Observe que esse tipo de disposição é consistente com o estilo POSIX de substituição de arquivos. Os valores CreateDispositionFILE_OVERWRITE_IF e FILE_SUPERSEDE são semelhantes. Se ZwCreateFile for chamado com um arquivo existente e qualquer um desses valores CreateDisposition, o arquivo será substituído.
Substituir um arquivo é semanticamente equivalente a uma operação de substituição, exceto pelo seguinte:
- O chamador deve ter acesso de gravação ao arquivo, em vez de excluir o acesso. Isso implica que, se o arquivo já tiver sido aberto por outro thread, ele abriu o arquivo com o sinalizador de FILE_SHARE_WRITE definido na entrada parâmetro ShareAccess.
- Os atributos de arquivo especificados são logicamente ORed com aqueles que já estão no arquivo. Isso implica que, se o arquivo já tiver sido aberto por outro thread, um chamador subsequente de NtCreateFile não poderá desabilitar sinalizadores de FileAttributes existentes, mas poderá habilitar sinalizadores adicionais para o mesmo arquivo. Observe que esse estilo de substituição de arquivos é consistente com os sistemas operacionais MS-DOS, Windows 3.1 e OS/2.
O valor CreateOptionsFILE_DIRECTORY_FILE especifica que o arquivo a ser criado ou aberto é um arquivo de diretório. Quando um arquivo de diretório é criado, o sistema de arquivos cria uma estrutura apropriada no disco para representar um diretório vazio para a estrutura em disco do sistema de arquivos específico. Se essa opção tiver sido especificada e o arquivo fornecido a ser aberto não for um arquivo de diretório ou se o chamador tiver especificado um valor CreateOptions ou CreateDisposition inconsistente, a chamada para NtCreateFile falhará.
O sinalizador CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING impede que o sistema de arquivos execute qualquer buffer intermediário em nome do chamador. Especificar esse valor coloca certas restrições nos parâmetros do chamador para outras rotinas de de arquivo deXXX
- Qualquer byteOffset opcional passado para a função NtReadFile ou NtWriteFile deve ser parte integrante do tamanho do setor.
- O de comprimento de
passado para NtReadFile ouNtWriteFile , deve ser uma parte integrante do tamanho do setor. Observe que especificar uma operação de leitura para um buffer cujo comprimento é exatamente o tamanho do setor pode resultar em um número menor de bytes significativos sendo transferidos para esse buffer se o final do arquivo foi atingido durante a transferência. - Os buffers devem ser ajustados de acordo com o requisito de alinhamento do dispositivo subjacente. Essas informações podem ser obtidas chamando NtCreateFile para obter um identificador para o objeto de arquivo que representa o dispositivo físico e, em seguida, chamando NtQueryInformationFile com esse identificador. Para obter uma lista do sistema FILE_valores de_ALIGNMENT XXX, consulte a documentação do SDK do Windows.
- As chamadas para
NtSetInformationFile com o parâmetro FileInformationClass definido como FilePositionInformation devem especificar um deslocamento que seja parte integrante do tamanho do setor.
Se o parâmetro CreateOptions especificar o sinalizador FILE_OPEN_REPARSE_POINT e NtCreateFile abrir um arquivo com um ponto de nova análise, o processamento de nova análise normal não ocorrerá e NtCreateFile tentar abrir diretamente o arquivo de ponto de nova análise. Se o sinalizador de FILE_OPEN_REPARSE_POINT não for especificado, o processamento normal do ponto de nova análise ocorrerá para o arquivo. Em ambos os casos, se a operação aberta tiver sido bem-sucedida, NtCreateFile retornará STATUS_SUCCESS; caso contrário, um código de erro. A função NtCreateFile
O sinalizador CreateOptionsFILE_OPEN_REQUIRING_OPLOCK do parâmetro elimina o tempo entre quando você abre o arquivo e solicita um oplock que poderia potencialmente permitir que terceiros abrissem o arquivo, o que causaria uma violação de compartilhamento. Um aplicativo pode usar o sinalizador FILE_OPEN_REQUIRING_OPLOCK com NtCreateFile e solicitar qualquer oplock. Isso garante que um proprietário do oplock seja notificado de qualquer solicitação aberta subsequente que cause uma violação de compartilhamento.
No Windows 7, se houver outros identificadores no arquivo quando um aplicativo usar esse sinalizador, a operação de criação falhará com STATUS_OPLOCK_NOT_GRANTED. Essa restrição não existe mais a partir do Windows 8.
Se essa operação de criação interromper um oplock que já existe no arquivo, a configuração do sinalizador FILE_OPEN_REQUIRING_OPLOCK fará com que a operação de criação falhe com STATUS_CANNOT_BREAK_OPLOCK. O oplock existente não será interrompido por essa operação de criação.
Um aplicativo que usa esse sinalizador deve solicitar um oplock depois que essa chamada for bem-sucedida ou todas as tentativas subsequentes de abrir o arquivo serão bloqueadas sem o benefício do processamento de oplock normal. Da mesma forma, se essa chamada for bem-sucedida, mas a solicitação oplock subsequente falhar, um aplicativo que usa esse sinalizador deverá fechar seu identificador depois de detectar que a solicitação oplock falhou.
O sinalizador FILE_RESERVE_OPFILTER do parâmetro CreateOptions permite que um aplicativo solicite um oplock de Nível 1, Lote ou Filtro para impedir que outros aplicativos sejam atingidos por violações de compartilhamento. No entanto, em termos práticos, o FILE_RESERVE_OPFILTER é útil apenas para oplocks de filtro. Para usá-lo, você deve concluir as seguintes etapas:
- Emita uma solicitação de criação com CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess exatamente FILE_READ_ATTRIBUTESe do ShareAccess exatamente
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE). As possíveis falhas são as seguintes:- Se já houver identificadores abertos, a solicitação de criação falhará com STATUS_OPLOCK_NOT_GRANTEDe o próximo oplock solicitado também falhará.
- Se você abrir com mais acesso do que FILE_READ_ATTRIBUTES ou menos compartilhamento do que
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE), a solicitação falhará com STATUS_OPLOCK_NOT_GRANTED.
- Se a solicitação de criação for bem-sucedida, solicite um oplock.
- Abra outro identificador no arquivo para fazer E/S.
(FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL) e ainda não quebra um oplock de filtro. No entanto, qualquer DesiredAccess maior que (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE) quebrará um oplock de Nível 1 ou lote e tornará o sinalizador FILE_RESERVE_OPFILTER inútil para esses tipos de oplock.
O NTFS é o único sistema de arquivos da Microsoft que implementa FILE_RESERVE_OPFILTER.
Para obter mais informações sobre oplocks, consulte Bloqueios oportunistas.
Observe que o arquivo de cabeçalho do WDK NtDef.h é necessário para muitas definições constantes, bem como o InitializeObjectAttributes macro. Você também pode usar as funções LoadLibrary e GetProcAddress para vincular dinamicamente a NtDll.dll.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino |
Windows |
| cabeçalho | winternl.h |
| biblioteca | ntdll.lib |
| de DLL |
ntdll.dll |