Funzione CreateFileA (fileapi.h)
Crea o apre un file o un dispositivo di I/O. I dispositivi I/O usati più comunemente sono i seguenti: file, flusso di file, directory, disco fisico, volume, buffer della console, unità nastro, risorsa di comunicazione, mailslot e pipe. La funzione restituisce un handle che può essere usato per accedere al file o al dispositivo per vari tipi di I/O a seconda del file o del dispositivo e dei flag e degli attributi specificati.
Per eseguire questa operazione come operazione transazionata, che comporta un handle che può essere usato per le operazioni di I/O transazionate, usare la funzione CreateFileTransacted .
Sintassi
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
);
Parametri
[in] lpFileName
Nome del file o del dispositivo da creare o aprire. È possibile usare barre in avanti (/) o barre rovesciata (\) in questo nome.
Per impostazione predefinita, il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, prependo "\\?\" al percorso. Per altre informazioni, vedere Denominazione di file, percorsi e spazi dei nomi.
Suggerimento
A partire da Windows 10, versione 1607, è possibile scegliere di rimuovere la limitazione MAX_PATH senza pre sospeso "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima lunghezza percorso" di nomi, nomi, percorsi e spazi dei nomi .
Per informazioni sui nomi di dispositivi speciali, vedere Definizione di un nome dispositivo MS-DOS.
Per creare un flusso di file, specificare il nome del file, un punto e quindi il nome del flusso. Per altre informazioni, vedere Flussi di file.
[in] dwDesiredAccess
Accesso richiesto al file o al dispositivo, che può essere riepilogato come lettura, scrittura, entrambi o 0 per indicare nessuno dei due.
I valori usati più comunemente sono GENERIC_READ, GENERIC_WRITE o entrambi (GENERIC_READ | GENERIC_WRITE). Per altre informazioni, vedere Diritti di accesso generico, sicurezza file e diritti di accesso, costanti di diritti di accesso ai file e ACCESS_MASK.
Se questo parametro è zero, l'applicazione può eseguire query su determinati metadati, ad esempio file, directory o attributi del dispositivo senza accedere a tale file o dispositivo, anche se GENERIC_READ accesso sarebbe stato negato.
Non è possibile richiedere una modalità di accesso in conflitto con la modalità di condivisione specificata dal parametro dwShareMode in una richiesta aperta che dispone già di un handle aperto.
Per altre informazioni, vedere la sezione Osservazioni di questo argomento e Creazione e apertura di file.
[in] dwShareMode
La modalità di condivisione richiesta del file o del dispositivo, che può essere letto, scritto, sia eliminato, tutto questo o nessuno (fare riferimento alla tabella seguente). Le richieste di accesso agli attributi o agli attributi estesi non sono interessate da questo flag.
Se questo parametro è zero e CreateFile ha esito positivo, il file o il dispositivo non può essere condiviso e non può essere nuovamente aperto fino a quando l'handle al file o al dispositivo non viene chiuso. Per altre informazioni, vedere la sezione Osservazioni.
Non è possibile richiedere una modalità di condivisione in conflitto con la modalità di accesso specificata in una richiesta esistente con un handle aperto. CreateFile ha esito negativo e la funzione GetLastError restituirà ERROR_SHARING_VIOLATION.
Per abilitare un processo per condividere un file o un dispositivo mentre un altro processo ha il file o il dispositivo aperto, usare una combinazione compatibile di uno o più dei valori seguenti. Per altre informazioni sulle combinazioni valide di questo parametro con il parametro dwDesiredAccess , vedere Creazione e apertura di file.
[in, optional] lpSecurityAttributes
Puntatore a una struttura SECURITY_ATTRIBUTES che contiene due membri dati separati ma correlati: un descrittore di sicurezza facoltativo e un valore booleano che determina se l'handle restituito può essere ereditato dai processi figlio.
Questo parametro può essere NULL.
Se questo parametro è NULL, l'handle restituito da CreateFile non può essere ereditato da tutti i processi figlio che l'applicazione può creare e il file o il dispositivo associato all'handle restituito ottiene un descrittore di sicurezza predefinito.
Il membro lpSecurityDescriptor della struttura specifica un SECURITY_DESCRIPTOR per un file o un dispositivo. Se questo membro è NULL, il file o il dispositivo associato all'handle restituito viene assegnato un descrittore di sicurezza predefinito.
CreateFile ignora il membro lpSecurityDescriptor quando si apre un file o un dispositivo esistente, ma continua a usare il membro bInheritHandle .
Il membro bInheritHandle della struttura specifica se l'handle restituito può essere ereditato.
Per altre informazioni, vedere la sezione Osservazioni.
[in] dwCreationDisposition
Un'azione da eseguire su un file o un dispositivo esistente o non esiste.
Per i dispositivi diversi dai file, questo parametro è in genere impostato su OPEN_EXISTING.
Per altre informazioni, vedere la sezione Osservazioni.
Questo parametro deve essere uno dei valori seguenti, che non possono essere combinati:
[in] dwFlagsAndAttributes
Gli attributi e i flag del file o del dispositivo FILE_ATTRIBUTE_NORMAL il valore predefinito più comune per i file.
Questo parametro può includere qualsiasi combinazione degli attributi di file disponibili (FILE_ATTRIBUTE_*). Tutti gli altri attributi di file sostituiscono FILE_ATTRIBUTE_NORMAL.
Questo parametro può anche contenere combinazioni di flag (FILE_FLAG_*) per il controllo del comportamento di memorizzazione nella cache dei file o del dispositivo, delle modalità di accesso e di altri flag a scopo speciale. Questi valori si combinano con qualsiasi FILE_ATTRIBUTE_* valori.
Questo parametro può anche contenere informazioni sqOS (Security Quality of Service) specificando il flag di SECURITY_SQOS_PRESENT . Le informazioni sui flag correlati a SQOS aggiuntive vengono presentate nella tabella che segue gli attributi e le tabelle dei flag.
Per un accesso più avanzato agli attributi di file, vedere SetFileAttributes. Per un elenco completo di tutti gli attributi di file con i relativi valori e descrizioni, vedere Costanti attributo file.
| Attributo | Significato |
|---|---|
|
Il file deve essere archiviato. Le applicazioni usano questo attributo per contrassegnare i file per il backup o la rimozione. |
|
Il file o la directory è crittografato. Per un file, questo significa che tutti i dati del file sono crittografati. Per una directory, ciò significa che la crittografia è l'impostazione predefinita per i file appena creati e le sottodirectory. Per altre informazioni, vedere Crittografia file.
Questo flag non ha alcun effetto se è specificato anche FILE_ATTRIBUTE_SYSTEM . Questo flag non è supportato nelle edizioni Home, Home Premium, Starter o ARM di Windows. |
|
Il file è nascosto. Non includerlo in un elenco di directory normale. |
|
Il file non ha altri attributi impostati. Questo attributo è valido solo se usato da solo. |
|
I dati di un file non sono immediatamente disponibili. Questo attributo indica che i dati dei file vengono spostati fisicamente nell'archiviazione offline. Questo attributo viene usato da Archiviazione remota, il software di gestione dell'archiviazione gerarchica. Le applicazioni non devono modificare arbitrariamente questo attributo. |
|
Il file è di sola lettura. Le applicazioni possono leggere il file, ma non possono scrivere o eliminarle. |
|
Il file fa parte o viene usato esclusivamente da un sistema operativo. |
|
Il file viene usato per l'archiviazione temporanea.
Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento. |
| Contrassegno | Significato |
|---|---|
|
Il file viene aperto o creato per un'operazione di backup o ripristino. Il sistema garantisce che il processo chiamante esegue l'override della sicurezza dei file quando il processo ha SE_BACKUP_NAME e SE_RESTORE_NAME privilegi. Per altre informazioni, vedere Modifica dei privilegi in un token.
È necessario impostare questo flag per ottenere un handle in una directory. Un handle di directory può essere passato a alcune funzioni anziché a un handle di file. Per altre informazioni, vedere la sezione Osservazioni. |
|
Il file deve essere eliminato immediatamente dopo la chiusura di tutti i relativi handle, inclusi l'handle specificato ed eventuali altri handle aperti o duplicati.
Se sono presenti handle aperti esistenti in un file, la chiamata non riesce a meno che non siano state aperte tutte con la modalità di condivisione FILE_SHARE_DELETE . Le successive richieste aperte per il file hanno esito negativo a meno che non venga specificata la modalità di condivisione FILE_SHARE_DELETE. |
|
Il file o il dispositivo viene aperto senza memorizzazione nella cache del sistema per le letture e le scritture dei dati. Questo flag non influisce sulla memorizzazione nella cache del disco rigido o sui file mappati alla memoria.
Esistono requisiti rigorosi per l'uso corretto dei file aperti con CreateFile usando il flag FILE_FLAG_NO_BUFFERING , per informazioni dettagliate, vedere Buffering file. |
|
I dati del file vengono richiesti, ma devono continuare a trovarsi nell'archiviazione remota. Non deve essere trasportato nuovamente all'archiviazione locale. Questo flag è usato dai sistemi di archiviazione remoti. |
|
L'elaborazione normale del punto di ripristino non si verificherà; CreateFile tenterà di aprire il punto di ripristino. Quando viene aperto un file, viene restituito un handle di file, indipendentemente dal fatto che il filtro che controlla il punto di ripristino sia operativo.
Questo flag non può essere usato con il flag di CREATE_ALWAYS . Se il file non è un punto di correzione, questo flag viene ignorato. Per altre informazioni, vedere la sezione Osservazioni. |
|
Il file o il dispositivo vengono aperti o creati per I/O asincroni.
Quando le operazioni di I/O successive vengono completate su questo handle, l'evento specificato nella struttura OVERLAPPED verrà impostato sullo stato segnalato. Se questo flag è specificato, il file può essere usato per operazioni di lettura e scrittura simultanee. Se questo flag non è specificato, le operazioni di I/O vengono serializzate, anche se le chiamate alle funzioni di lettura e scrittura specificano una struttura OVERLAPPED . Per informazioni sulle considerazioni sull'uso di un handle di file creato con questo flag, vedere la sezione Handle di I/O sincroni e asincroni di questo argomento. |
|
L'accesso verrà eseguito in base alle regole POSIX. Ciò include l'autorizzazione di più file con nomi, diversi solo nel caso, per i file system che supportano tale denominazione. Usare attenzione quando si usa questa opzione, poiché i file creati con questo flag potrebbero non essere accessibili dalle applicazioni scritte per MS-DOS o Windows a 16 bit. |
|
L'accesso deve essere casuale. Il sistema può interpretare questa situazione come hint per l'ottimizzazione della memorizzazione del file nella cache.
Questo flag non ha alcun effetto se il file system non supporta l'I/O memorizzato nella cache e FILE_FLAG_NO_BUFFERING. Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento. |
|
Il file o il dispositivo viene aperto con consapevolezza della sessione. Se questo flag non viene specificato, non è possibile aprire i dispositivi per sessione, ad esempio un dispositivo che usa il reindirizzamento USB RemoteFX, tramite processi in esecuzione nella sessione 0.
Questo flag non ha alcun effetto per i chiamanti non nella sessione 0. Questo flag è supportato solo nelle edizioni server di Windows.
Windows Server 2008 R2 e Windows Server 2008: Questo flag non è supportato prima dell'Windows Server 2012. |
|
L'accesso deve essere sequenziale dall'inizio alla fine. Il sistema può interpretare questa situazione come hint per l'ottimizzazione della memorizzazione del file nella cache.
Questo flag non deve essere usato se verrà usato read-behind (ovvero analisi inversa). Questo flag non ha effetto se il file system non supporta le operazioni di I/O memorizzate nella cache e FILE_FLAG_NO_BUFFERING. Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento. |
|
Le operazioni di scrittura non passeranno attraverso alcuna cache intermedia, che passeranno direttamente al disco.
Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento. |
Il parametro dwFlagsAndAttributes può anche specificare informazioni SQOS. Per altre informazioni, vedere Livelli di rappresentazione. Quando l'applicazione chiamante specifica il flag SECURITY_SQOS_PRESENT come parte di dwFlagsAndAttributes, può contenere anche uno o più dei valori seguenti.
[in, optional] hTemplateFile
Handle valido per un file modello con il diritto di accesso GENERIC_READ . Il file modello fornisce attributi di file e attributi estesi per il file in fase di creazione.
Questo parametro può essere NULL.
Quando si apre un file esistente, CreateFile ignora questo parametro.
Quando si apre un nuovo file crittografato, il file eredita l'elenco di controllo di accesso discrezionale dalla directory padre. Per altre informazioni, vedere Crittografia file.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle aperto per il file, il dispositivo, la named pipe o lo slot di posta elettronica specificato.
Se la funzione ha esito negativo, il valore restituito viene INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
CreateFile è stato originariamente sviluppato specificamente per l'interazione con i file, ma è stato ampliato e migliorato per includere la maggior parte degli altri tipi di dispositivi E/O e meccanismi disponibili per gli sviluppatori Windows. Questa sezione tenta di coprire i vari problemi che gli sviluppatori possono riscontrare quando si usa CreateFile in contesti diversi e con tipi di I/O diversi. Il testo tenta di utilizzare il file di parola solo quando si fa riferimento specificamente ai dati archiviati in un file system effettivo in un file system. Tuttavia, alcuni usi del file possono fare riferimento in genere a un oggetto I/O che supporta meccanismi simili a file. Questo uso liberale del termine file è particolarmente diffuso nei nomi costanti e nei nomi dei parametri a causa dei motivi cronologici menzionati in precedenza.
Al termine dell'utilizzo dell'handle dell'oggetto restituito da CreateFile, usare la funzione CloseHandle per chiudere l'handle. Ciò non solo libera le risorse di sistema, ma può avere un'influenza più ampia su elementi come la condivisione del file o del dispositivo e il commit dei dati su disco. Le specifiche sono indicate all'interno di questo argomento in base alle esigenze.
Windows Server 2003 e Windows XP: Una violazione di condivisione si verifica se si tenta di aprire un file o una directory per l'eliminazione in un computer remoto quando il valore del parametro dwDesiredAccess è il flag di accesso DELETE (0x00010000) OR'ed con qualsiasi altro flag di accesso e il file o la directory remota non è stata aperta con FILE_SHARE_DELETE. Per evitare la violazione di condivisione in questo scenario, aprire il file o la directory remota solo con il diritto di accesso DELETE oppure chiamare DeleteFile senza prima aprire il file o la directory per l'eliminazione.
Alcuni file system, ad esempio il file system NTFS, supportano la compressione o la crittografia per singoli file e directory. Nei volumi con un file system montato con questo supporto, un nuovo file eredita gli attributi di compressione e crittografia della relativa directory.
Non è possibile utilizzare CreateFile per controllare la compressione, la decompressione o la decrittografia in un file o in una directory. Per altre informazioni, vedere Creazione e apertura di file, compressione e decompressione dei file e crittografia dei file.
Windows Server 2003 e Windows XP: Per motivi di compatibilità con le versioni precedenti, CreateFile non applica regole di ereditarietà quando si specifica un descrittore di sicurezza in lpSecurityAttributes. Per supportare l'ereditarietà, le funzioni che in seguito eseguono query sul descrittore di sicurezza di questo file possono determinare e segnalare che l'ereditarietà è attiva. Per altre informazioni, vedere Propagazione automatica degli ACL ereditabili.
Come indicato in precedenza, se il parametro lpSecurityAttributes è NULL, l'handle restituito da CreateFile non può essere ereditato da alcun processo figlio che l'applicazione può creare. Si applicano anche le informazioni seguenti relative a questo parametro:
- Se la variabile membro bInheritHandle non è FALSE, ovvero qualsiasi valore diverso da zero, l'handle può essere ereditato. Pertanto, è fondamentale che questo membro della struttura venga inizializzato correttamente su FALSE se non si intende ereditare l'handle.
- Gli elenchi di controllo di accesso (ACL) nel descrittore di sicurezza predefinito per un file o una directory vengono ereditati dalla relativa directory padre.
- Il file system di destinazione deve supportare la sicurezza nei file e nelle directory affinché il membro lpSecurityDescriptor abbia un effetto su di essi, che può essere determinato tramite GetVolumeInformation.
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| Failover trasparente SMB 3.0 (TFO) | Vedere le osservazioni |
| SMB 3.0 con condivisioni file di scalabilità orizzontale (SO) | Vedere le osservazioni |
| File system del volume condiviso cluster (CsvFS) | Sì |
| Resilient File System (ReFS) | Sì |
Si noti che CreateFile con eliminazione sostituita avrà esito negativo se eseguita in un file in cui è già presente un flusso di dati alternativo aperto.
Comportamento del collegamento simbolico
Se la chiamata a questa funzione crea un file, non viene apportata alcuna modifica al comportamento. Considerare anche le informazioni seguenti relative FILE_FLAG_OPEN_REPARSE_POINT:-
Se viene specificato FILE_FLAG_OPEN_REPARSE_POINT :
- Se viene aperto un file esistente ed è un collegamento simbolico, l'handle restituito è un handle per il collegamento simbolico.
- Se vengono specificati TRUNCATE_EXISTING o FILE_FLAG_DELETE_ON_CLOSE , il file interessato è un collegamento simbolico.
-
Se non viene specificato FILE_FLAG_OPEN_REPARSE_POINT:
- Se un file esistente viene aperto ed è un collegamento simbolico, l'handle restituito è un handle per la destinazione.
- Se vengono specificati CREATE_ALWAYS, TRUNCATE_EXISTING o FILE_FLAG_DELETE_ON_CLOSE , il file interessato è la destinazione.
Comportamento di memorizzazione nella cache
Diversi valori possibili per il parametro dwFlagsAndAttributes vengono usati da CreateFile per controllare o influire sul modo in cui i dati associati all'handle vengono memorizzati nella cache dal sistema. ovvero:- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Alcuni di questi flag non devono essere combinati. Ad esempio, la combinazione di FILE_FLAG_RANDOM_ACCESS con FILE_FLAG_SEQUENTIAL_SCAN è auto-sconfitta.
Se si specifica il flag di FILE_FLAG_SEQUENTIAL_SCAN , è possibile aumentare le prestazioni per le applicazioni che leggeno file di grandi dimensioni usando l'accesso sequenziale. I miglioramenti delle prestazioni possono essere ancora più evidenti per le applicazioni che leggeno principalmente file di grandi dimensioni in sequenza, ma occasionalmente ignorano gli intervalli di byte di piccole dimensioni. Se un'applicazione sposta il puntatore di file per l'accesso casuale, è probabile che le prestazioni ottimali della memorizzazione nella cache non si verifichino. Tuttavia, l'operazione corretta è ancora garantita.
I flag FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING sono indipendenti e possono essere combinati.
Se FILE_FLAG_WRITE_THROUGH viene usato ma non viene specificato FILE_FLAG_NO_BUFFERING, in modo che la memorizzazione nella cache del sistema sia effettiva, i dati vengono scritti nella cache di sistema ma vengono scaricati su disco senza ritardo.
Se FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING sono entrambi specificati, in modo che la memorizzazione nella cache del sistema non sia effettiva, i dati vengono immediatamente scaricati su disco senza passare dalla cache del sistema Windows. Il sistema operativo richiede anche un write-through della cache hardware locale del disco rigido per supporti persistenti.
Una richiesta di scrittura tramite FILE_FLAG_WRITE_THROUGH causa anche lo scaricamento di eventuali modifiche ai metadati, ad esempio un aggiornamento del timestamp o un'operazione di ridenominazione, che comporta l'elaborazione della richiesta. Per questo motivo, il flag di FILE_FLAG_WRITE_THROUGH viene spesso usato con il flag FILE_FLAG_NO_BUFFERING come sostituzione per chiamare la funzione FlushFileBuffers dopo ogni scrittura, che può causare penali per le prestazioni non necessarie. L'uso di questi flag consente di evitare tali sanzioni. Per informazioni generali sulla memorizzazione nella cache dei file e dei metadati, vedere Memorizzazione nella cache dei file.
Quando FILE_FLAG_NO_BUFFERING viene combinato con FILE_FLAG_OVERLAPPED, i flag offrono prestazioni asincrone massime, perché l'I/O non si basa sulle operazioni sincrone della gestione memoria. Tuttavia, alcune operazioni di I/O richiedono più tempo, perché i dati non vengono mantenuti nella cache. Inoltre, i metadati dei file possono comunque essere memorizzati nella cache, ad esempio durante la creazione di un file vuoto. Per assicurarsi che i metadati vengano scaricati su disco, usare la funzione FlushFileBuffers .
Se è disponibile una memoria di cache sufficiente, l'attributo FILE_ATTRIBUTE_TEMPORARY causa l'eliminazione di un file system temporaneo dopo la chiusura di un handle. In tal caso, il sistema può evitare completamente di scrivere i dati. Anche se non controlla direttamente la memorizzazione nella cache dei dati nello stesso modo dei flag menzionati in precedenza, l'attributo FILE_ATTRIBUTE_TEMPORARY indica al sistema di conservare il più possibile nella cache di sistema senza scrivere e pertanto può essere di preoccupazione per determinate applicazioni.
File
Se si rinomina o si elimina un file e quindi lo si ripristina poco dopo, il sistema cerca la cache per il ripristino delle informazioni sui file. Le informazioni memorizzate nella cache includono la coppia di nomi brevi/lunghi e il tempo di creazione.Se si chiama CreateFile in un file in sospeso come risultato di una chiamata precedente a DeleteFile, la funzione ha esito negativo. Il sistema operativo ritarda l'eliminazione del file fino a quando non vengono chiusi tutti gli handle del file. GetLastError restituisce ERROR_ACCESS_DENIED.
Il parametro dwDesiredAccess può essere zero, consentendo all'applicazione di eseguire query sugli attributi del file senza accedere al file se l'applicazione è in esecuzione con impostazioni di sicurezza adeguate. Ciò è utile per testare l'esistenza di un file senza aprirlo per l'accesso in lettura e/o scrittura o per ottenere altre statistiche relative al file o alla directory. Vedere Ottenere e impostare informazioni sul file eGetFileInformationByHandle.
Se CREATE_ALWAYS e FILE_ATTRIBUTE_NORMAL vengono specificati, CreateFile ha esito negativo e imposta l'ultimo errore su ERROR_ACCESS_DENIED se il file esiste e ha l'attributo FILE_ATTRIBUTE_HIDDEN o FILE_ATTRIBUTE_SYSTEM. Per evitare l'errore, specificare gli stessi attributi del file esistente.
Quando un'applicazione crea un file in una rete, è preferibile usare dwDesiredAccess rispetto all'uso GENERIC_READ | GENERIC_WRITE di GENERIC_WRITE solo. Il codice risultante è più veloce, perché il reindirizzamento può usare la gestione cache e inviare meno PMI con più dati.
Questa combinazione evita inoltre un problema per cui la scrittura in un file in una rete può occasionalmente restituire ERROR_ACCESS_DENIED.
Per altre informazioni, vedere Creazione e apertura di file.
Handle di I/O sincroni e sincroni
CreateFile fornisce la creazione di un handle di file o dispositivo sincrono o asincrono. Un handle sincrono si comporta in modo che le chiamate di funzione di I/O usando tale handle vengano bloccate fino al completamento, mentre un handle di file asincrono consente al sistema di restituire immediatamente dalle chiamate di funzione I/O, indipendentemente dal completamento dell'operazione di I/O o. Come indicato in precedenza, questo comportamento sincrono o asincrono è determinato specificando FILE_FLAG_OVERLAPPED all'interno del parametro dwFlagsAndAttributes . Esistono diverse complessità e potenziali insodenze durante l'uso di I/O asincrone; per altre informazioni, vedere I/O sincrona e asincrona.Flussi di file
Nei file system NTFS è possibile usare CreateFile per creare flussi separati all'interno di un file. Per altre informazioni, vedere Flussi di file.Directory
Un'applicazione non può creare una directory usando CreateFile, pertanto solo il valore di OPEN_EXISTING è valido per dwCreationDisposition per questo caso dwCreationDisposition . Per creare una directory, l'applicazione deve chiamare CreateDirectory o CreateDirectoryEx.Per aprire una directory usando CreateFile, specificare il flag FILE_FLAG_BACKUP_SEMANTICS come parte di dwFlagsAndAttributes. I controlli di sicurezza appropriati si applicano ancora quando questo flag viene usato senza SE_BACKUP_NAME e SE_RESTORE_NAME privilegi.
Quando si usa CreateFile per aprire una directory durante la deframmentazione di un volume del file system FAT o FAT32, non specificare il diritto di accesso MAXIMUM_ALLOWED . L'accesso alla directory viene negato se viene eseguito. Specificare invece il diritto di accesso GENERIC_READ .
Per altre informazioni, vedere Informazioni su Gestione directory.
Dischi fisici e volumi
L'accesso diretto al disco o a un volume è limitato.Windows Server 2003 e Windows XP: L'accesso diretto al disco o a un volume non è limitato in questo modo.
È possibile usare la funzione CreateFile per aprire un'unità disco fisico o un volume, che restituisce un handle daSD (Direct Access Storage Device) che può essere usato con la funzione DeviceIoControl . In questo modo è possibile accedere direttamente al disco o al volume, ad esempio metadati del disco come la tabella di partizione. Tuttavia, questo tipo di accesso espone anche l'unità disco o il volume a potenziali perdite di dati, perché una scrittura errata in un disco usando questo meccanismo potrebbe rendere il relativo contenuto inaccessibile al sistema operativo. Per garantire l'integrità dei dati, assicurarsi di acquisire familiarità con DeviceIoControl e di come altre API si comportano in modo diverso con un handle di accesso diretto anziché con un handle di file system.
I requisiti seguenti devono essere soddisfatti per la riuscita di una chiamata di questo tipo:
- Il chiamante deve avere privilegi amministrativi. Per altre informazioni, vedere Esecuzione con privilegi speciali.
- Il parametro dwCreationDisposition deve avere il flag di OPEN_EXISTING .
- Quando si apre un volume o un disco floppy, il parametro dwShareMode deve avere il flag di FILE_SHARE_WRITE .
| string | Significato |
|---|---|
| "\\.\PhysicalDrive0" | Apre la prima unità fisica. |
| "\\.\PhysicalDrive2" | Apre la terza unità fisica. |
Per ottenere l'identificatore di unità fisica per un volume, aprire un handle per il volume e chiamare la funzione DeviceIoControl con IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Questo codice di controllo restituisce il numero e l'offset del disco per ognuno dei volumi uno o più extent; un volume può estendersi su più dischi fisici.
Per un esempio di apertura di un'unità fisica, vedere Chiamata di DeviceIoControl.
Quando si apre un volume o un'unità multimediale rimovibile ,ad esempio un'unità disco floppy o un'unità personale di memoria flash, la stringa lpFileName deve essere la forma seguente: "\.\X:". Non usare una barra rovesciata finale (\), che indica la directory radice di un'unità. La tabella seguente illustra alcuni esempi di stringhe di unità.
| string | Significato |
|---|---|
| "\.\A:" | Apre l'unità disco floppy A. |
| "\\.\C:" | Apre il volume C: |
| "\\.\C:\" | Apre il file system del volume C: . |
È anche possibile aprire un volume facendo riferimento al nome del volume. Per altre informazioni, vedere Denominazione di un volume.
Un volume contiene uno o più file system montati. Gli handle di volume possono essere aperti come non memorizzati nella cache a discrezione del file system specifico, anche quando l'opzione non memorizzata nella cache non è specificata in CreateFile. È consigliabile presupporre che tutti i file system Microsoft aprono handle di volume come non memorizzati nella cache. Le restrizioni relative all'I/O non memorizzato nella cache per i file si applicano anche ai volumi.
Un file system può richiedere o meno l'allineamento del buffer anche se i dati non sono memorizzati nella cache. Tuttavia, se l'opzione non memorizzata nella cache viene specificata durante l'apertura di un volume, l'allineamento del buffer viene applicato indipendentemente dal file system nel volume. È consigliabile in tutti i file system che si aprono handle di volume come non memorizzati nella cache e seguire le restrizioni di I/O non memorizzate nella cache.
Dispositivo modificatore
I codici di controllo IOCTL_CHANGER_* per DeviceIoControl accettano un handle per un dispositivo di modifica. Per aprire un dispositivo di modifica, usare un nome file nel formato seguente: "\.\Changerx" dove x è un numero che indica il dispositivo da aprire, a partire da zero. Per aprire il dispositivo changer zero in un'applicazione scritta in C o C++, usare il nome file seguente: "\\.\Changer0".Unità nastro
È possibile aprire unità nastro usando un nome di file nel formato seguente: "\\.\TAPEx" dove x è un numero che indica quale unità aprire, a partire dall'unità nastro zero. Per aprire l'unità nastro zero in un'applicazione scritta in C o C++, usare il nome file seguente: "\.\TAPE0".Per altre informazioni, vedere Backup.
Risorse di comunicazione
La funzione CreateFile può creare un handle per una risorsa di comunicazione, ad esempio la porta seriale COM1. Per le risorse di comunicazione, il parametro dwCreationDisposition deve essere OPEN_EXISTING, il parametro dwShareMode deve essere zero (accesso esclusivo) e il parametro hTemplateFile deve essere NULL. È possibile specificare l'accesso in lettura, scrittura o lettura/scrittura e l'handle può essere aperto per operazioni di I/O sovrapposte.Per specificare un numero di porta COM maggiore di 9, utilizzare la sintassi seguente: "\.\COM10". Questa sintassi funziona per tutti i numeri di porta e l'hardware che consente di specificare i numeri di porta COM.
Per altre informazioni sulle comunicazioni, vedere Comunicazioni.
Console
La funzione CreateFile può creare un handle per l'input della console (CONIN$). Se il processo dispone di un handle aperto in seguito all'ereditarietà o alla duplicazione, può anche creare un handle per il buffer dello schermo attivo (CONOUT$). Il processo chiamante deve essere collegato a una console ereditata o a una allocata dalla funzione AllocConsole . Per gli handle della console, impostare i parametri CreateFile come indicato di seguito.| Parametri | Valore |
|---|---|
| lpFileName |
Usare il valore CONIN$ per specificare l'input della console.
Usare il valore CONOUT$ per specificare l'output della console. CONIN$ ottiene un handle per il buffer di input della console, anche se la funzione SetStdHandle reindirizza l'handle di input standard. Per ottenere l'handle di input standard, usare la funzione GetStdHandle . CONOUT$ ottiene un handle per il buffer dello schermo attivo, anche se SetStdHandle reindirizza l'handle di output standard. Per ottenere l'handle di output standard, usare GetStdHandle. |
| dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE è preferibile, ma uno può limitare l'accesso.
|
| dwShareMode |
Quando si apre CONIN$, specificare FILE_SHARE_READ. Quando si apre CONOUT$, specificare FILE_SHARE_WRITE.
Se il processo chiamante eredita la console o se un processo figlio deve essere in grado di accedere alla console, questo parametro deve essere |
| lpSecurityAttributes | Se si desidera che la console venga ereditata, il membro bInheritHandle della struttura SECURITY_ATTRIBUTES deve essere TRUE. |
| dwCreationDisposition | È necessario specificare OPEN_EXISTING quando si usa CreateFile per aprire la console. |
| dwFlagsAndAttributes | Ignorato. |
| hTemplateFile | Ignorato. |
La tabella seguente illustra varie impostazioni di dwDesiredAccess e lpFileName.
| lpFileName | dwDesiredAccess | Risultato |
|---|---|---|
| "CON" | GENERIC_READ | Apre la console per l'input. |
| "CON" | GENERIC_WRITE | Apre la console per l'output. |
| "CON" | GENERIC_READ | GENERIC_WRITE |
Causa l'esito negativo di CreateFile ; GetLastError restituisce ERROR_FILE_NOT_FOUND. |
Mailslots
Se CreateFile apre la fine client di un oggetto mailslot, la funzione restituisce INVALID_HANDLE_VALUE se il client mailslot tenta di aprire un oggetto mailslot locale prima che il server mailslot lo abbia creato con la funzione CreateMailSlot .Per altre informazioni, vedere Mailslots.
Tubi
Se CreateFile apre la fine del client di una named pipe, la funzione usa qualsiasi istanza della named pipe che si trova nello stato di ascolto. Il processo di apertura può duplicare l'handle tutte le volte necessario, ma dopo l'apertura, l'istanza della named pipe non può essere aperta da un altro client. L'accesso specificato quando viene aperta una pipe deve essere compatibile con l'accesso specificato nel parametro dwOpenMode della funzione CreateNamedPipe .Se la funzione CreateNamedPipe non è stata chiamata correttamente nel server prima di questa operazione, non esisterà una pipe e CreateFile avrà esito negativo con ERROR_FILE_NOT_FOUND.
Se è presente almeno un'istanza della pipe attiva ma non sono presenti pipe del listener disponibili nel server, il che significa che tutte le istanze della pipe sono attualmente connesse, CreateFile ha esito negativo con ERROR_PIPE_BUSY.
Per altre informazioni, vedere Pipe.
Esempio
Le operazioni sui file di esempio sono illustrate negli argomenti seguenti:
- Aggiunta di un file a un altro file
- Annullamento delle operazioni di I/O in sospeso
- Creazione di un processo figlio con input e output reindirizzati
- Creazione e uso di un file temporaneo
- FSCTL_RECALL_FILE
- GetFinalPathNameByHandle
- Blocco e sblocco degli intervalli di byte nei file
- Recupero di un nome file da un handle di file
- Recupero delle informazioni di riconoscimento del file system
- Apertura di un file per la lettura o la scrittura
- Recupero dell'ora di Last-Write
- SetFileInformationByHandle
- Test per la fine di un file
- Uso delle fibre
- Uso dei flussi
- Memorizzazione di un buffer di record del journal delle modifiche
- Wow64DisableWow64FsRedirection
- Wow64EnableWow64FsRedirection
- Chiamata a DeviceIoControl
- Configurazione di una risorsa di comunicazione
- Monitoraggio degli eventi di comunicazione
- Elaborazione di una richiesta per rimuovere un dispositivo
L'uso di una mailslot viene visualizzato in Scrittura in una mailslot.
È possibile trovare un frammento di codice di backup nastro in Creazione di un'applicazione di backup.
Nota
L'intestazione fileapi.h definisce CreateFile come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
Requisiti
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | fileapi.h (includere Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |
Vedere anche
Informazioni sulla gestione delle directory
Informazioni sulla gestione dei volumi
Creazione, eliminazione e gestione di file
Controllo input e output del dispositivo (IOCTL)
Compressione e decompressione dei file
Diritti di sicurezza e accesso dei file
Funzioni
Recupero e impostazione delle informazioni sui file
Argomenti di panoramica
Commenti e suggerimenti
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, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per