Partager via


CreateFileW, fonction (fileapi.h)

Crée ou ouvre un fichier ou un périphérique d’E/S. Les périphériques d’E/S les plus couramment utilisés sont les suivants : fichier, flux de fichiers, répertoire, disque physique, volume, mémoire tampon de la console, lecteur de bande, ressource de communication, fente de courrier et tuyau. La fonction retourne un handle qui peut être utilisé pour accéder au fichier ou à l’appareil pour différents types d’E/S en fonction du fichier ou de l’appareil et des indicateurs et attributs spécifiés.

Pour effectuer cette opération en tant qu’opération traitée, ce qui aboutit à un handle qui peut être utilisé pour les E/S traitées, utilisez la fonction CreateFileTransacted .

Syntaxe

HANDLE CreateFileW(
  [in]           LPCWSTR               lpFileName,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwCreationDisposition,
  [in]           DWORD                 dwFlagsAndAttributes,
  [in, optional] HANDLE                hTemplateFile
);

Paramètres

[in] lpFileName

Nom du fichier ou de l’appareil à créer ou à ouvrir. Vous pouvez utiliser des barres obliques (/) ou des barres obliques inverses (\) dans ce nom.

Pour plus d’informations sur les noms d’appareils spéciaux, consultez Définition d’un nom d’appareil MS-DOS.

Pour créer un flux de fichiers, spécifiez le nom du fichier, un signe deux-points, puis le nom du flux. Pour plus d’informations, consultez Flux de fichiers.

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères larges, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.

Conseil

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précédencer « \\ ?\ ». Pour plus d’informations, consultez la section « Limitation maximale de la longueur du chemin d’accès » de Naming Files, Paths et Namespaces .

[in] dwDesiredAccess

Accès demandé au fichier ou à l’appareil, qui peut être résumé en lecture, écriture, les deux ou zéro).

Les valeurs les plus couramment utilisées sont GENERIC_READ, GENERIC_WRITE ou les deux (GENERIC_READ | GENERIC_WRITE). Pour plus d’informations, consultez Droits d’accès génériques, Sécurité des fichiers et droits d’accès, Constantes des droits d’accès aux fichiers et ACCESS_MASK.

Si ce paramètre est égal à zéro, l’application peut interroger certaines métadonnées telles que des attributs de fichier, de répertoire ou d’appareil sans accéder à ce fichier ou à cet appareil, même si GENERIC_READ accès aurait été refusé.

Vous ne pouvez pas demander un mode d’accès qui entre en conflit avec le mode de partage spécifié par le paramètre dwShareMode dans une demande ouverte qui a déjà un handle ouvert.

Pour plus d’informations, consultez la section Remarques de cette rubrique et Création et ouverture de fichiers.

[in] dwShareMode

Mode de partage demandé du fichier ou de l’appareil, qui peut être lu, écrit, à la fois, supprimé, tous ces éléments ou aucun (reportez-vous au tableau suivant). Les demandes d’accès aux attributs ou aux attributs étendus ne sont pas affectées par cet indicateur.

Si ce paramètre est égal à zéro et que CreateFile réussit, le fichier ou l’appareil ne peut pas être partagé et ne peut pas être rouvert tant que le handle du fichier ou de l’appareil n’est pas fermé. Pour plus d'informations, consultez la section Notes.

Vous ne pouvez pas demander un mode de partage qui entre en conflit avec le mode d’accès spécifié dans une demande existante qui a un handle ouvert. CreateFile échoue et la fonction GetLastError retourne ERROR_SHARING_VIOLATION.

Pour permettre à un processus de partager un fichier ou un appareil alors qu’un autre processus a ouvert le fichier ou l’appareil, utilisez une combinaison compatible d’une ou plusieurs des valeurs suivantes. Pour plus d’informations sur les combinaisons valides de ce paramètre avec le paramètre dwDesiredAccess , consultez Création et ouverture de fichiers.

Note Les options de partage pour chaque handle ouvert restent en vigueur jusqu’à ce que ce handle soit fermé, quel que soit le contexte du processus.
Valeur Signification
0
0x00000000
Empêche les opérations d’ouverture suivantes sur un fichier ou un appareil si elles demandent un accès à la suppression, à la lecture ou à l’écriture.
FILE_SHARE_DELETE
0x00000004
Active les opérations d’ouverture suivantes sur un fichier ou un appareil pour demander l’accès à la suppression.

Sinon, aucun processus ne peut ouvrir le fichier ou l’appareil s’il demande un accès de suppression.

Si cet indicateur n’est pas spécifié, mais que le fichier ou l’appareil a été ouvert pour l’accès à la suppression, la fonction échoue.

Note Supprimer l’accès permet les opérations de suppression et de renommage.
FILE_SHARE_READ
0x00000001
Permet aux opérations d’ouverture suivantes sur un fichier ou un appareil de demander l’accès en lecture.

Sinon, aucun processus ne peut ouvrir le fichier ou l’appareil s’il demande un accès en lecture.

Si cet indicateur n’est pas spécifié, mais que le fichier ou l’appareil a été ouvert pour l’accès en lecture, la fonction échoue.

FILE_SHARE_WRITE
0x00000002
Permet aux opérations d’ouverture suivantes sur un fichier ou un appareil de demander l’accès en écriture.

Sinon, aucun processus ne peut ouvrir le fichier ou l’appareil s’il demande un accès en écriture.

Si cet indicateur n’est pas spécifié, mais que le fichier ou l’appareil a été ouvert pour l’accès en écriture ou a un mappage de fichiers avec accès en écriture, la fonction échoue.

[in, optional] lpSecurityAttributes

Pointeur vers une structure de SECURITY_ATTRIBUTES qui contient deux membres de données distincts mais associés : un descripteur de sécurité facultatif et une valeur booléenne qui détermine si le handle retourné peut être hérité par des processus enfants.

Ce paramètre peut être NULL.

