Fonction NtCreateFile (ntifs.h)

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

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateFile(
  [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 standard définis pour tous les types d’objets, l’appelant peut spécifier l’un des droits d’accès spécifiques suivants : c’est-à-dire des droits spécifiques aux fichiers.

L’appelant peut également spécifier les droits d’accès génériques suivants (droits qui s’appliquent à tous les types d’objets, où la signification de chaque droit d’accès générique est spécifique au type d’objet). Les droits d’accès génériques pour les objets fichier correspondent à des droits d’accès spécifiques, comme indiqué dans le tableau suivant. (Notez que « correspond » signifie « mappe à » et ne signifie pas que la valeur du droit générique est « égale » à la valeur du ou au niveau du bit de son mappage de droits spécifiques). Le gestionnaire d’E/S définit le mappage réel.

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 (mais ne sont pas égaux à) 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 et Droits d’accès.

[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 dans la documentation Microsoft Windows SDK. 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 de périphérique et intermédiaires, ce paramètre doit être un pointeur NULL .

[in] EaLength

Pour les pilotes de périphérique et intermédiaires, ce paramètre doit être égal à zéro.

Valeur retournée

NtCreateFile retourne STATUS_SUCCESS en cas de 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 l’échec en vérifiant le paramètre IoStatusBlock .

Remarques

NtCreateFile 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 NtClose 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 NtCreateFile :

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

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 NtCreateFile 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é à NtCreateFile 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 à NtCreateFile 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 NtCreateFile 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 NtCreateFile ne peut pas désactiver les indicateurs FileAttributes existants, mais peut activer des indicateurs supplémentaires pour le même fichier. Notez que ce style de remplacement des fichiers est cohérent avec MS-DOS, Microsoft Windows 3.1 et OS/2.

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 à NtCreateFile é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é à NtReadFile ou NtWriteFile doit être un multiple de la taille de secteur.
• La longueur passée à NtReadFile ou NtWriteFile 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 NtCreateFile pour obtenir un handle pour l’objet file qui représente l’appareil physique, puis transmettez ce handle à NtQueryInformationFile. Pour obtenir la liste des valeurs FILE_XXX_ALIGNMENT du système, consultez DEVICE_OBJECT.
• Les appels à NtSetInformationFile 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) spécifient que toutes les opérations d’E/S sur le fichier seront synchrones, tant que les opérations 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 file 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 à NtReadFile et NtWriteFile. Appelez NtQueryInformationFile ou NtSetInformationFile pour obtenir ou définir cette position.

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

Pour l’indicateur de FILE_OPEN_BY_FILE_ID CreateOptions , un exemple de nom d’appareil aura le format suivant :

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

où FileID est de 8 octets et ObjectID de 16 octets :

• Sur NTFS, il peut s’agir d’un numéro de référence ou d’un ID d’objet de 8 octets ou de 16 octets. Un numéro de référence de 16 octets est identique à un nombre de 8 octets rempli de zéros.
• Sur ReFS, il peut s’agir d’un numéro de référence de 8 octets ou de 16 octets. Un nombre de 16 octets n’est pas lié à un nombre de 8 octets. Les ID d’objet ne sont pas pris en charge.
• Les systèmes de fichiers FAT, ExFAT, UDFS et CDFS ne prennent pas en charge l’indicateur FILE_OPEN_BY_FILE_ID.

Ce numéro est attribué par et spécifique au système de fichiers particulier. Étant donné que le champ nom de fichier contient en partie un objet blob binaire, il est incorrect de supposer qu’il s’agit d’une chaîne Unicode valide et, plus important encore, peut ne pas être une chaîne terminée par null.

Les appelants de NtCreateFile doivent être en cours d’exécution à IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.

Pour les appels à partir 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 Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

Voir aussi

ACCESS_MASK

DEVICE_OBJECT

EXTENDED_CREATE_INFORMATION

IO_STATUS_BLOCK

InitializeObjectAttributes

NtClose

NtOpenFile

NtQueryInformationFile

NtReadFile

NtSetInformationFile

NtWriteFile