ZwCreateFile, fonction (wdm.h)

La routine ZwCreateFile crée un fichier ou ouvre un fichier existant.

Syntaxe

NTSYSAPI NTSTATUS ZwCreateFile(
  [out]          PHANDLE            FileHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in, optional] PLARGE_INTEGER     AllocationSize,
  [in]           ULONG              FileAttributes,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Paramètres

[out] FileHandle

Pointeur vers une variable HANDLE qui reçoit un handle pour le fichier.

[in] DesiredAccess

Spécifie une valeur ACCESS_MASK qui détermine l’accès demandé à l’objet . En plus des droits d’accès définis pour tous les types d’objets, l’appelant peut spécifier l’un des droits d’accès suivants, qui sont spécifiques aux fichiers.

Ne spécifiez pas FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA ou FILE_EXECUTE lorsque vous créez ou ouvrez un répertoire.

L’appelant peut uniquement spécifier un droit d’accès générique, GENERIC_XXX, pour un fichier, et non un répertoire. Les droits d’accès génériques correspondent à des droits d’accès spécifiques, comme indiqué dans le tableau suivant.

Par exemple, si vous spécifiez GENERIC_READ pour un objet fichier, la routine mappe cette valeur au masque de bits FILE_GENERIC_READ des droits d’accès spécifiques. Dans le tableau précédent, les droits d’accès spécifiques répertoriés pour GENERIC_READ correspondent aux indicateurs d’accès contenus dans le masque de bits FILE_GENERIC_READ.

Si le fichier est en fait un répertoire, l’appelant peut également spécifier les droits d’accès génériques suivants.

Pour plus d’informations sur les droits d’accès, consultez ACCESS_MASK.

[in] ObjectAttributes

Pointeur vers une structure OBJECT_ATTRIBUTES qui spécifie le nom de l’objet et d’autres attributs. Utilisez InitializeObjectAttributes pour initialiser cette structure. Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit définir l’attribut OBJ_KERNEL_HANDLE lorsqu’il appelle InitializeObjectAttributes.

[out] IoStatusBlock

Pointeur vers une structure de IO_STATUS_BLOCK qui reçoit la status d’achèvement finale et d’autres informations sur l’opération demandée. En particulier, le membre Information reçoit l’une des valeurs suivantes :

• FILE_CREATED

• FILE_OPENED

• FILE_OVERWRITTEN

• FILE_SUPERSEDED

• FILE_EXISTS

• FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Pointeur vers un LARGE_INTEGER qui contient la taille d’allocation initiale, en octets, pour un fichier créé ou remplacé. Si AllocationSize a la valeur NULL, aucune taille d’allocation n’est spécifiée. Si aucun fichier n’est créé ou remplacé, AllocationSize est ignoré.

[in] FileAttributes

Spécifie un ou plusieurs indicateurs FILE_ATTRIBUTE_XXX , qui représentent les attributs de fichier à définir si vous créez ou remplacez un fichier. L’appelant spécifie généralement FILE_ATTRIBUTE_NORMAL, ce qui définit les attributs par défaut. Pour obtenir la liste des indicateurs FILE_ATTRIBUTE_XXX valides, consultez la routine CreateFile . Si aucun fichier n’est créé ou remplacé, FileAttributes est ignoré.

[in] ShareAccess

Type d’accès au partage, qui est spécifié comme zéro ou toute combinaison des indicateurs suivants.

Les pilotes de périphérique et intermédiaires définissent généralement ShareAccess sur zéro, ce qui donne à l’appelant un accès exclusif au fichier ouvert.

[in] CreateDisposition

Spécifie l’action à effectuer si le fichier existe ou n’existe pas. CreateDisposition peut être l’une des valeurs du tableau suivant.

[in] CreateOptions

Spécifie les options à appliquer lorsque le pilote crée ou ouvre le fichier. Utilisez un ou plusieurs des indicateurs dans le tableau suivant.

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

Valeur retournée

ZwCreateFile retourne STATUS_SUCCESS sur la réussite ou un code d’erreur NTSTATUS approprié en cas d’échec. Dans ce dernier cas, l’appelant peut déterminer la cause de la défaillance en vérifiant le paramètre IoStatusBlock .

ZwCreateFile peut renvoyer STATUS_FILE_LOCK_CONFLICT comme valeur de retour ou dans le membre Status de la structure IO_STATUS_BLOCK vers laquelle pointe le paramètre IoStatusBlock . Cela se produit uniquement si le fichier journal NTFS est plein et qu’une erreur se produit alors que ZwCreateFile tente de gérer cette situation.

Remarques

ZwCreateFile fournit un handle que l’appelant peut utiliser pour manipuler les données d’un fichier ou l’état et les attributs de l’objet fichier. Pour plus d’informations, consultez Utilisation de fichiers dans un pilote.

Une fois que le handle pointé par FileHandle n’est plus utilisé, le pilote doit appeler ZwClose pour le fermer.

Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit s’assurer que tous les handles qu’il crée sont des handles privés. Sinon, le handle est accessible par le processus dans le contexte dans lequel le pilote est en cours d’exécution. Pour plus d’informations, consultez Handles d’objet.

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

1. En tant que chemin d’accès complet, fourni dans le membre ObjectName de l’entrée ObjectAttributes.

2. 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.

La définition de certains indicateurs dans le paramètre DesiredAccess entraîne 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 complétion d’E/S à l’aide d’un objet d’événement.

• Si l’appelant définit uniquement les indicateurs FILE_APPEND_DATA et SYNCHRONIZE, il peut écrire uniquement à la fin du fichier, et toutes les informations de décalage sur les opérations d’écriture dans le fichier sont ignorées. Le fichier est automatiquement étendu si nécessaire pour ce type d’opération.

• La définition de l’indicateur FILE_WRITE_DATA pour un fichier permet également à l’appelant d’écrire au-delà de la fin du fichier. Là encore, le fichier est automatiquement étendu si nécessaire.

• Si l’appelant définit uniquement les indicateurs FILE_EXECUTE et SYNCHRONIZE, il 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 opérations d’instruction et d’accès aux données. Les pilotes de périphérique et intermédiaire ne doivent pas définir l’indicateur FILE_EXECUTE.

Le paramètre ShareAccess détermine si des threads distincts peuvent accéder au même fichier, éventuellement simultanément. À condition que les deux appelants disposent des privilèges d’accès appropriés, le fichier peut être correctement ouvert et partagé. Si l’appelant d’origine de ZwCreateFile ne spécifie pas FILE_SHARE_READ, FILE_SHARE_WRITE ou FILE_SHARE_DELETE, aucun autre appelant ne peut ouvrir le fichier, c’est-à-dire qu’un accès exclusif est accordé à l’appelant d’origine.

Pour ouvrir un fichier partagé, les indicateurs DesiredAccess doivent être compatibles avec les indicateurs DesiredAccess et ShareAccess de toutes les opérations d’ouverture précédentes qui n’ont pas encore été publiées via . Autrement dit, le DesiredAccess spécifié à ZwCreateFile pour un fichier donné ne doit pas entrer en conflit avec les accès que d’autres ouvreurs du fichier ont refusés.

La valeur CreateDisposition 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 à ZwCreateFile 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 ShareAccess avec 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 CreateDisposition FILE_OVERWRITE_IF et FILE_SUPERSEDE sont similaires. Si ZwCreateFile est appelé avec un fichier existant et l’une de ces valeurs CreateDisposition , 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 avoir un accès en écriture au fichier, au lieu 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 de ZwCreateFile ne peut pas désactiver les indicateurs FileAttributes existants, mais peut activer des indicateurs supplémentaires pour le même fichier.

La valeur FILE_DIRECTORY_FILE CreateOptions spécifie que le fichier à créer ou ouvrir est un 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 CreateDisposition incohérente, l’appel à ZwCreateFile échoue.

L’indicateur FILE_NO_INTERMEDIATE_BUFFERING CreateOptions 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 cet indicateur place les restrictions suivantes sur les paramètres de l’appelant pour d’autres routines ZwXxxFile :

• Tout ByteOffset facultatif passé à ZwReadFile ou ZwWriteFile doit être un multiple de la taille du secteur.

• La longueur transmise à ZwReadFile ou ZwWriteFile doit être une 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. Pour obtenir ces informations, appelez ZwCreateFile pour obtenir un handle pour l’objet file qui représente l’appareil physique, puis transmettez ce handle à ZwQueryInformationFile. Pour obtenir la liste des valeurs FILE_XXX_ALIGNMENT du système, consultez DEVICE_OBJECT.

• Les appels à ZwSetInformationFile avec le paramètre FileInformationClass défini sur FilePositionInformation doivent spécifier un décalage qui est un multiple de la taille de secteur.

Les indicateurs CreateOptions FILE_SYNCHRONOUS_IO_ALERT et FILE_SYNCHRONOUS_IO_NONALERT, qui s’excluent mutuellement comme leur nom le suggère, spécifient que toutes les opérations d’E/S sur le fichier seront synchrones, tant qu’elles se produisent via l’objet file référencé par le FileHandle retourné. Toutes les E/S d’un tel fichier sont sérialisées sur tous les threads à l’aide du handle retourné. Si l’un de ces indicateurs CreateOptions est défini, l’indicateur SYNCHRONIZE DesiredAccess doit également être défini pour obliger le gestionnaire d’E/S à utiliser l’objet fichier comme objet de synchronisation. Dans ce cas, le gestionnaire d’E/S effectue le suivi du décalage actuel de la position du fichier, que vous pouvez passer à ZwReadFile et ZwWriteFile. Appelez ZwQueryInformationFile ou ZwSetInformationFile pour obtenir ou définir cette position.

Si l’indicateur de FILE_OPEN_REPARSE_POINT CreateOptions n’est pas spécifié et que ZwCreateFile 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 ZwCreateFile tente d’ouvrir directement le fichier de point d’analyse. Dans les deux cas, si l’opération d’ouverture a réussi, ZwCreateFile retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. ZwCreateFile ne retourne jamais STATUS_REPARSE.

L’indicateur de FILE_OPEN_REQUIRING_OPLOCK CreateOptions é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 ZwCreateFile , puis demander un oplock. Cela garantit qu’un propriétaire d’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 permet d’arrêter un oplock qui existe déjà dans 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 l’avantage 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é que la demande d’oplock a échoué.

L’indicateur FILE_OPEN_REQUIRING_OPLOCK est disponible dans les systèmes d’exploitation Windows 7, Windows Server 2008 R2 et ultérieur. 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, Batch ou Filter pour empêcher d’autres applications d’obtenir des violations de partage. Toutefois, FILE_RESERVE_OPFILTER n’est pratiquement utile que pour les verrous de filtrage. Pour l’utiliser, vous devez effectuer les étapes suivantes :

1. É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.

2. Si la demande de création réussit, demandez un oplock.

3. Ouvrez un autre handle dans le fichier pour effectuer des E/S.

L’étape 3 rend cette opération 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 Batch et rend l’indicateur FILE_RESERVE_OPFILTER inutile pour ces types de verrous d’opération.

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

Les appelants de ZwCreateFile doivent s’exécuter sur IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.

Si l’appel à cette fonction se produit en mode utilisateur, vous devez utiliser le nom « NtCreateFile » au lieu de « ZwCreateFile ».

Pour les appels provenant de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Configuration requise

Voir aussi

ACCESS_MASK

DEVICE_OBJECT

IO_STATUS_BLOCK

InitializeObjectAttributes

Utilisation des versions Nt et Zw des routines des services système natifs

ZwClose

ZwOpenFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile

 Verrous opportunistes

Points d'analyse