Si ce paramètre a la valeur NULL, le handle retourné par CreateFile ne peut pas être hérité par les processus enfants que l’application peut créer et le fichier ou l’appareil associé au handle retourné obtient un descripteur de sécurité par défaut.

Le membre lpSecurityDescriptor de la structure spécifie un SECURITY_DESCRIPTOR pour un fichier ou un appareil. Si ce membre a la valeur NULL, un descripteur de sécurité par défaut est attribué au fichier ou à l’appareil associé au handle retourné.

CreateFile ignore le membre lpSecurityDescriptor lors de l’ouverture d’un fichier ou d’un appareil existant, mais continue d’utiliser le membre bInheritHandle .

Le membre bInheritHandle de la structure spécifie si le handle retourné peut être hérité.

Pour plus d'informations, consultez la section Notes.

[in] dwCreationDisposition

Action à entreprendre sur un fichier ou un appareil qui existe ou n’existe pas.

Pour les appareils autres que les fichiers, ce paramètre est généralement défini sur OPEN_EXISTING.

Pour plus d'informations, consultez la section Notes.

Ce paramètre doit être l’une des valeurs suivantes, qui ne peuvent pas être combinées :

Valeur Signification
CREATE_ALWAYS
2
Crée un fichier, toujours.

Si le fichier spécifié existe et est accessible en écriture, la fonction tronque le fichier, la fonction réussit et le code de la dernière erreur est défini sur ERROR_ALREADY_EXISTS (183).

Si le fichier spécifié n’existe pas et qu’il s’agit d’un chemin d’accès valide, un nouveau fichier est créé, la fonction réussit et le code de la dernière erreur est défini sur zéro.

Pour plus d’informations, consultez la section Remarques de cette rubrique.

CREATE_NEW
1
Crée un fichier, uniquement s’il n’existe pas déjà.

Si le fichier spécifié existe, la fonction échoue et le code de dernière erreur est défini sur ERROR_FILE_EXISTS (80).

Si le fichier spécifié n’existe pas et qu’il s’agit d’un chemin d’accès valide à un emplacement accessible en écriture, un nouveau fichier est créé.

OPEN_ALWAYS
4
Ouvre toujours un fichier.

Si le fichier spécifié existe, la fonction réussit et le code de dernière erreur est défini sur ERROR_ALREADY_EXISTS (183).

Si le fichier spécifié n’existe pas et qu’il s’agit d’un chemin d’accès valide à un emplacement accessible en écriture, la fonction crée un fichier et le code de dernière erreur est défini sur zéro.

OPEN_EXISTING
3
Ouvre un fichier ou un appareil, uniquement s’il existe.

Si le fichier ou l’appareil spécifié n’existe pas, la fonction échoue et le code de dernière erreur est défini sur ERROR_FILE_NOT_FOUND (2).

Pour plus d’informations sur les appareils, consultez la section Remarques.

TRUNCATE_EXISTING
5
Ouvre un fichier et le tronque de sorte que sa taille soit égale à zéro octet, uniquement s’il existe.

Si le fichier spécifié n’existe pas, la fonction échoue et le code de dernière erreur est défini sur ERROR_FILE_NOT_FOUND (2).

Le processus appelant doit ouvrir le fichier avec le GENERIC_WRITE bit défini dans le cadre du paramètre dwDesiredAccess .

[in] dwFlagsAndAttributes

Attributs et indicateurs de fichier ou d’appareil, FILE_ATTRIBUTE_NORMAL étant la valeur par défaut la plus courante pour les fichiers.

Ce paramètre peut inclure n’importe quelle combinaison des attributs de fichier disponibles (FILE_ATTRIBUTE_*). Tous les autres attributs de fichier remplacent FILE_ATTRIBUTE_NORMAL.

Ce paramètre peut également contenir des combinaisons d’indicateurs (FILE_FLAG_) pour le contrôle du comportement de mise en cache des fichiers ou des appareils, des modes d’accès et d’autres indicateurs à usage spécial. Ils se combinent à n’importe quelle valeur FILE_ATTRIBUTE_ .

Ce paramètre peut également contenir des informations SQOS (Security Quality of Service) en spécifiant l’indicateur SECURITY_SQOS_PRESENT . Des informations supplémentaires relatives aux indicateurs SQOS sont présentées dans le tableau suivant les tables d’attributs et d’indicateurs.

Note Quand CreateFile ouvre un fichier existant, il combine généralement les indicateurs de fichier avec les attributs de fichier du fichier existant et ignore tous les attributs de fichier fournis dans le cadre de dwFlagsAndAttributes. Les cas spéciaux sont détaillés dans Création et ouverture de fichiers.
Certains des attributs et indicateurs de fichier suivants peuvent s’appliquer uniquement aux fichiers et pas nécessairement à tous les autres types d’appareils que CreateFile peut ouvrir. Pour plus d’informations, consultez la section Remarques de cette rubrique et Création et ouverture de fichiers.

Pour un accès plus avancé aux attributs de fichier, consultez SetFileAttributes. Pour obtenir la liste complète de tous les attributs de fichier avec leurs valeurs et descriptions, consultez Constantes d’attribut de fichier.

Attribut Signification
FILE_ATTRIBUTE_ARCHIVE
32 (0x20)
Le fichier doit être archivé. Les applications utilisent cet attribut pour marquer des fichiers à des fins de sauvegarde ou de suppression.
FILE_ATTRIBUTE_ENCRYPTED
16384 (0x4000)
Le fichier ou le répertoire est chiffré. Cela signifie pour un fichier, que toutes ses données sont chiffrées. Pour un répertoire, cela signifie que le chiffrement est la valeur par défaut pour les fichiers et sous-répertoires nouvellement créés. Pour plus d’informations, consultez Chiffrement de fichiers.

Cet indicateur n’a aucun effet si FILE_ATTRIBUTE_SYSTEM est également spécifié.

Cet indicateur n’est pas pris en charge sur les éditions Home, Home Premium, Starter ou ARM de Windows.

FILE_ATTRIBUTE_HIDDEN
2 (0x2)
Le fichier est masqué. Ne l’incluez pas dans une liste de répertoires ordinaire.
FILE_ATTRIBUTE_NORMAL
128 (0x80)
Le fichier n’a pas d’autres attributs définis. Cet attribut n’est valide que s’il est utilisé seul.
FILE_ATTRIBUTE_OFFLINE
4096 (0x1000)
Les données d’un fichier ne sont pas immédiatement disponibles. Cet attribut indique que les données de fichier sont physiquement déplacées vers le stockage hors connexion. Cet attribut est utilisé par le stockage à distance, le logiciel de gestion du stockage hiérarchique. Les applications ne doivent pas modifier arbitrairement cet attribut.
FILE_ATTRIBUTE_READONLY
1 (0x1)
Le fichier est en lecture seule. Les applications peuvent lire le fichier, mais ne peuvent pas l’écrire ou le supprimer.
FILE_ATTRIBUTE_SYSTEM
4 (0x4)
Le fichier fait partie ou est utilisé exclusivement par un système d’exploitation.
FILE_ATTRIBUTE_TEMPORARY
256 (0x100)
Le fichier est utilisé pour le stockage temporaire.

Pour plus d’informations, consultez la section Comportement de mise en cache de cette rubrique.

Indicateur Signification
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
Le fichier est en cours d’ouverture ou de création pour une opération de sauvegarde ou de restauration. Le système garantit que le processus appelant remplace les vérifications de sécurité des fichiers lorsque le processus dispose de privilèges SE_BACKUP_NAME et SE_RESTORE_NAME . Pour plus d’informations, consultez Modification des privilèges dans un jeton.

Vous devez définir cet indicateur pour obtenir un handle dans un répertoire. Un handle de répertoire peut être passé à certaines fonctions au lieu d’un handle de fichier. Pour plus d'informations, consultez la section Notes.

FILE_FLAG_DELETE_ON_CLOSE
0x04000000
Le fichier doit être supprimé immédiatement après la fermeture de tous ses handles, ce qui comprend le handle spécifié et tous les autres handles ouverts ou dupliqués.

S’il existe des handles ouverts existants dans un fichier, l’appel échoue, sauf s’ils ont tous été ouverts avec le mode de partage FILE_SHARE_DELETE .

Les demandes d’ouverture suivantes du fichier échouent, sauf si le mode de partage FILE_SHARE_DELETE est spécifié.

FILE_FLAG_NO_BUFFERING
0x20000000
Le fichier ou l’appareil est ouvert sans mise en cache système pour les lectures et les écritures de données. Cet indicateur n’affecte pas la mise en cache du disque dur ou les fichiers mappés à la mémoire.

Il existe des exigences strictes pour utiliser correctement les fichiers ouverts avec CreateFile à l’aide de l’indicateur FILE_FLAG_NO_BUFFERING . Pour plus d’informations, consultez Mise en mémoire tampon des fichiers.

FILE_FLAG_OPEN_NO_RECALL
0x00100000
Les données de fichier sont demandées, mais elles doivent continuer à se trouver dans le stockage distant. Il ne doit pas être renvoyé vers le stockage local. Cet indicateur est destiné aux systèmes de stockage distants.
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
Le traitement normal des points d’analyse ne se produira pas ; CreateFile tente d’ouvrir le point d’analyse. Lorsqu’un fichier est ouvert, un handle de fichier est retourné, que le filtre qui contrôle le point d’analyse soit opérationnel ou non.

Cet indicateur ne peut pas être utilisé avec l’indicateur CREATE_ALWAYS .

Si le fichier n’est pas un point d’analyse, cet indicateur est ignoré.

Pour plus d'informations, consultez la section Notes.

FILE_FLAG_OVERLAPPED
0x40000000
Le fichier ou l’appareil est en cours d’ouverture ou de création pour les E/S asynchrones.

Lorsque les opérations d’E/S suivantes sont terminées sur ce handle, l’événement spécifié dans la structure CHEVAUCHEMENT EST défini sur l’état signalé.

Si cet indicateur est spécifié, le fichier peut être utilisé pour des opérations de lecture et d’écriture simultanées.

Si cet indicateur n’est pas spécifié, les opérations d’E/S sont sérialisées, même si les appels aux fonctions de lecture et d’écriture spécifient une structure CHEVAUCHÉE .

Pour plus d’informations sur les considérations à prendre en compte lors de l’utilisation d’un handle de fichier créé avec cet indicateur, consultez la section Handles d’E/S synchrones et asynchrones de cette rubrique.

FILE_FLAG_POSIX_SEMANTICS
0x01000000
L’accès se produit selon les règles POSIX. Cela inclut l’autorisation de plusieurs fichiers avec des noms différents uniquement en cas, pour les systèmes de fichiers qui prennent en charge ce nom. Soyez prudent lorsque vous utilisez cette option, car les fichiers créés avec cet indicateur peuvent ne pas être accessibles par les applications écrites pour MS-DOS ou Windows 16 bits.
FILE_FLAG_RANDOM_ACCESS
0x10000000
L’accès est destiné à être aléatoire. Le système peut utiliser cette indication pour optimiser la mise en cache du fichier.

Cet indicateur n’a aucun effet si le système de fichiers ne prend pas en charge les E/S mises en cache et les FILE_FLAG_NO_BUFFERING.

Pour plus d’informations, consultez la section Comportement de mise en cache de cette rubrique.

FILE_FLAG_SESSION_AWARE
0x00800000
Le fichier ou l’appareil est en cours d’ouverture avec la reconnaissance de session. Si cet indicateur n’est pas spécifié, les appareils par session (par exemple, un appareil utilisant la redirection USB RemoteFX) ne peuvent pas être ouverts par les processus s’exécutant dans la session 0. Cet indicateur n’a aucun effet pour les appelants qui ne sont pas dans la session 0. Cet indicateur est pris en charge uniquement sur les éditions serveur de Windows.

Windows Server 2008 R2 et Windows Server 2008 : Cet indicateur n’est pas pris en charge avant Windows Server 2012.

FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
L’accès est destiné à être séquentiel du début à la fin. Le système peut utiliser cette indication pour optimiser la mise en cache du fichier.

Cet indicateur ne doit pas être utilisé si la lecture-behind (c’est-à-dire les analyses inversées) est utilisée.

Cet indicateur n’a aucun effet si le système de fichiers ne prend pas en charge les E/S mises en cache et les FILE_FLAG_NO_BUFFERING.

Pour plus d’informations, consultez la section Comportement de mise en cache de cette rubrique.

FILE_FLAG_WRITE_THROUGH
0x80000000
Les opérations d’écriture ne passeront par aucun cache intermédiaire, elles seront directement sur le disque.

Pour plus d’informations, consultez la section Comportement de mise en cache de cette rubrique.

Le paramètre dwFlagsAndAttributes peut également spécifier des informations SQOS. Pour plus d’informations, consultez Niveaux d’emprunt d’identité. Lorsque l’application appelante spécifie l’indicateur SECURITY_SQOS_PRESENT dans le cadre de dwFlagsAndAttributes, elle peut également contenir une ou plusieurs des valeurs suivantes.

Indicateur de sécurité Signification
SECURITY_ANONYMOUS
Emprunte l’identité d’un client au niveau de l’emprunt d’identité anonyme.
SECURITY_CONTEXT_TRACKING
Le mode de suivi de la sécurité est dynamique. Si cet indicateur n’est pas spécifié, le mode de suivi de la sécurité est statique.
SECURITY_DELEGATION
Emprunte l’identité d’un client au niveau de l’emprunt d’identité de délégation.
SECURITY_EFFECTIVE_ONLY
Seuls les aspects activés du contexte de sécurité du client sont disponibles pour le serveur. Si vous ne spécifiez pas cet indicateur, tous les aspects du contexte de sécurité du client sont disponibles.

Cela permet au client de limiter les groupes et les privilèges qu’un serveur peut utiliser lors de l’emprunt d’identité du client.

SECURITY_IDENTIFICATION
Emprunte l’identité d’un client au niveau de l’emprunt d’identité d’identification.
SECURITY_IMPERSONATION
Emprunt d’identité d’un client au niveau de l’emprunt d’identité. Il s’agit du comportement par défaut si aucun autre indicateur n’est spécifié avec l’indicateur SECURITY_SQOS_PRESENT .

[in, optional] hTemplateFile

Handle valide pour un fichier modèle avec le droit d’accès GENERIC_READ . Le fichier modèle fournit des attributs de fichier et des attributs étendus pour le fichier en cours de création.

Ce paramètre peut être NULL.

Lors de l’ouverture d’un fichier existant, CreateFile ignore ce paramètre.

Lors de l’ouverture d’un nouveau fichier chiffré, le fichier hérite de la liste de contrôle d’accès discrétionnaire de son répertoire parent. Pour plus d’informations, consultez Chiffrement de fichiers.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle ouvert pour le fichier, l’appareil, le canal nommé ou l’emplacement de messagerie spécifié.

Si la fonction échoue, la valeur de retour est INVALID_HANDLE_VALUE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

CreateFile a été développé à l’origine spécifiquement pour l’interaction avec les fichiers, mais a depuis été développé et amélioré pour inclure la plupart des autres types d’appareils et mécanismes d’E/S disponibles pour les développeurs Windows. Cette section tente de couvrir les différents problèmes que les développeurs peuvent rencontrer lors de l’utilisation de CreateFile dans différents contextes et avec différents types d’E/S. Le texte tente d’utiliser le fichier word uniquement lorsqu’il fait référence spécifiquement aux données stockées dans un fichier réel sur un système de fichiers. Toutefois, certaines utilisations de fichier peuvent faire référence plus généralement à un objet d’E/S qui prend en charge des mécanismes de type fichier. Cette utilisation libérale du terme fichier est particulièrement répandue dans les noms de constantes et les noms de paramètres en raison des raisons historiques mentionnées précédemment.

Lorsqu’une application a terminé d’utiliser le handle d’objet retourné par CreateFile, utilisez la fonction CloseHandle pour fermer le handle. Cela libère non seulement les ressources système, mais peut avoir une influence plus large sur des éléments tels que le partage du fichier ou de l’appareil et la validation des données sur le disque. Les spécificités sont indiquées dans cette rubrique, le cas échéant.

Windows Server 2003 et Windows XP : Une violation de partage se produit si une tentative d’ouverture d’un fichier ou d’un répertoire est effectuée pour suppression sur un ordinateur distant lorsque la valeur du paramètre dwDesiredAccess est l’indicateur d’accès DELETE (0x00010000) OR’ed avec tout autre indicateur d’accès, et que le fichier ou répertoire distant n’a pas été ouvert avec FILE_SHARE_DELETE. Pour éviter la violation de partage dans ce scénario, ouvrez le fichier ou le répertoire distant avec le droit d’accès DELETE uniquement, ou appelez DeleteFile sans ouvrir au préalable le fichier ou le répertoire pour suppression.

Certains systèmes de fichiers, tels que le système de fichiers NTFS, prennent en charge la compression ou le chiffrement des fichiers et répertoires individuels. Sur les volumes qui ont un système de fichiers monté avec cette prise en charge, un nouveau fichier hérite des attributs de compression et de chiffrement de son répertoire.

Vous ne pouvez pas utiliser CreateFile pour contrôler la compression, la décompression ou le déchiffrement d’un fichier ou d’un répertoire. Pour plus d’informations, consultez Création et ouverture de fichiers, Compression et décompression de fichiers et Chiffrement de fichiers.

Windows Server 2003 et Windows XP : À des fins de compatibilité descendante, CreateFile n’applique pas de règles d’héritage lorsque vous spécifiez un descripteur de sécurité dans lpSecurityAttributes. Pour prendre en charge l’héritage, les fonctions qui interrogent ultérieurement le descripteur de sécurité de ce fichier peuvent déterminer et signaler de manière heuristique que l’héritage est en vigueur. Pour plus d’informations, consultez Propagation automatique des AE hérités.

Comme indiqué précédemment, si le paramètre lpSecurityAttributes a la valeur NULL, le handle retourné par CreateFile ne peut pas être hérité par les processus enfants que votre application peut créer. Les informations suivantes concernant ce paramètre s’appliquent également :

  • Si la variable membre bInheritHandle n’est pas FALSE, ce qui est une valeur différente de zéro, le handle peut être hérité. Par conséquent, il est essentiel que ce membre de structure soit correctement initialisé sur FALSE si vous ne souhaitez pas que le handle soit héritable.
  • Les listes de contrôle d’accès (ACL) du descripteur de sécurité par défaut d’un fichier ou d’un répertoire sont héritées de son répertoire parent.
  • Le système de fichiers cible doit prendre en charge la sécurité sur les fichiers et les répertoires pour que le membre lpSecurityDescriptor ait un effet sur ceux-ci, ce qui peut être déterminé à l’aide de GetVolumeInformation.
Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.
Technologie Prise en charge
Protocole Server Message Block (SMB) 3.0 Oui
Basculement transparent SMB 3.0 (TFO) Voir les remarques
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) Voir les remarques
Système de fichiers du volume partagé de cluster (CsvFS) Oui
Système de fichiers résilient (ReFS) Oui

Notez que CreateFile avec la suppression de remplacement échoue s’il est effectué sur un fichier où il existe déjà un autre flux de données ouvert.

Comportement des liens symboliques

Si l’appel à cette fonction crée un fichier, il n’y a aucun changement de comportement. Tenez également compte des informations suivantes concernant FILE_FLAG_OPEN_REPARSE_POINT :
  • Si FILE_FLAG_OPEN_REPARSE_POINT est spécifié :
    • Si un fichier existant est ouvert et qu’il s’agit d’un lien symbolique, le descripteur retourné est un descripteur vers ce lien symbolique.
    • Si TRUNCATE_EXISTING ou FILE_FLAG_DELETE_ON_CLOSE sont spécifiés, le fichier affecté est un lien symbolique.
  • Si FILE_FLAG_OPEN_REPARSE_POINT n’est pas spécifié :
    • Si un fichier existant est ouvert et qu’il s’agit d’un lien symbolique, le descripteur retourné est un descripteur de la cible.
    • Si CREATE_ALWAYS, TRUNCATE_EXISTING ou FILE_FLAG_DELETE_ON_CLOSE sont spécifiés, le fichier affecté est la cible.

Comportement de mise en cache

Plusieurs des valeurs possibles pour le paramètre dwFlagsAndAttributes sont utilisées par CreateFile pour contrôler ou affecter la façon dont les données associées au handle sont mises en cache par le système. Il s'agit des éléments suivants :
  • FILE_FLAG_NO_BUFFERING
  • FILE_FLAG_RANDOM_ACCESS
  • FILE_FLAG_SEQUENTIAL_SCAN
  • FILE_FLAG_WRITE_THROUGH
  • FILE_ATTRIBUTE_TEMPORARY
Si aucun de ces indicateurs n’est spécifié, le système utilise un schéma de mise en cache à usage général par défaut. Sinon, la mise en cache système se comporte comme spécifié pour chaque indicateur.

Certains de ces indicateurs ne doivent pas être combinés. Par instance, la combinaison de FILE_FLAG_RANDOM_ACCESS avec FILE_FLAG_SEQUENTIAL_SCAN est un échec automatique.

La spécification de l’indicateur FILE_FLAG_SEQUENTIAL_SCAN peut augmenter les performances pour les applications qui lisent des fichiers volumineux à l’aide d’un accès séquentiel. Les gains de performances peuvent être encore plus notables pour les applications qui lisent des fichiers volumineux principalement de manière séquentielle, mais qui passent parfois à l’avant sur de petites plages d’octets. Si une application déplace le pointeur de fichier pour un accès aléatoire, il est probable que les performances de mise en cache optimales ne se produisent pas. Toutefois, le bon fonctionnement est toujours garanti.

Les indicateurs FILE_FLAG_WRITE_THROUGH et FILE_FLAG_NO_BUFFERING sont indépendants et peuvent être combinés.

Si FILE_FLAG_WRITE_THROUGH est utilisé mais que FILE_FLAG_NO_BUFFERING n’est pas également spécifié, de sorte que la mise en cache du système est en vigueur, les données sont écrites dans le cache système, mais vidées sur le disque sans délai.

Si FILE_FLAG_WRITE_THROUGH et FILE_FLAG_NO_BUFFERING sont tous deux spécifiés, de sorte que la mise en cache du système n’est pas appliquée, les données sont immédiatement vidées sur le disque sans passer par le cache système Windows. Le système d’exploitation demande également une écriture directe du cache matériel local du disque dur sur un support persistant.

Note Tout le matériel de disque dur ne prend pas en charge cette fonctionnalité d’écriture directe.
L’utilisation correcte de l’indicateur FILE_FLAG_NO_BUFFERING nécessite des considérations particulières relatives à l’application. Pour plus d’informations, consultez Mise en mémoire tampon des fichiers.

