Funzione CreateFileA (fileapi.h)

Articolo
06/02/2023

Crea o apre un file o un dispositivo di I/O. I dispositivi di 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 transazioni, 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 (/) 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, anteporre "\\?\" al percorso. Per altre informazioni, vedere denominazione di file, percorsi e spazi dei nomi.

Mancia

A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente alla rimozione della limitazione MAX_PATH senza anteporre "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di nomi, percorsi e spazi dei nomi.

Per informazioni sui nomi speciali dei dispositivi, vedere Definizione di un nome di dispositivo MS-DOS.

Per creare un flusso di file, specificare il nome del file, i due punti 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_WRITEo entrambi (GENERIC_READ | GENERIC_WRITE). Per altre informazioni, vedere diritti di accesso generico, diritti di accesso e sicurezza dei file, costanti per i diritti di accesso ai filee 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

Modalità di condivisione richiesta del file o del dispositivo, che può essere letta, scritta, entrambe, eliminate, tutte queste o nessuna (vedere la 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 aperto di nuovo fino alla chiusura dell'handle nel file o nel dispositivo. 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 avrà esito negativo e la funzione GetLastError restituirà ERROR_SHARING_VIOLATION.

Per consentire a un processo di 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 Creating and Opening Files.

Nota Le opzioni di condivisione per ogni handle aperto rimangono attive fino a quando tale handle non viene chiuso, indipendentemente dal contesto del processo.

Valore	Significato
0 0x00000000	Impedisce ad altri processi di aprire un file o un dispositivo se richiedono l'eliminazione, la lettura o l'accesso in scrittura.
FILE_SHARE_DELETE 0x00000004	Consente alle successive operazioni aperte su un file o un dispositivo di richiedere l'accesso per l'eliminazione. In caso contrario, altri processi non possono aprire il file o il dispositivo se richiedono l'accesso eliminato. Se questo flag non è specificato, ma il file o il dispositivo è stato aperto per l'accesso all'eliminazione, la funzione ha esito negativo. Nota Eliminare l'accesso consente operazioni di eliminazione e ridenominazione.
FILE_SHARE_READ 0x00000001	Consente alle successive operazioni aperte su un file o un dispositivo di richiedere l'accesso in lettura. In caso contrario, altri processi non possono aprire il file o il dispositivo se richiedono l'accesso in lettura. Se questo flag non è specificato, ma il file o il dispositivo è stato aperto per l'accesso in lettura, la funzione ha esito negativo.
FILE_SHARE_WRITE 0x00000002	Consente alle successive operazioni aperte su un file o un dispositivo di richiedere l'accesso in scrittura. In caso contrario, altri processi non possono aprire il file o il dispositivo se richiedono l'accesso in scrittura. Se questo flag non è specificato, ma il file o il dispositivo è stato aperto per l'accesso in scrittura o ha un mapping di file con accesso in scrittura, la funzione ha esito negativo.

[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 qualsiasi processo figlio che l'applicazione può creare e il file o il dispositivo associato all'handle restituito ottiene un descrittore di sicurezza predefinito.

Il lpSecurityDescriptor membro della struttura specifica un SECURITY_DESCRIPTOR per un file o un dispositivo. Se questo membro è NULL, al file o al 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 bInheritHandle membro della struttura specifica se l'handle restituito può essere ereditato.

Per altre informazioni, vedere la sezione Osservazioni.

[in] dwCreationDisposition

Azione da eseguire su un file o un dispositivo esistente o non esistente.

Per i dispositivi diversi dai file, questo parametro viene 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:

Valore	Significato
CREATE_ALWAYS 2	Crea sempre un nuovo file. Se il file specificato esiste ed è scrivibile, la funzione tronca il file, la funzione ha esito positivo e il codice dell'ultimo errore viene impostato su ERROR_ALREADY_EXISTS (183). Se il file specificato non esiste ed è un percorso valido, viene creato un nuovo file, la funzione ha esito positivo e l'ultimo codice di errore è impostato su zero. Per altre informazioni, vedere la sezione Osservazioni di questo argomento.
CREATE_NEW 1	Crea un nuovo file, solo se non esiste già. Se il file specificato esiste, la funzione ha esito negativo e l'ultimo codice di errore viene impostato su ERROR_FILE_EXISTS (80). Se il file specificato non esiste ed è un percorso valido per un percorso scrivibile, viene creato un nuovo file.
OPEN_ALWAYS 4	Apre sempre un file. Se il file specificato esiste, la funzione ha esito positivo e l'ultimo codice di errore viene impostato su ERROR_ALREADY_EXISTS (183). Se il file specificato non esiste ed è un percorso valido per un percorso scrivibile, la funzione crea un file e l'ultimo codice di errore è impostato su zero.
OPEN_EXISTING 3	Apre un file o un dispositivo, solo se esiste. Se il file o il dispositivo specificato non esiste, la funzione ha esito negativo e l'ultimo codice di errore è impostato su ERROR_FILE_NOT_FOUND (2). Per altre informazioni sui dispositivi, vedere la sezione Osservazioni.
TRUNCATE_EXISTING 5	Apre un file e lo tronca in modo che le dimensioni siano pari a zero byte, solo se esiste. Se il file specificato non esiste, la funzione ha esito negativo e l'ultimo codice di errore è impostato su ERROR_FILE_NOT_FOUND (2). Il processo chiamante deve aprire il file con il bit GENERIC_WRITE impostato come parte del parametro dwDesiredAccess.

[in] dwFlagsAndAttributes

Gli attributi e i flag del file o del dispositivo, FILE_ATTRIBUTE_NORMAL essere il valore predefinito più comune per i file.

Questo parametro può includere qualsiasi combinazione degli attributi del file disponibili (FILE_ATTRIBUTE_*). Tutti gli altri attributi di file sostituiscono FILE_ATTRIBUTE_NORMAL.

Questo parametro può contenere anche combinazioni di flag (FILE_FLAG_*) per il controllo del comportamento di memorizzazione nella cache dei file o dei dispositivi, delle modalità di accesso e di altri flag speciali. Questi valori vengono combinati con qualsiasi FILE_ATTRIBUTE_* valori.

Questo parametro può contenere anche informazioni sulla qualità del servizio (SQOS) specificando il flag SECURITY_SQOS_PRESENT. Le informazioni aggiuntive sui flag correlati a SQOS vengono presentate nella tabella che segue gli attributi e le tabelle dei flag.

Nota Quando CreateFile apre un file esistente, in genere combina i flag di file con gli attributi di file del file esistente e ignora gli attributi di file forniti come parte di dwFlagsAndAttributes. I casi speciali sono descritti in dettaglio in Creazione e apertura di file.

Alcuni degli attributi e dei flag di file seguenti possono essere applicati solo ai file e non necessariamente a tutti gli altri tipi di dispositivi che CreateFile possono essere aperti. Per altre informazioni, vedere la sezione Osservazioni di questo argomento e Creazione e apertura di file.

Per l'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
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Il file deve essere archiviato. Le applicazioni usano questo attributo per contrassegnare i file per il backup o la rimozione.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	Il file o la directory è crittografato. Per un file, ciò significa che tutti i dati nel file vengono crittografati. Per una directory, significa che la crittografia è l'impostazione predefinita per i file e le sottodirectory appena creati. Per altre informazioni, vedere File Encryption. Questo flag non ha alcun effetto se viene specificato anche FILE_ATTRIBUTE_SYSTEM. Questo flag non è supportato nelle edizioni Home, Home Premium, Starter o ARM di Windows.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	Il file è nascosto. Non includerlo in un elenco di directory normale.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	Il file non dispone di altri attributi impostati. Questo attributo è valido solo se usato da solo.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	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 gerarchica delle risorse di archiviazione. Le applicazioni non devono modificare arbitrariamente questo attributo.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Il file è di sola lettura. Le applicazioni possono leggere il file, ma non possono scriverlo o eliminarlo.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Il file fa parte o viene utilizzato esclusivamente da un sistema operativo.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Il file viene usato per l'archiviazione temporanea. Per altre informazioni, vedere la sezione comportamento di memorizzazione nella cache di questo argomento.

Bandiera	Significato
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	Il file viene aperto o creato per un'operazione di backup o ripristino. Il sistema garantisce che il processo chiamante sostituisa i controlli di 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 su una directory. Un handle di directory può essere passato ad alcune funzioni anziché a un handle di file. Per altre informazioni, vedere la sezione Osservazioni.
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	Il file deve essere eliminato immediatamente dopo la chiusura di tutti i relativi handle, che include l'handle specificato e qualsiasi altro handle aperto o duplicato. Se sono presenti handle aperti esistenti in un file, la chiamata ha esito negativo a meno che non siano state tutte aperte 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.
FILE_FLAG_NO_BUFFERING 0x20000000	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 File Buffering.
FILE_FLAG_OPEN_NO_RECALL 0x00100000	I dati del file vengono richiesti, ma devono continuare a trovarsi nell'archiviazione remota. Non deve essere trasportato nuovamente nella risorsa di archiviazione locale. Questo flag è destinato all'uso da parte di sistemi di archiviazione remoti.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	Non si verificherà normale punto di analisi; CreateFile tenterà di aprire il reparse point. Quando un file viene aperto, viene restituito un handle di file, indipendentemente dal fatto che il filtro che controlla il punto di analisi sia operativo. Questo flag non può essere utilizzato con il flag CREATE_ALWAYS. Se il file non è un reparse point, questo flag viene ignorato. Per altre informazioni, vedere la sezione Osservazioni.
FILE_FLAG_OVERLAPPED 0x40000000	Il file o il dispositivo viene aperto o creato per l'I/O asincrono. Quando vengono completate le operazioni di I/O successive su questo handle, l'evento specificato nella struttura OVERLAPPED verrà impostato sullo stato segnalato. Se questo flag viene specificato, il file può essere usato per operazioni di lettura e scrittura simultanee. Se questo flag non viene 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 relative all'uso di un handle di file creato con questo flag, vedere la sezione handle di I/O sincroni e asincroni di questo argomento.
FILE_FLAG_POSIX_SEMANTICS 0x01000000	L'accesso verrà eseguito in base alle regole POSIX. Ciò include l'uso di più file con nomi diversi solo nel caso, per i file system che supportano tale denominazione. Prestare attenzione quando si usa questa opzione, perché i file creati con questo flag potrebbero non essere accessibili dalle applicazioni scritte per windows a MS-DOS o a 16 bit.
FILE_FLAG_RANDOM_ACCESS 0x10000000	L'accesso deve essere casuale. Il sistema può usarlo come suggerimento per ottimizzare la memorizzazione nella cache dei file. Questo flag non ha alcun 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.
FILE_FLAG_SESSION_AWARE 0x00800000	Il file o il dispositivo viene aperto con consapevolezza della sessione. Se questo flag non viene specificato, i dispositivi per sessione (ad esempio un dispositivo che usa il reindirizzamento USB RemoteFX) non possono essere aperti dai 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 di Windows Server 2012.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	L'accesso deve essere sequenziale dall'inizio alla fine. Il sistema può usarlo come suggerimento per ottimizzare la memorizzazione nella cache dei file. Questo flag non deve essere usato se verrà usato read-behind (ovvero analisi inversi). Questo flag non ha alcun 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.
FILE_FLAG_WRITE_THROUGH 0x80000000	Le operazioni di scrittura non passeranno attraverso alcuna cache intermedia, verranno passate direttamente al disco. Per altre informazioni, vedere la sezione comportamento di memorizzazione nella cache di questo argomento.

Il parametro dwFlagsAndAttributes può specificare anche le 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.

Flag di sicurezza	Significato
SECURITY_ANONYMOUS	Rappresenta un client a livello di rappresentazione anonima.
SECURITY_CONTEXT_TRACKING	La modalità di rilevamento della sicurezza è dinamica. Se questo flag non è specificato, la modalità di rilevamento della sicurezza è statica.
SECURITY_DELEGATION	Rappresenta un client a livello di rappresentazione della delega.
SECURITY_EFFECTIVE_ONLY	Solo gli aspetti abilitati del contesto di sicurezza del client sono disponibili per il server. Se non si specifica questo flag, sono disponibili tutti gli aspetti del contesto di sicurezza del client. In questo modo il client può limitare i gruppi e i privilegi che un server può usare durante la rappresentazione del client.
SECURITY_IDENTIFICATION	Rappresenta un client a livello di rappresentazione dell'identificazione.
SECURITY_IMPERSONATION	Rappresenta un client a livello di rappresentazione. Questo è il comportamento predefinito se non vengono specificati altri flag insieme al flag SECURITY_SQOS_PRESENT.

[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 specificati.

Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

CreateFile è stato originariamente sviluppato appositamente per l'interazione con i file, ma è stato ampliato e migliorato per includere la maggior parte degli altri tipi di dispositivi e meccanismi di I/O disponibili per gli sviluppatori Windows. Questa sezione tenta di trattare i vari problemi che gli sviluppatori possono riscontrare quando si usano CreateFile in contesti diversi e con tipi di I/O diversi. Il testo tenta di utilizzare la parola file solo quando si fa riferimento specificamente ai dati archiviati in un file system effettivo. Tuttavia, alcuni usi di 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: Si verifica una violazione di condivisione 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 sono stati aperti con FILE_SHARE_DELETE. Per evitare la violazione di condivisione in questo scenario, aprire il file o la directory remota con il diritto di accesso DELETE solo o 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 di 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 in modo euristico 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 processi 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 inizializzare correttamente questo membro della struttura per 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 directory padre.
Il file system di destinazione deve supportare la sicurezza su file e directory per il membro lpSecurityDescriptor, che può essere determinato usando GetVolumeInformation.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Sostenuto
Protocollo SMB (Server Message Block) 3.0	Sì
SMB 3.0 Transparent Failover (TFO)	Vedere le osservazioni
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Vedere le osservazioni
Cluster Shared Volume File System (CsvFS)	Sì
Resilient File System (ReFS)	Sì

Si noti che CreateFile con eliminazione sostituita avrà esito negativo se eseguito 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 a FILE_FLAG_OPEN_REPARSE_POINT:

Se si specifica FILE_FLAG_OPEN_REPARSE_POINT:
- Se un file esistente viene aperto 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 FILE_FLAG_OPEN_REPARSE_POINT non è specificato:
- Se un file esistente viene aperto ed è un collegamento simbolico, l'handle restituito è un handle per la destinazione.
- Se vengono specificati CREATE_ALWAYS, TRUNCATE_EXISTINGo 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 sulla modalità di memorizzazione nella cache dei dati associati all'handle dal sistema. Sono:

FILE_FLAG_NO_BUFFERING
FILE_FLAG_RANDOM_ACCESS
FILE_FLAG_SEQUENTIAL_SCAN
FILE_FLAG_WRITE_THROUGH
FILE_ATTRIBUTE_TEMPORARY

Se nessuno di questi flag è specificato, il sistema usa uno schema di memorizzazione nella cache per utilizzo generico predefinito. In caso contrario, la memorizzazione nella cache del sistema si comporta come specificato per ogni flag.

Alcuni di questi flag non devono essere combinati. Ad esempio, la combinazione di FILE_FLAG_RANDOM_ACCESS con FILE_FLAG_SEQUENTIAL_SCAN è auto-sconfitta.

La specifica del flag di FILE_FLAG_SEQUENTIAL_SCAN può migliorare le prestazioni per le applicazioni che leggono file di grandi dimensioni usando l'accesso sequenziale. I miglioramenti delle prestazioni possono essere ancora più evidenti per le applicazioni che leggono file di grandi dimensioni principalmente in sequenza, ma occasionalmente ignorano in avanti su intervalli di byte di piccole dimensioni. Se un'applicazione sposta il puntatore al file per l'accesso casuale, le prestazioni di memorizzazione nella cache ottimali probabilmente non si verificheranno. Tuttavia, l'operazione corretta è comunque 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 attiva, i dati vengono scritti nella cache di sistema ma scaricati su disco senza ritardi.

Se FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING vengono specificati entrambi, in modo che la memorizzazione nella cache del sistema non sia attiva, i dati vengono scaricati immediatamente su disco senza passare attraverso la cache di sistema di Windows. Il sistema operativo richiede inoltre un write-through della cache hardware locale del disco rigido a supporti persistenti.

Nota Non tutti gli hardware del disco rigido supportano questa funzionalità di scrittura.

L'uso corretto del flag di FILE_FLAG_NO_BUFFERING richiede considerazioni speciali sull'applicazione. Per altre informazioni, vedere file buffering.

Una richiesta write-through tramite FILE_FLAG_WRITE_THROUGH fa anche in modo che NTFS scarichi tutte le modifiche ai metadati, ad esempio un aggiornamento timestamp o un'operazione di ridenominazione, risultante dall'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 inutili sanzioni per le prestazioni. L'uso di questi flag insieme evita 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 della memoria. Tuttavia, alcune operazioni di I/O richiedono più tempo, perché i dati non vengono mantenuti nella cache. Inoltre, i metadati del file possono essere ancora 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 si specifica l'attributo FILE_ATTRIBUTE_TEMPORARY, i file system evitano di scrivere i dati nell'archiviazione di massa se è disponibile memoria cache sufficiente, perché un'applicazione elimina un file 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 nella cache le informazioni sui file da ripristinare. Le informazioni memorizzate nella cache includono la coppia nome breve/lungo 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 dei file fino a quando tutti gli handle del file non vengono chiusi. 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 verificare 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 le informazioni sui file e GetFileInformationByHandle.

Se vengono specificati CREATE_ALWAYS e FILE_ATTRIBUTE_NORMAL, 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 GENERIC_READ | GENERIC_WRITE per dwDesiredAccess piuttosto che usare GENERIC_WRITE da solo. Il codice risultante è più veloce, perché il redirector può usare gestione cache e inviare meno SMB 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 asincroni

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 che usano tale handle vengano bloccate fino al completamento, mentre un handle di file asincrono consente al sistema di restituire immediatamente dalle chiamate di funzione di I/O, indipendentemente dal fatto che abbiano completato o meno l'operazione di I/O. Come indicato in precedenza, questo comportamento sincrono e asincrono viene determinato specificando FILE_FLAG_OVERLAPPED all'interno del parametro dwFlagsAndAttributes. Esistono diverse complessità e potenziali insidie quando si usa l'I/O asincrona; 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.

dischi fisici e volumi

L'accesso diretto al disco o a un volume è limitato.

Windows Server 2003 e Windows XP: 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 non corretta in un disco che usa questo meccanismo potrebbe rendere il contenuto inaccessibile al sistema operativo. Per garantire l'integrità dei dati, assicurarsi di acquisire familiarità con DeviceIoControl e il comportamento di altre API in modo diverso con un handle di accesso diretto anziché con un handle del file system.

Per il successo di una chiamata di questo tipo, è necessario soddisfare i requisiti seguenti:

Il chiamante deve disporre di 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 FILE_SHARE_WRITE.

Nota Il parametro dwDesiredAccess può essere zero, consentendo all'applicazione di eseguire query sugli attributi del dispositivo senza accedere a un dispositivo. Ciò è utile per un'applicazione per determinare le dimensioni di un'unità disco floppy e i formati supportati senza richiedere un disco floppy in un'unità, ad esempio. Può essere usato anche per la lettura delle statistiche senza richiedere autorizzazioni di lettura/scrittura di dati di livello superiore.

Quando si apre un'unità fisica x:, la stringa lpFileName deve essere la seguente: "\\.\PhysicalDriveX". I numeri del disco rigido iniziano da zero. La tabella seguente illustra alcuni esempi di stringhe di unità fisiche.

Corda	Significato
"\.\PhysicalDrive0"	Apre la prima unità fisica.
"\.\PhysicalDrive2"	Apre la terza unità fisica.

Per ottenere l'identificatore dell'unità fisica per un volume, aprire un handle al volume e chiamare la funzione DeviceIoControl con IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Questo codice di controllo restituisce il numero del disco e l'offset per ogni extent del volume; 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à chiavetta flash), l'lpFileName stringa deve essere il formato 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à.

Corda	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 Naming a 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 quando si apre 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.

Nota Per leggere o scrivere negli ultimi settori del volume, è necessario chiamare DeviceIoControl e specificare FSCTL_ALLOW_EXTENDED_DASD_IO. In questo modo il driver del file system non esegue alcun controllo dei limiti di I/O sulle chiamate di lettura o scrittura della partizione. I controlli limite vengono invece eseguiti dal driver di dispositivo.

dispositivo di modifica

I codici di controllo IOCTL_CHANGER_* per DeviceIoControl accettano un handle in un dispositivo di modifica. Per aprire un dispositivo di modifica, usare un nome di file nel formato seguente: "\\.\Changerx" dove x è un numero che indica quale dispositivo 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 scrittura e l'handle può essere aperto per operazioni di I/O sovrapposte.

Per specificare un numero di porta COM maggiore di 9, usare 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 Communications.

Console

La funzione CreateFile può creare un handle per l'input della console (CONIN$). Se il processo ha un handle aperto a esso 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 è possibile 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 `FILE_SHARE_READ \| FILE_SHARE_WRITE`.
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 del client di un messaggio di posta elettronica, la funzione restituisce INVALID_HANDLE_VALUE se il client mailslot tenta di aprire un messaggio di posta locale prima che il server mailslot lo abbia creato con la funzione CreateMailSlot.

Per altre informazioni, vedere Mailslots.

pipe

Se CreateFile apre la fine client di una named pipe, la funzione usa qualsiasi istanza della named pipe nello stato di ascolto. Il processo di apertura può duplicare l'handle quante più 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.

Esempi

Le operazioni di file di esempio sono illustrate negli argomenti seguenti:

L'I/O del dispositivo fisico è illustrato negli argomenti seguenti:

Un esempio di uso di named pipe si trova in named pipe client.

L'utilizzo di un file mailslot viene visualizzato in Scrittura in unMailslot.

Un frammento di codice di backup su nastro è disponibile 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 indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	fileapi.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll