Fonction IoCreateFile (wdm.h)

Article
08/08/2023

La routine IoCreateFile provoque la création d’un fichier ou d’un répertoire, ou ouvre un fichier, un appareil, un répertoire ou un volume existant, ce qui donne à l’appelant un handle pour l’objet fichier.

Syntaxe

NTSTATUS IoCreateFile(
  [out]          PHANDLE            FileHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in, optional] PLARGE_INTEGER     AllocationSize,
  [in]           ULONG              FileAttributes,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              Disposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           CREATE_FILE_TYPE   CreateFileType,
  [in, optional] PVOID              InternalParameters,
  [in]           ULONG              Options
);

Paramètres

[out] FileHandle

Pointeur vers une variable qui reçoit le handle de fichier si l’appel réussit. Le pilote doit fermer la poignée avec ZwClose une fois que la poignée n’est plus utilisée.

[in] DesiredAccess

Masque de bits d’indicateurs spécifiant le type d’accès au fichier ou au répertoire requis par l’appelant. Consultez le paramètre DesiredAccessd’IoCreateFileEx pour plus d’informations sur ce paramètre et pour obtenir la liste des valeurs d’indicateur.

[in] ObjectAttributes

Pointeur vers une structure de OBJECT_ATTRIBUTES opaque déjà initialisée avec InitializeObjectAttributes. Pour plus d’informations et pour obtenir une description de chaque membre de structure, consultez le paramètre ObjectAttributesd’IoCreateFileEx .

[out] IoStatusBlock

Pointeur vers une structure IO_STATUS_BLOCK qui reçoit l’achèvement final status et des informations sur l’opération demandée. Consultez le paramètre IoStatusBlockd’IoCreateFileEx.

[in, optional] AllocationSize

Spécifie éventuellement la taille d’allocation initiale en octets pour le fichier. Une valeur différente de zéro n’a aucun effet, sauf si le fichier est en cours de création, de remplacement ou de remplacement.

[in] FileAttributes

Les attributs explicitement spécifiés sont appliqués uniquement lorsque le fichier est créé, remplacé ou, dans certains cas, remplacé. Par défaut, cette valeur est FILE_ATTRIBUTE_NORMAL, qui peut être remplacée par une combinaison ORed d’un ou plusieurs indicateurs FILE_ATTRIBUTE_XXX , qui sont définis dans Wdm.h. Pour obtenir la liste des indicateurs qui peuvent être utilisés avec IoCreateFile, consultez CreateFile.

[in] ShareAccess

Spécifie le type d’accès de partage au fichier dont l’appelant a besoin, comme zéro ou un, ou une combinaison des indicateurs. Pour plus d’informations et pour obtenir la liste des indicateurs, consultez le paramètre ShareAccessd’IoCreateFileEx .

[in] Disposition

Spécifie une valeur qui détermine l’action à entreprendre, selon que le fichier existe déjà. Pour obtenir la liste des valeurs possibles, consultez le paramètre Dispositiond’IoCreateFileEx .

[in] CreateOptions

Spécifie les options à appliquer lors de la création ou de l’ouverture du fichier. Ce paramètre est une combinaison compatible des indicateurs répertoriés et décrits dans le paramètre CreateOptionsd’IoCreateFileEx.

[in, optional] EaBuffer

Pour les pilotes d’appareil et intermédiaires, ce paramètre doit être un pointeur NULL .

[in] EaLength

Pour les pilotes d’appareil et intermédiaires, ce paramètre doit être égal à zéro.

[in] CreateFileType

Les pilotes doivent définir ce paramètre sur CreateFileTypeNone.

[in, optional] InternalParameters

Les pilotes doivent définir ce paramètre sur NULL.

[in] Options

Spécifie les options à utiliser lors de la création de la demande de création. Consultez le paramètre Optionsd’IoCreateFileEx pour obtenir la liste des options possibles.

Valeur retournée

IoCreateFile retourne STATUS_SUCCESS ou une status d’erreur appropriée. Valeur NTSTATUS. Consultez la section Return Value (Valeur de retour) de IoCreateFileEx pour obtenir la liste des codes de retour possibles.

Remarques

La routine IoCreateFileEx est similaire à la routine IoCreateFile , mais fournit des fonctionnalités supérieures à la routine IoCreateFile , y compris l’accès à des paramètres de création supplémentaires (ECP), des objets d’appareil et des informations de transaction.