Une demande d’écriture directe via FILE_FLAG_WRITE_THROUGH également pour que NTFS vide toutes les modifications de métadonnées, telles qu’une mise à jour d’horodatage ou une opération de renommage, qui résultent du traitement de la demande. Pour cette raison, l’indicateur FILE_FLAG_WRITE_THROUGH est souvent utilisé avec l’indicateur FILE_FLAG_NO_BUFFERING en remplacement de l’appel de la fonction FlushFileBuffers après chaque écriture, ce qui peut entraîner des pénalités de performances inutiles. L’utilisation de ces indicateurs ensemble permet d’éviter ces pénalités. Pour obtenir des informations générales sur la mise en cache des fichiers et des métadonnées, consultez Mise en cache des fichiers.

Lorsque FILE_FLAG_NO_BUFFERING est combiné avec FILE_FLAG_OVERLAPPED, les indicateurs offrent des performances asynchrones maximales, car les E/S ne reposent pas sur les opérations synchrones du gestionnaire de mémoire. Toutefois, certaines opérations d’E/S prennent plus de temps, car les données ne sont pas conservées dans le cache. En outre, les métadonnées du fichier peuvent toujours être mises en cache (par exemple, lors de la création d’un fichier vide). Pour vous assurer que les métadonnées sont vidées sur le disque, utilisez la fonction FlushFileBuffers .

Si vous spécifiez l’attribut FILE_ATTRIBUTE_TEMPORARY , les systèmes de fichiers évitent d’écrire des données dans le stockage de masse si suffisamment de mémoire cache est disponible, car une application supprime un fichier temporaire après la fermeture d’un handle. Dans ce cas, le système peut complètement éviter d’écrire les données. Bien qu’il ne contrôle pas directement la mise en cache des données de la même façon que les indicateurs mentionnés précédemment, l’attribut FILE_ATTRIBUTE_TEMPORARY indique au système de conserver autant que possible dans le cache système sans écriture et peut donc être préoccupant pour certaines applications.

Fichiers

Si vous renommez ou supprimez un fichier, puis que vous le restaurez peu après, le système recherche dans le cache des informations de fichier à restaurer. Les informations mises en cache incluent leur paire de noms court/long et l’heure de création.

Si vous appelez CreateFile sur un fichier en attente de suppression à la suite d’un appel précédent à DeleteFile, la fonction échoue. Le système d’exploitation retarde la suppression du fichier jusqu’à ce que tous les handles du fichier soient fermés. GetLastError retourne ERROR_ACCESS_DENIED.

Le paramètre dwDesiredAccess peut être égal à zéro, ce qui permet à l’application d’interroger les attributs de fichier sans accéder au fichier si l’application s’exécute avec des paramètres de sécurité adéquats. Cela est utile pour tester l’existence d’un fichier sans l’ouvrir pour un accès en lecture et/ou en écriture, ou pour obtenir d’autres statistiques sur le fichier ou le répertoire. Consultez Obtention et définition d’informations sur le fichier et GetFileInformationByHandle.

Si CREATE_ALWAYS et FILE_ATTRIBUTE_NORMAL sont spécifiés, CreateFile échoue et définit la dernière erreur sur ERROR_ACCESS_DENIED si le fichier existe et a l’attribut FILE_ATTRIBUTE_HIDDEN ou FILE_ATTRIBUTE_SYSTEM . Pour éviter l’erreur, spécifiez les mêmes attributs que le fichier existant.

Lorsqu’une application crée un fichier sur un réseau, il est préférable d’utiliser GENERIC_READ | GENERIC_WRITE pour dwDesiredAccess plutôt que d’utiliser GENERIC_WRITE seule. Le code obtenu est plus rapide, car le redirecteur peut utiliser le gestionnaire de cache et envoyer moins de PME avec plus de données. Cette combinaison évite également un problème où l’écriture dans un fichier sur un réseau peut occasionnellement retourner ERROR_ACCESS_DENIED.

Pour plus d’informations, consultez Création et ouverture de fichiers.

Handles d’E/S synchrones et asynchrones

CreateFile permet de créer un handle de fichier ou d’appareil synchrone ou asynchrone. Un handle synchrone se comporte de telle sorte que les appels de fonction d’E/S utilisant ce handle soient bloqués jusqu’à ce qu’ils se terminent, tandis qu’un handle de fichier asynchrone permet au système de retourner immédiatement à partir des appels de fonction d’E/S, qu’ils ont terminé l’opération d’E/S ou non. Comme indiqué précédemment, ce comportement synchrone et asynchrone est déterminé en spécifiant FILE_FLAG_OVERLAPPED dans le paramètre dwFlagsAndAttributes . Il existe plusieurs complexités et pièges potentiels lors de l’utilisation d’E/S asynchrones ; Pour plus d’informations, consultez E/S synchrones et asynchrones.

Flux de fichiers

Sur les systèmes de fichiers NTFS, vous pouvez utiliser CreateFile pour créer des flux distincts dans un fichier. Pour plus d’informations, consultez Flux de fichiers.

Téléphonique

Une application ne peut pas créer de répertoire à l’aide de CreateFile. Par conséquent, seule la valeur OPEN_EXISTING est valide pour dwCreationDisposition pour ce cas d’usage. Pour créer un répertoire, l’application doit appeler CreateDirectory ou CreateDirectoryEx.

Pour ouvrir un répertoire à l’aide de CreateFile, spécifiez l’indicateur FILE_FLAG_BACKUP_SEMANTICS dans le cadre de dwFlagsAndAttributes. Les vérifications de sécurité appropriées s’appliquent toujours lorsque cet indicateur est utilisé sans privilèges SE_BACKUP_NAME et SE_RESTORE_NAME .

Lorsque vous utilisez CreateFile pour ouvrir un répertoire lors de la défragmentation d’un volume de système de fichiers FAT ou FAT32, ne spécifiez pas le droit d’accès MAXIMUM_ALLOWED . L’accès au répertoire est refusé si cette opération est effectuée. Spécifiez plutôt le droit d’accès GENERIC_READ .

Pour plus d’informations, consultez À propos de la gestion d’annuaires.

