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 DesiredAccess definiti dal sistema determina i diritti di accesso specifici seguenti per gli oggetti file.
Non specificare FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA o FILE_EXECUTE quando si crea o si apre una directory.
I chiamanti di NtCreateFile possono specificare una o una combinazione delle seguenti, usando un OR bit per bit con flag compatibili aggiuntivi dell'elenco dei flag DesiredAccess precedenti, 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 CreateOptions , i chiamanti di NtCreateFile possono specificare una o una combinazione delle seguenti, eventualmente usando un OR bit per bit con uno o più flag compatibili dall'elenco di flag DesiredAccess precedente.
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 dei dati ObjectAttributes forniti. Questo valore deve essere almeno sizeof(OBJECT_ATTRIBUTES). |
|
Facoltativamente, specifica un handle in una directory ottenuta da una chiamata precedente a NtCreateFile. Se questo valore è NULL, il membro ObjectName deve essere una specifica di file completa che include il percorso completo del file di destinazione. Se questo valore è diverso da NULL, il membro ObjectName specifica un nome file relativo a questa directory. |
|
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 file, percorsi e spazi dei nomi. |
|
Set di flag che controlla gli attributi dell'oggetto file. Questo valore può essere zero o OBJ_CASE_INSENSITIVE, che indica che il codice di ricerca del nome deve ignorare la distinzione tra maiuscole e minuscole del membro ObjectName anziché eseguire una ricerca con corrispondenza esatta. Il valore OBJ_INHERIT è irrilevante per i driver di dispositivo e intermedi. |
|
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 parte di tale ACL dal file di directory padre combinato 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 è diverso da 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
Dimensione di allocazione iniziale 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 di condivisione che il chiamante vuole usare nel file, come zero o come una o una combinazione dei valori seguenti.
Per altre informazioni, vedere la Windows SDK.
[in] CreateDisposition
Specifica cosa fare, 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.
Valore | Significato |
---|---|
|
Il file creato o aperto è un file di directory. Con questo flag, il parametro CreateDisposition deve essere impostato su FILE_CREATE, FILE_OPEN o FILE_OPEN_IF. Con questo flag, altri flag CreateOptions compatibili includono solo i flag seguenti: FILE_SYNCHRONOUS_IO_ALERT,FILE_SYNCHRONOUS_IO _NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT e FILE_OPEN_BY_FILE_ID. |
|
Il file aperto non deve essere un file di directory o questa chiamata non riesce. L'oggetto file aperto può rappresentare un file di dati, un dispositivo logico, virtuale o fisico o un volume. |
|
Le applicazioni che scrivono dati nel file devono effettivamente trasferire i dati nel file prima che venga considerata completata qualsiasi operazione di scrittura richiesta. Questo flag viene impostato automaticamente se il flag CreateOptionsFILE_NO_INTERMEDIATE _BUFFERING è impostato. |
|
Tutti gli accessi al file sono sequenziali. |
|
Gli accessi al file possono essere casuali, quindi non è necessario eseguire operazioni di lettura sequenziale sul file da FSD o dal sistema. |
|
Il file non può essere memorizzato nella cache o nel buffer interno di un driver. Questo flag non è compatibile con il flag DesiredAccessFILE_APPEND_DATA . |
|
Tutte le operazioni sul file vengono eseguite in modo sincrono. Qualsiasi attesa per conto del chiamante è soggetta alla terminazione prematura dagli avvisi. Questo flag causa anche il mantenimento del contesto di posizione del file dal sistema di I/O. Se questo flag è impostato, è necessario impostare anche il flag DesiredAccessSYNC . |
|
Tutte le operazioni sul file vengono eseguite in modo sincrono. Le attese nel sistema per sincronizzare l'accodamento di I/O e il completamento non sono soggetti agli avvisi. Questo flag causa anche il mantenimento del contesto di posizione del file dal sistema di I/O. Se questo flag è impostato, è necessario impostare anche il flag DesiredAccessSYNC . |
|
Creare una connessione ad albero per questo file per aprirla tramite la rete. Questo flag non viene usato dai driver di dispositivo e intermedi. |
|
Se gli attributi estesi in un file esistente che viene aperto indicano che il chiamante deve comprendere EAs per interpretare correttamente il file, non riuscire a eseguire questa richiesta perché il chiamante non capisce come gestire EAs. Questo flag è irrilevante per i driver intermedi e del dispositivo. |
|
Aprire un file con un punto di correzione e ignorare l'elaborazione normale del punto di ripristino per il file. Per altre informazioni, vedere la sezione Osservazioni. |
|
Eliminare il file quando l'ultimo handle viene passato a NtClose. Se questo flag è impostato, il flag DELETE deve essere impostato nel parametro DesiredAccess . |
|
Il nome del file specificato dal parametro ObjectAttributes include il numero di riferimento del file a 8 byte per il file. Questo numero viene assegnato da e specifico per il file system specifico. Se il file è un punto reparse, il nome del file includerà anche il nome di un dispositivo. Si noti che il file system FAT non supporta questo flag. Questo flag non viene usato dai driver di dispositivo e intermedi. |
|
Il file viene aperto per la finalità di backup. Pertanto, il sistema deve controllare determinati diritti di accesso e concedere al chiamante l'accesso appropriato al file prima di controllare il parametro DesiredAccess sul descrittore di sicurezza del file. Questo flag non viene usato dai driver intermedi e del dispositivo. |
|
Questo flag consente a un'applicazione di richiedere un blocco opportunistico di filtro (oplock) per impedire ad altre applicazioni di ottenere violazioni di condivisione. Se sono già disponibili handle aperti, la richiesta di creazione avrà esito negativo con STATUS_OPLOCK_NOT_GRANTED. Per altre informazioni, vedere la sezione Osservazioni. |
|
Il file viene aperto e viene richiesto un blocco opportunistico (oplock) nel file come singola operazione atomica. Il file system controlla gli oplock prima di eseguire l'operazione di creazione e avrà esito negativo con un codice restituito di STATUS_CANNOT_BREAK_OPLOCK se il risultato sarebbe interrompere un oplock esistente. Per altre informazioni, vedere la sezione Osservazioni. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo flag non è supportato.
Questo flag è supportato nei file system seguenti: NTFS, FAT e exFAT. |
|
Completare immediatamente questa operazione con un codice di esito positivo alternativo di STATUS_OPLOCK_BREAK_IN_PROGRESS se il file di destinazione viene oplockato, anziché bloccare il thread del chiamante. Se il file è oplocked, un altro chiamante ha già accesso al file. Questo flag non viene usato dai driver di dispositivo e intermedi. |
[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 IoStatusBlock. Per semplificare questo controllo, un'applicazione può usare le macro NT_SUCCESS, NT_ERROR e NT_WARNING.
Commenti
L'handle, specificato 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:
- Nome percorso completo fornito nel membro ObjectName dell'oggetto ObjectAttributes
- Nome percorso relativo al file di directory rappresentato dall'handle nel membro RootDirectorydell'oggetto ObjectAttributes di input
- Per consentire a un chiamante di sincronizzare un completamento di I/O in attesa del fileHandle restituito, è necessario impostare il flag SYNC .
- Il passaggio di zero a DesiredFlags non è valido.
- Se vengono impostati solo i flag FILE_APPEND_DATA e SYNC , il chiamante può scrivere solo alla fine del file e tutte le informazioni di 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 di 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 SYNC , il chiamante non può leggere o scrivere direttamente dati nel file usando fileHandle restituito, ovvero tutte le operazioni sul file si verificano tramite il pager del sistema in risposta alle istruzioni e agli accessi ai dati.
Per aprire correttamente un file condiviso, il parametro DesiredAccess richiesto per il file deve essere compatibile con le specifiche DesiredAccess e ShareAccess di tutte le apertura precedenti non ancora rilasciate con NtClose. Vale a dire, il parametro DesiredAccess specificato in NtCreateFile per un determinato file non deve essere in conflitto con gli accessi che altri opener del file non sono consentiti.
Il valore CreateDispositionFILE_SUPERSEDE richiede che il chiamante disponga dell'accesso DELETE a un oggetto file esistente. In tal caso, una chiamata riuscita a NtCreateFile con FILE_SUPERSEDE in un file esistente elimina in modo efficace tale file e quindi la crea nuovamente. Ciò implica che, se il file è già stato aperto da un altro thread, ha aperto il file specificando un parametro ShareAccess con il set di flag FILE_SHARE_DELETE . Si noti che questo tipo di eliminazione è coerente con lo stile POSIX dei file sovrascrivere. 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 del seguente:
- 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 FILE_SHARE_WRITE impostato nel parametro ShareAccess di input.
- 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 sovrascrivere i file è coerente con MS-DOS, Windows 3.1 e sistemi operativi OS/2.
Il flag CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING impedisce al file system di eseguire qualsiasi buffer intermedio per conto del chiamante. Se si specifica questo valore, vengono applicate determinate restrizioni ai parametri del chiamante ad altre routine di fileNT XXX, tra cui quanto segue:
- Qualsiasi byteOffset facoltativo passato alla funzione NtReadFile o NtWriteFile deve essere un integrale delle dimensioni del settore.
- La lunghezza passata a NtReadFile o NtWriteFile deve essere un integrale delle dimensioni del settore. Si noti che specificando un'operazione di lettura in un buffer la cui lunghezza è esattamente la dimensione del settore potrebbe causare un numero minore di byte significativi trasferiti 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 FILE_XXXdel sistema_ALIGNMENT, vedere la documentazione Windows SDK.
- Le chiamate a NtSetInformationFile con il parametro FileInformationClass impostata su FilePositionInformation devono specificare un offset integrale delle dimensioni del settore.
Se il parametro CreateOptions specifica il flag FILE_OPEN_REPARSE_POINT e NtCreateFile apre un file con un punto reparse, l'elaborazione di reparse normale non si verifica e NtCreateFile tenta di aprire direttamente il file del punto di ripristino. Se il flag di FILE_OPEN_REPARSE_POINT non è specificato, viene eseguita la normale elaborazione del punto di ripristino per il file. In entrambi i casi, se l'operazione aperta ha avuto esito positivo, NtCreateFile restituisce STATUS_SUCCESS; in caso contrario, un codice di errore. La funzione NtCreateFile non restituisce mai STATUS_REPARSE.
Il flag di FILE_OPEN_REQUIRING_OPLOCK del parametro CreateOptions elimina il tempo compreso tra l'apertura del file e la richiesta di un oplock che potrebbe consentire a una terza parte di aprire il file, che causerebbe una violazione della condivisione. Un'applicazione può usare il flag di FILE_OPEN_REQUIRING_OPLOCK con NtCreateFile e quindi richiedere qualsiasi oplock. Ciò garantisce che un proprietario di oplock riceverà una notifica di qualsiasi richiesta aperta successiva che causa una violazione della condivisione.
In Windows 7, se esistono altri handle nel file 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à presente nel file, l'impostazione del flag di 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 che questa chiamata ha esito positivo o tutti i tentativi successivi di aprire il file verranno bloccati senza il vantaggio dell'elaborazione normale del blocco. Analogamente, se questa chiamata ha esito positivo, ma la richiesta di 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 di FILE_RESERVE_OPFILTER del parametro CreateOptions consente a un'applicazione di richiedere un oplock di livello 1, Batch o Filtro per impedire che altre applicazioni ottengano violazioni di condivisione. Tuttavia, in termini pratici, l'FILE_RESERVE_OPFILTER è utile solo per gli oplock di filtro. Per usarlo, è necessario completare la procedura seguente:
- Eseguire una richiesta di creazione con CreateOptions di FILE_RESERVE_OPFILTER, DesiredAccess di esattamente FILE_READ_ATTRIBUTES e 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_GRANTED e il successivo oplock richiesto ha esito negativo.
- Se si apre con più accesso rispetto a FILE_READ_ATTRIBUTES o minore 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 blocco di filtri. Tuttavia, qualsiasi oggetto DesiredAccess maggiore di (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE)
quello che interromperà un blocco di livello 1 o Batch e rende il flag FILE_RESERVE_OPFILTER inutile per tali tipi di oplock.
NTFS è l'unico file system Microsoft che implementa FILE_RESERVE_OPFILTER.
Per altre informazioni sui oplock, vedere Oplock Semantics.
Si noti che il file di intestazione WDK NtDef.h è necessario per molte definizioni costanti e la macro InitializeObjectAttributes . È anche possibile usare le funzioni LoadLibrary e GetProcAddress per collegare dinamicamente a NtDll.dll.
Requisiti
Requisito | Valore |
---|---|
Piattaforma di destinazione | Windows |
Intestazione | winternl.h |
Libreria | ntdll.lib |
DLL | ntdll.dll |
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per