Le handle obtenu par IoCreateFile peut être utilisé par les appels suivants pour manipuler des données dans le fichier ou l’état ou les attributs de l’objet fichier.

Il existe deux autres façons de spécifier le nom du fichier à créer ou à ouvrir avec IoCreateFile :

En tant que chemin d’accès complet, fourni dans le membre ObjectName de l’entrée ObjectAttributes
En tant que chemin d’accès relatif au fichier de répertoire représenté par le handle dans le membre RootDirectory de l’entrée ObjectAttributes

Certains indicateurs DesiredAccess et combinaisons d’indicateurs ont les effets suivants :

Pour qu’un appelant synchronise une fin d’E/S en attendant le FileHandle retourné, l’indicateur SYNCHRONIZE doit être défini. Sinon, un appelant qui est un périphérique ou un pilote intermédiaire doit synchroniser une fin d’E/S à l’aide d’un objet d’événement.
Si seuls les indicateurs FILE_APPEND_DATA et SYNCHRONIZE sont définis, l’appelant peut écrire uniquement à la fin du fichier, et toutes les informations de décalage sur les écritures dans le fichier sont ignorées. Toutefois, le fichier est automatiquement étendu si nécessaire pour ce type d’opération d’écriture.
La définition de l’indicateur FILE_WRITE_DATA pour un fichier permet également aux écritures au-delà de la fin du fichier de se produire. Le fichier est également automatiquement étendu pour ce type d’écriture.
Si seuls les indicateurs FILE_EXECUTE et SYNCHRONIZE sont définis, l’appelant ne peut pas lire ou écrire directement des données dans le fichier à l’aide du FileHandle retourné : autrement dit, toutes les opérations sur le fichier se produisent via le pagineur système en réponse aux instructions et aux accès aux données. Les pilotes d’appareil et intermédiaires ne doivent pas définir l’indicateur FILE_EXECUTE dans DesiredAccess.

Le paramètre ShareAccess détermine si des threads distincts peuvent accéder au même fichier, éventuellement simultanément. À condition que les deux ouvreurs de fichiers aient le privilège d’accéder à un fichier de la manière spécifiée, le fichier peut être ouvert et partagé avec succès. Si l’appelant d’origine d’IoCreateFile ne spécifie pas FILE_SHARE_READ, FILE_SHARE_WRITE ou FILE_SHARE_DELETE, aucune autre opération ouverte ne peut être effectuée sur le fichier : autrement dit, l’appelant d’origine reçoit un accès exclusif au fichier.

Pour qu’un fichier partagé soit correctement ouvert, l’accès souhaité demandé au fichier doit être compatible avec les spécifications DesiredAccess et ShareAccess de tous les ouvertures précédentes qui n’ont pas encore été publiées avec ZwClose. Autrement dit, le DesiredAccess spécifié dans IoCreateFile pour un fichier donné ne doit pas entrer en conflit avec les accès que les autres ouvreurs du fichier ont refusés.

La valeur Disposition FILE_SUPERSEDE nécessite que l’appelant dispose d’un accès DELETE à un objet de fichier existant. Si c’est le cas, un appel réussi à IoCreateFile avec FILE_SUPERSEDE sur un fichier existant supprime ce fichier, puis le recrée. Cela implique que, si le fichier a déjà été ouvert par un autre thread, il a ouvert le fichier en spécifiant un paramètre ShareAccessavec l’indicateur FILE_SHARE_DELETE défini. Notez que ce type de disposition est cohérent avec le style POSIX de remplacement des fichiers.

Les valeurs Disposition FILE_OVERWRITE_IF et FILE_SUPERSEDE sont similaires. Si IoCreateFile est appelé avec un fichier existant et que l’une de ces valeurs de disposition , le fichier est remplacé.

Le remplacement d’un fichier équivaut sémantiquement à une opération de remplacement, à l’exception des éléments suivants :

L’appelant doit disposer d’un accès en écriture au fichier, plutôt que de supprimer l’accès. Cela implique que, si le fichier a déjà été ouvert par un autre thread, il a ouvert le fichier avec l’indicateur FILE_SHARE_WRITE défini dans l’entrée ShareAccess.
Les attributs de fichier spécifiés sont logiquement ORed avec ceux déjà présents dans le fichier. Cela implique que, si le fichier a déjà été ouvert par un autre thread, un appelant suivant d’IoCreateFile ne peut pas désactiver les indicateurs FileAttributes existants, mais peut activer des indicateurs supplémentaires pour le même fichier.