Disques physiques et volumes

L’accès direct au disque ou à un volume est limité.

Windows Server 2003 et Windows XP : L’accès direct au disque ou à un volume n’est pas limité de cette manière.

Vous pouvez utiliser la fonction CreateFile pour ouvrir un lecteur de disque physique ou un volume, qui retourne un handle de périphérique de stockage à accès direct (DASD) qui peut être utilisé avec la fonction DeviceIoControl . Cela vous permet d’accéder directement au disque ou au volume, par exemple les métadonnées de disque comme la table de partition. Toutefois, ce type d’accès expose également le lecteur de disque ou le volume à une perte de données potentielle, car une écriture incorrecte sur un disque à l’aide de ce mécanisme peut rendre son contenu inaccessible au système d’exploitation. Pour garantir l’intégrité des données, veillez à vous familiariser avec DeviceIoControl et comment les autres API se comportent différemment avec un handle d’accès direct par rapport à un handle de système de fichiers.

Les conditions suivantes doivent être remplies pour qu’un tel appel réussisse :

  • L’appelant doit disposer de privilèges administratifs. Pour plus d’informations, consultez Exécution avec des privilèges spéciaux.
  • Le paramètre dwCreationDisposition doit avoir l’indicateur OPEN_EXISTING .
  • Lors de l’ouverture d’un volume ou d’une disquette, le paramètre dwShareMode doit avoir l’indicateur FILE_SHARE_WRITE .
Note Le paramètre dwDesiredAccess peut être égal à zéro, ce qui permet à l’application d’interroger les attributs d’appareil sans accéder à un appareil. Cela est utile pour une application afin de déterminer la taille d’un lecteur de disquette et les formats qu’il prend en charge sans nécessiter de disquette dans un lecteur, pour instance. Il peut également être utilisé pour lire des statistiques sans nécessiter d’autorisation de lecture/écriture de données de niveau supérieur.
Lors de l’ouverture d’un lecteur physique x :, la chaîne lpFileName doit avoir la forme suivante : « \\.\PhysicalDriveX ». Les numéros de disque dur commencent à zéro. Le tableau suivant présente quelques exemples de chaînes de lecteur physique.
String Signification
« \\.\PhysicalDrive0 » Ouvre le premier lecteur physique.
« \\.\PhysicalDrive2 » Ouvre le troisième lecteur physique.

Pour obtenir l’identificateur de lecteur physique d’un volume, ouvrez un handle sur le volume et appelez la fonction DeviceIoControl avec IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Ce code de contrôle retourne le numéro de disque et le décalage pour chacune des extensions du volume ; un volume peut s’étendre sur plusieurs disques physiques.

Pour obtenir un exemple d’ouverture d’un lecteur physique, consultez Appel de DeviceIoControl.

Lors de l’ouverture d’un volume ou d’un lecteur multimédia amovible (par exemple, un lecteur de disquette ou un lecteur de mémoire flash), la chaîne lpFileName doit avoir la forme suivante : « \.\X : ». N’utilisez pas de barre oblique inverse de fin (\), qui indique le répertoire racine d’un lecteur. Le tableau suivant présente quelques exemples de chaînes de lecteur.

String Signification
« \\.\A : » Ouvre le lecteur de disquette A.
« \\.\C : » Ouvre le volume C :.
« \\.\C :\ » Ouvre le système de fichiers du volume C :.

Vous pouvez également ouvrir un volume en faisant référence à son nom de volume. Pour plus d’informations, consultez Nommage d’un volume.

Un volume contient un ou plusieurs systèmes de fichiers montés. Les handles de volume peuvent être ouverts en tant que non mis en cache à la discrétion du système de fichiers particulier, même lorsque l’option non mise en cache n’est pas spécifiée dans CreateFile. Vous devez supposer que tous les systèmes de fichiers Microsoft ouvrent les handles de volume comme non mis en cache. Les restrictions sur les E/S non mises en cache pour les fichiers s’appliquent également aux volumes.

Un système de fichiers peut nécessiter ou non l’alignement de la mémoire tampon même si les données ne sont pas mises en cache. Toutefois, si l’option non mise en cache est spécifiée lors de l’ouverture d’un volume, l’alignement de la mémoire tampon est appliqué quel que soit le système de fichiers sur le volume. Il est recommandé sur tous les systèmes de fichiers d’ouvrir des handles de volume comme non mis en cache et de suivre les restrictions d’E/S non mises en cache.

Note Pour lire ou écrire dans les derniers secteurs du volume, vous devez appeler DeviceIoControl et spécifier FSCTL_ALLOW_EXTENDED_DASD_IO. Cela indique au pilote du système de fichiers de ne pas effectuer de vérifications de limites d’E/S sur les appels de lecture ou d’écriture de partition. Au lieu de cela, les vérifications de limites sont effectuées par le pilote de périphérique.

Changer l’appareil

Les codes de contrôle IOCTL_CHANGER_* pour DeviceIoControl acceptent un handle pour un appareil changeur. Pour ouvrir un appareil changeur, utilisez un nom de fichier au format suivant : « \\.\Changerx », où x est un nombre qui indique l’appareil à ouvrir, en commençant par zéro. Pour ouvrir l’appareil changeur zéro dans une application écrite en C ou C++, utilisez le nom de fichier suivant : « \\\\.\Changer0 ».

Lecteurs de bande

Vous pouvez ouvrir des lecteurs de bande à l’aide d’un nom de fichier au format suivant : « \\.\TAPEx », où x est un nombre qui indique le lecteur à ouvrir, en commençant par zéro. Pour ouvrir le lecteur de bande zéro dans une application écrite en C ou C++, utilisez le nom de fichier suivant : « \\\\.\TAPE0 ».

Pour plus d’informations, consultez Sauvegarde.

Ressources de communication

