Funzione NtCreateFile (winternl.h)
Crea un nuovo file o una nuova directory oppure apre un file, un dispositivo, una directory o un volume esistente.
Questa funzione è la modalità utente equivalente alla funzione ZwCreateFile documentata in Windows Driver Kit (WDK).
Sintassi
__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
);
Parametri
[out] FileHandle
Puntatore a una variabile che riceve l'handle di file se la chiamata ha esito positivo.
[in] DesiredAccess
Valore ACCESS_MASK che esprime il tipo di accesso richiesto dal chiamante al file o alla directory. Il set di flag di DesiredAccess definiti dal sistema determina i diritti di accesso specifici seguenti per gli oggetti file.
I chiamanti di NtCreateFile possono specificare una o una combinazione delle opzioni seguenti, eventualmente usando un or bit per bit con flag compatibili aggiuntivi del elenco di flag DesiredAccess, per qualsiasi oggetto file che non rappresenta un file di directory.
Il valore FILE_GENERIC_EXECUTE è irrilevante per i driver intermedi e del dispositivo.
Il STANDARD_RIGHTS_XXX sono valori di sistema predefiniti usati per applicare la sicurezza agli oggetti di sistema.
Per aprire o creare un file di directory, come indicato anche con il parametro
| Valore | Significato |
|---|---|
|
I file nella directory possono essere elencati. |
|
La directory può essere attraversata, ovvero può far parte del percorso di un file. |
[in] ObjectAttributes
Puntatore a una struttura già inizializzata con InitializeObjectAttributes. I membri di questa struttura per un oggetto file includono quanto segue.
| Valore | Significato |
|---|---|
|
Specifica il numero di byte di ObjectAttributes dati forniti. Questo valore deve essere almeno sizeof(OBJECT_ATTRIBUTES). |
|
Facoltativamente, specifica un handle per una directory ottenuta da una chiamata precedente a NtCreateFile. Se questo valore è |
|
Punta a una stringa Unicode memorizzata nel buffer che assegna un nome al file da creare o aprire. Questo valore deve essere una specifica di file completa o il nome di un oggetto dispositivo, a meno che non sia il nome di un file relativo alla directory specificata da RootDirectory. Ad esempio, \Device\Floppy1\myfile.dat o \?? \B:\myfile.dat potrebbe essere la specifica completa del file, purché il driver floppy e il file system overlying siano già caricati. Per altre informazioni, vedere nomi, percorsi e spazi dei nomi. |
|
Set di flag che controllano gli attributi dell'oggetto file. Questo valore può essere zero o OBJ_CASE_INSENSITIVE, che indica che il codice name-lookup deve ignorare il caso del ObjectName membro invece di eseguire una ricerca di corrispondenza esatta. Il valore OBJ_INHERIT è irrilevante per i driver intermedi e del dispositivo. |
|
Facoltativamente, specifica un descrittore di sicurezza da applicare a un file. Gli ACL specificati da un descrittore di sicurezza di questo tipo vengono applicati al file solo quando viene creato. Se il valore è NULL quando viene creato un file, l'ACL inserito nel file dipende dal file system; la maggior parte dei file system propaga una parte di tale ACL dal file di directory padre combinata con l'ACL predefinito del chiamante. I driver di dispositivo e intermedi possono impostare questo membro su NULL. |
|
Specifica i diritti di accesso che un server deve essere assegnato al contesto di sicurezza del client. Questo valore non èNULL solo quando viene stabilita una connessione a un server protetto, consentendo al chiamante di controllare quali parti del contesto di sicurezza del chiamante vengono rese disponibili al server e se il server è autorizzato a rappresentare il chiamante. |
[out] IoStatusBlock
Puntatore a una variabile che riceve lo stato di completamento finale e informazioni sull'operazione richiesta. In caso di restituzione da NtCreateFile, il membro Information contiene uno dei valori seguenti:
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
Dimensioni di allocazione iniziali in byte per il file. Un valore diverso da zero non ha alcun effetto a meno che il file non venga creato, sovrascritto o sostituito.
[in] FileAttributes
Attributi del file. Gli attributi specificati in modo esplicito vengono applicati solo quando il file viene creato, sostituito o, in alcuni casi, sovrascritto. Per impostazione predefinita, questo valore è un FILE_ATTRIBUTE_NORMAL, che può essere sottoposto a override da una combinazione ORed di uno o più flag FILE_ATTRIBUTE_xxxx, definiti in Wdm.h e NtDdk.h. Per un elenco di flag che possono essere usati con NtCreateFile, vedere CreateFile.
[in] ShareAccess
Tipo di accesso condiviso che il chiamante desidera utilizzare nel file, come zero o come una o una combinazione dei valori seguenti.
Per altre informazioni, vedere Windows SDK.
[in] CreateDisposition
Specifica le operazioni da eseguire, a seconda che il file esista già, come uno dei valori seguenti.
[in] CreateOptions
Le opzioni da applicare durante la creazione o l'apertura del file, come combinazione compatibile dei flag seguenti.
[in] EaBuffer
Puntatore a un buffer EA usato per passare attributi estesi.
[in] EaLength
Lunghezza del buffer EA.
Valore restituito
NtCreateFile restituisce STATUS_SUCCESS o uno stato di errore appropriato. Se restituisce uno stato di errore, il chiamante può trovare altre informazioni sulla causa dell'errore controllando il IoStatusBlock. Per semplificare questa verifica, un'applicazione può usare le macro NT_SUCCESS, NT_ERRORe NT_WARNING.
Osservazioni
L'handle, fornito da NtCreateFile, può essere usato dalle chiamate successive per modificare i dati all'interno del file o lo stato o gli attributi dell'oggetto file.
Esistono due modi alternativi per specificare il nome del file da creare o aprire con NtCreateFile:
- Come nome percorso completo, fornito nel membro ObjectName
dell'input ObjectAttributes - Come percorso relativo al file di directory rappresentato dall'handle nel rootDirectory membro dell'input ObjectAttributes
Alcuni flag DesiredAccess e combinazioni di flag hanno gli effetti seguenti:
- Affinché un chiamante sincronizzi un completamento di I/O in attesa del
fileHandle restituito , è necessario impostare il flag SYNCHRONIZE. - Il passaggio di zero a desiredFlags non è valido.
- Se vengono impostati solo i flag FILE_APPEND_DATA e SYNCHRONIZE, il chiamante può scrivere solo alla fine del file e tutte le informazioni sull'offset sulle scritture nel file vengono ignorate. Tuttavia, il file viene esteso automaticamente in base alle esigenze per questo tipo di operazione di scrittura.
- L'impostazione del flag FILE_WRITE_DATA per un file consente anche di scrivere oltre la fine del file. Il file viene esteso automaticamente anche per questo tipo di scrittura.
- Se vengono impostati solo i flag FILE_EXECUTE e SYNCHRONIZE, il chiamante non può leggere o scrivere direttamente dati nel file usando l'FileHandle restituito, ovvero tutte le operazioni sul file vengono eseguite tramite il cercapersone di sistema in risposta a istruzioni e accessi ai dati.
Il parametro
Affinché un file condiviso venga aperto correttamente, il parametro DesiredAccess richiesto al file deve essere compatibile sia con DesiredAccess che con ShareAccess specifiche di tutte le aperte precedenti che non sono ancora state rilasciate con NtClose. Ovvero, il parametro
Il valore CreateDispositionFILE_SUPERSEDE richiede che il chiamante abbia DELETE l'accesso a un oggetto file esistente. In tal caso, una chiamata riuscita a NtCreateFile con FILE_SUPERSEDE in un file esistente elimina effettivamente tale file e quindi la ricrea. Ciò implica che, se il file è già stato aperto da un altro thread, il file è stato aperto specificando un parametro ShareAccess con il flag FILE_SHARE_DELETE impostato.
Si noti che questo tipo di eliminazione è coerente con lo stile POSIX di sovrascrivere i file. I valori CreateDispositionFILE_OVERWRITE_IF e FILE_SUPERSEDE sono simili. Se ZwCreateFile viene chiamato con un file esistente e uno di questi valori CreateDisposition, il file viene sostituito.
La sovrascrittura di un file è semanticamente equivalente a un'operazione di sostituzione, ad eccezione dei seguenti:
- Il chiamante deve avere accesso in scrittura al file, anziché eliminare l'accesso. Ciò implica che, se il file è già stato aperto da un altro thread, ha aperto il file con il flag di FILE_SHARE_WRITE impostato nel parametro di input ShareAccess.
- Gli attributi di file specificati sono logicamente ORed con quelli già presenti nel file. Ciò implica che, se il file è già stato aperto da un altro thread, un chiamante successivo di NtCreateFile non può disabilitare i flag FileAttributes esistenti ma può abilitare flag aggiuntivi per lo stesso file. Si noti che questo stile di sovrascrittura dei file è coerente con i sistemi operativi MS-DOS, Windows 3.1 e OS/2.
Il valore CreateOptionsFILE_DIRECTORY_FILE specifica che il file da creare o aprire è un file di directory. Quando viene creato un file di directory, il file system crea una struttura appropriata sul disco per rappresentare una directory vuota per la struttura su disco di quel particolare file system. Se questa opzione è stata specificata e il file specificato da aprire non è un file di directory o se il chiamante ha specificato un incoerente CreateOptions o valore createDisposition, la chiamata a NtCreateFile ha esito negativo.
Il flag CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING impedisce al file system di eseguire qualsiasi buffering intermedio per conto del chiamante. Se si specifica questo valore, alcune restrizioni sui parametri del chiamante vengono applicate ad altre routine NtXXXFile, incluse le seguenti:
- Qualsiasi
ByteOffset facoltativo passato al NtReadFileo funzione NtWriteFile deve essere un integrale delle dimensioni del settore. - La lunghezza
passata a NtReadFile oNtWriteFile , deve essere un integrale delle dimensioni del settore. Si noti che la specifica di un'operazione di lettura in un buffer la cui lunghezza è esattamente la dimensione del settore può comportare il trasferimento di un numero minore di byte significativi a tale buffer se la fine del file è stata raggiunta durante il trasferimento. - I buffer devono essere modificati in base al requisito di allineamento del dispositivo sottostante. Queste informazioni possono essere ottenute chiamando NtCreateFile per ottenere un handle per l'oggetto file che rappresenta il dispositivo fisico e quindi chiamando NtQueryInformationFile con tale handle. Per un elenco dei valori di FILE_XXX_ALIGNMENT di sistema, vedere la documentazione di Windows SDK.
- Le chiamate a NtSetInformationFile con il parametro FileInformationClass impostato su FilePositionInformation devono specificare un offset integrale delle dimensioni del settore.
Se il parametro
Il flag di
In Windows 7, se nel file esistono altri handle quando un'applicazione usa questo flag, l'operazione di creazione avrà esito negativo con STATUS_OPLOCK_NOT_GRANTED. Questa restrizione non esiste più a partire da Windows 8.
Se questa operazione di creazione interrompe un oplock già esistente nel file, l'impostazione del flag FILE_OPEN_REQUIRING_OPLOCK causerà l'esito negativo dell'operazione di creazione con STATUS_CANNOT_BREAK_OPLOCK. L'oplock esistente non verrà interrotto da questa operazione di creazione.
Un'applicazione che usa questo flag deve richiedere un oplock dopo l'esito positivo della chiamata oppure tutti i tentativi successivi di aprire il file verranno bloccati senza il vantaggio della normale elaborazione di oplock. Analogamente, se questa chiamata ha esito positivo ma la richiesta oplock successiva ha esito negativo, un'applicazione che usa questo flag deve chiudere il relativo handle dopo aver rilevato che la richiesta di oplock non è riuscita.
Il flag FILE_RESERVE_OPFILTERCreateOptions consente a un'applicazione di richiedere un oplock di livello 1, batch o filtro per impedire ad altre applicazioni di ricevere violazioni di condivisione. Tuttavia, in termini pratici, il FILE_RESERVE_OPFILTER è utile solo per gli oplock di filtro. Per usarlo, è necessario completare i passaggi seguenti:
- Eseguire una richiesta di creazione con CreateOptions di FILE_RESERVE_OPFILTER, DesiredAccess di esattamente FILE_READ_ATTRIBUTESe ShareAccess di esattamente
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE). I possibili errori sono i seguenti:- Se sono già presenti handle aperti, la richiesta di creazione ha esito negativo con STATUS_OPLOCK_NOT_GRANTEDe anche il successivo oplock richiesto ha esito negativo.
- Se si apre con più accesso rispetto a FILE_READ_ATTRIBUTES o meno condivisione di
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE), la richiesta ha esito negativo con STATUS_OPLOCK_NOT_GRANTED.
- Se la richiesta di creazione ha esito positivo, richiedere un oplock.
- Aprire un altro handle per il file per eseguire operazioni di I/O.
(FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL) e non interrompe ancora un oplock di filtro. Tuttavia, qualsiasi DesiredAccess maggiore di (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE) interrompe un oplock di livello 1 o Batch e rende il flag di FILE_RESERVE_OPFILTER inutilizzabile per questi tipi di oplock.
NTFS è l'unico file system Microsoft che implementa FILE_RESERVE_OPFILTER.
Per altre informazioni sugli oplock, vedere Blocchi opportunistici.
Si noti che il file di intestazione WDK NtDef.h è necessario per molte definizioni costanti, nonché per la macro InitializeObjectAttributes. È anche possibile usare le funzioni di LoadLibrary
Fabbisogno
| Requisito | Valore |
|---|---|
| piattaforma di destinazione | Finestre |
| intestazione |
winternl.h |
| libreria |
ntdll.lib |
| dll | ntdll.dll |