La valeur de FILE_DIRECTORY_FILE CreateOptions spécifie que le fichier à créer ou à ouvrir est un fichier de répertoire. Lorsqu’un fichier de répertoire est créé, le système de fichiers crée une structure appropriée sur le disque pour représenter un répertoire vide pour la structure sur disque de ce système de fichiers particulier. Si cette option a été spécifiée et que le fichier donné à ouvrir n’est pas un fichier de répertoire, ou si l’appelant a spécifié une valeur CreateOptions ou Disposition incohérente, l’appel à IoCreateFile échoue.

L’indicateur CreateOptions FILE_NO_INTERMEDIATE_BUFFERING empêche le système de fichiers d’effectuer une mise en mémoire tampon intermédiaire pour le compte de l’appelant. La spécification de cette valeur place certaines restrictions sur les paramètres de l’appelant pour les routines de fichier ZwXxx, notamment les suivantes :

Tout ByteOffset facultatif passé à ZwReadFile ou ZwWriteFile doit faire partie intégrante de la taille du secteur.
La longueur passée à ZwReadFile ou ZwWriteFile doit faire partie intégrante de la taille du secteur. Notez que la spécification d’une opération de lecture dans une mémoire tampon dont la longueur correspond exactement à la taille du secteur peut entraîner le transfert d’un nombre inférieur d’octets significatifs vers cette mémoire tampon si la fin du fichier a été atteinte pendant le transfert.
Les mémoires tampons doivent être alignées conformément à l’exigence d’alignement de l’appareil sous-jacent. Ces informations peuvent être obtenues en appelant IoCreateFile pour obtenir un handle pour l’objet de fichier qui représente l’appareil physique, puis en appelant ZwQueryInformationFile avec ce handle. Pour obtenir la liste des valeurs système FILE_XXX_ALIGNMENT, consultez DEVICE_OBJECT.
Les appels à ZwSetInformationFile avec le paramètre FileInformationClass défini sur FilePositionInformationInformation doivent spécifier un décalage qui fait partie intégrante de la taille du secteur.

Les FILE_SYNCHRONOUS_IO_ALERT et FILE_SYNCHRONOUS_IO_NONALERT CreateOptions , qui s’excluent mutuellement comme le suggèrent leurs noms, spécifient que toutes les opérations d’E/S sur le fichier doivent être synchrones tant qu’elles se produisent via l’objet file auquel fait référence le FileHandle retourné. Toutes les E/S d’un tel fichier sont sérialisées sur tous les threads à l’aide du handle retourné. Avec l’un de ces CreateOptions, l’indicateur DesiredAccess SYNCHRONIZE doit être défini pour que le gestionnaire d’E/S utilise l’objet file comme objet de synchronisation. Avec l’un de ces createOptions définis, le gestionnaire d’E/S conserve le « contexte de position de fichier » pour l’objet de fichier, un décalage de position de fichier actuel interne. Ce décalage peut être utilisé dans les appels à ZwReadFile et ZwWriteFile. Sa position peut également être interrogée ou définie avec ZwQueryInformationFile et ZwSetInformationFile.

Si l’indicateur CreateOptions FILE_OPEN_REPARSE_POINT n’est pas spécifié et qu’IoCreateFile tente d’ouvrir un fichier avec un point d’analyse, le traitement normal du point d’analyse se produit pour le fichier. Si, en revanche, l’indicateur FILE_OPEN_REPARSE_POINT est spécifié, le traitement normal de l’analyse ne se produit pas et IoCreateFile tente d’ouvrir directement le fichier de point d’analyse. Dans les deux cas, si l’opération d’ouverture a réussi, IoCreateFile retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. IoCreateFile ne retourne jamais STATUS_REPARSE.

L’indicateur CreateOptions FILE_OPEN_REQUIRING_OPLOCK élimine le délai entre l’ouverture du fichier et la demande d’un oplock qui pourrait potentiellement permettre à un tiers d’ouvrir le fichier et d’obtenir une violation de partage. Une application peut utiliser l’indicateur FILE_OPEN_REQUIRING_OPLOCK sur IoCreateFile , puis demander n’importe quel oplock. Cela garantit qu’un propriétaire oplock sera averti de toute demande ouverte ultérieure qui provoque une violation de partage.