La fonction CreateFile peut créer un handle pour une ressource de communication, telle que le port série COM1. Pour les ressources de communication, le paramètre dwCreationDisposition doit être OPEN_EXISTING, le paramètre dwShareMode doit être égal à zéro (accès exclusif) et le paramètre hTemplateFile doit avoir la valeur NULL. L’accès en lecture, en écriture ou en lecture/écriture peut être spécifié, et le handle peut être ouvert pour les E/S qui se chevauchent.

Pour spécifier un numéro de port COM supérieur à 9, utilisez la syntaxe suivante : « \.\COM10 ». Cette syntaxe fonctionne pour tous les numéros de port et le matériel qui permet de spécifier des numéros de port COM.

Pour plus d’informations sur les communications, consultez Communications.

Consoles

La fonction CreateFile peut créer un handle pour l’entrée de console (CONIN$). Si le processus a un handle ouvert à la suite d’un héritage ou d’une duplication, il peut également créer un handle dans la mémoire tampon d’écran active (CONOUT$). Le processus appelant doit être attaché à une console héritée ou à une console allouée par la fonction AllocConsole . Pour les handles de console, définissez les paramètres CreateFile comme suit.
Paramètres Valeur
lpFileName Utilisez la valeur CONIN$ pour spécifier l’entrée de console.

Utilisez la valeur CONOUT$ pour spécifier la sortie de console.

CONIN$ obtient un handle vers la mémoire tampon d’entrée de console, même si la fonction SetStdHandle redirige le handle d’entrée standard. Pour obtenir le handle d’entrée standard, utilisez la fonction GetStdHandle .

CONOUT$ obtient un handle vers la mémoire tampon d’écran active, même si SetStdHandle redirige le handle de sortie standard. Pour obtenir le handle de sortie standard, utilisez GetStdHandle.

dwDesiredAccess GENERIC_READ | GENERIC_WRITE est préférable, mais l’une ou l’autre peut limiter l’accès.
dwShareMode Lors de l’ouverture de CONIN$, spécifiez FILE_SHARE_READ. Lors de l’ouverture de CONOUT$, spécifiez FILE_SHARE_WRITE.

Si le processus appelant hérite de la console, ou si un processus enfant doit pouvoir accéder à la console, ce paramètre doit être FILE_SHARE_READ | FILE_SHARE_WRITE.

lpSecurityAttributes Si vous souhaitez que la console soit héritée, le membre bInheritHandle de la structure SECURITY_ATTRIBUTES doit avoir la valeur TRUE.
dwCreationDisposition Vous devez spécifier OPEN_EXISTING lors de l’utilisation de CreateFile pour ouvrir la console.
dwFlagsAndAttributes Ignoré.
hTemplateFile Ignoré.

Le tableau suivant présente les différents paramètres de dwDesiredAccess et lpFileName.

lpFileName dwDesiredAccess Résultats
« CON » GENERIC_READ Ouvre la console pour l’entrée.
« CON » GENERIC_WRITE Ouvre la console pour la sortie.
« CON » GENERIC_READ | GENERIC_WRITE Provoque l’échec de CreateFile ; GetLastError retourne ERROR_FILE_NOT_FOUND.

Mailslots

Si CreateFile ouvre l’extrémité cliente d’un maillot, la fonction retourne INVALID_HANDLE_VALUE si le client maillot tente d’ouvrir un maillot local avant que le serveur maillot ne l’ait créé avec la fonction CreateMailSlot .

Pour plus d’informations, consultez Mailslots.

Tuyaux

Si CreateFile ouvre l’extrémité cliente d’un canal nommé, la fonction utilise n’importe quelle instance du canal nommé qui est à l’état d’écoute. Le processus d’ouverture peut dupliquer le handle autant de fois que nécessaire, mais une fois ouvert, le canal nommé instance ne peut pas être ouvert par un autre client. L’accès spécifié lors de l’ouverture d’un canal doit être compatible avec l’accès spécifié dans le paramètre dwOpenMode de la fonction CreateNamedPipe .

Si la fonction CreateNamedPipe n’a pas été correctement appelée sur le serveur avant cette opération, il n’existe pas de canal et CreateFile échoue avec ERROR_FILE_NOT_FOUND.

S’il existe au moins un canal actif instance mais qu’aucun canal d’écouteur n’est disponible sur le serveur, ce qui signifie que toutes les instances de canal sont actuellement connectées, CreateFile échoue avec ERROR_PIPE_BUSY.

Pour plus d’informations, consultez Canaux.

Exemples

Les exemples d’opérations de fichier sont présentés dans les rubriques suivantes :

Les E/S d’appareil physique sont illustrées dans les rubriques suivantes : Un exemple d’utilisation de canaux nommés se trouve dans Client de canal nommé.

L’utilisation d’un maillot s’affiche dans Écriture dans un maillot.

Vous trouverez un extrait de code de sauvegarde sur bande dans Création d’une application de sauvegarde.

Notes

L’en-tête fileapi.h définit CreateFile en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
Plateforme cible Windows
En-tête fileapi.h (inclure Windows.h)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi

À propos de la gestion des répertoires

À propos de la gestion des volumes

Sauvegarde

CloseHandle

Communications

CreateDirectory

CreateDirectoryEx

CreateFileTransacted

CreateMailSlot

CreateNamedPipe

Création, suppression et maintenance des fichiers

DeleteFile

Contrôle d’entrée et de sortie de l’appareil (IOCTL)

DeviceIoControl

Compression et décompression de fichiers

Chiffrement de fichiers

Fonctions de gestion des fichiers

Sécurité du fichier et droits d’accès

Flux de fichiers

Fonctions

Obtenir la dernière erreur

Ports d’achèvement des E/S

Concepts d’E/S

Mailslots

Obtention et définition des informations sur un fichier

Rubriques de présentation

Canaux

ReadFile

ReadFileEx

Exécution avec des privilèges spéciaux

SetFileAttributes

WriteFile

WriteFileEx