Dans Windows 7, si d’autres handles existent sur le fichier lorsqu’une application utilise l’indicateur FILE_OPEN_REQUIRING_OPLOCK, l’opération de création échoue avec STATUS_OPLOCK_NOT_GRANTED. Cette restriction n’existe plus à partir de Windows 8.

Si cette opération de création interrompt un blocage d’opération qui existe déjà sur le fichier, la définition de l’indicateur FILE_OPEN_REQUIRING_OPLOCK entraîne l’échec de l’opération de création avec STATUS_CANNOT_BREAK_OPLOCK. L’oplock existant ne sera pas rompu par cette opération de création.

Une application qui utilise l’indicateur FILE_OPEN_REQUIRING_OPLOCK doit demander un oplock une fois cet appel réussi, sinon toutes les tentatives suivantes d’ouverture du fichier seront bloquées sans le bénéfice d’un traitement oplock normal. De même, si cet appel réussit mais que la demande oplock suivante échoue, une application qui utilise cet indicateur doit fermer son handle après avoir détecté l’échec de la demande d’oplock.

L’indicateur FILE_OPEN_REQUIRING_OPLOCK est disponible dans Windows 7, Windows Server 2008 R2 et les versions ultérieures de Windows. Les systèmes de fichiers Microsoft qui implémentent cet indicateur dans Windows 7 sont NTFS, FAT et exFAT.

L’indicateur CreateOptions , FILE_RESERVE_OPFILTER, permet à une application de demander un oplock de niveau 1, par lot ou de filtre pour empêcher d’autres applications d’obtenir des violations de partage. Toutefois, FILE_RESERVE_OPFILTER n’est utile que pour les oplocks de filtre. Pour l’utiliser, vous devez suivre les étapes suivantes :

Émettre une demande de création avec CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess de FILE_READ_ATTRIBUTES exactement et ShareAccess d’exactement FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- S’il existe déjà des handles ouverts, la demande de création échoue avec STATUS_OPLOCK_NOT_GRANTED et le verrouillage d’opération suivant échoue également.
- Si vous ouvrez avec plus d’accès ou moins de partage, cela entraîne également un échec de STATUS_OPLOCK_NOT_GRANTED.
Si la demande de création réussit, demandez un oplock.
Ouvrez un autre handle dans le fichier pour effectuer des E/S.

L’étape 3 rend cela pratique uniquement pour les verrous de filtre. Le handle ouvert à l’étape 3 peut avoir un DesiredAccess qui contient un maximum de FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL et n’interrompez toujours pas un blocage de filtre. Toutefois, tout DesiredAccess supérieur à FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE interrompt un oplock de niveau 1 ou par lot et rend l’indicateur de FILE_RESERVE_OPFILTER inutile pour ces types d’oplock.

L’indicateur Options IO_NO_PARAMETER_CHECKING peut être utile si un pilote émet une demande de création en mode noyau pour le compte d’une opération lancée par une application en mode utilisateur. Étant donné que la demande se produit dans un contexte en mode utilisateur, le gestionnaire d’E/S, par défaut, sonde les valeurs de paramètre fournies, ce qui peut entraîner une violation d’accès si les paramètres sont des adresses en mode noyau. Cet indicateur permet à l’appelant de remplacer ce comportement par défaut et d’éviter la violation d’accès.

Pour les demandes de création provenant du mode utilisateur, si le pilote définit à la fois IO_NO_PARAMETER_CHECKING et IO_FORCE_ACCESS_CHECK dans le paramètre Optionsd’IoCreateFile , il doit également définir OBJ_FORCE_ACCESS_CHECK dans le paramètre ObjectAttributes . Pour plus d’informations sur cet indicateur, consultez le membre Attributs de OBJECT_ATTRIBUTES.

NTFS est le seul système de fichiers Microsoft qui implémente FILE_RESERVE_OPFILTER.

Les routines de pilote qui s’exécutent dans un contexte de processus autre que celui du processus système doivent définir l’attribut OBJ_KERNEL_HANDLE pour le paramètre ObjectAttributesd’IoCreateFile. Cela limite l’utilisation du handle retourné par IoCreateFile aux processus exécutés uniquement en mode noyau. Sinon, le handle est accessible par le processus dans le contexte dans lequel le pilote est en cours d’exécution. Les pilotes peuvent appeler InitializeObjectAttributes pour définir l’attribut OBJ_KERNEL_HANDLE comme suit.

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)