Fonction NtCreateFile (winternl.h)
Crée un fichier ou un répertoire, ou ouvre un fichier, un appareil, un répertoire ou un volume existant.
Cette fonction est l’équivalent en mode utilisateur de la fonction ZwCreateFile documentée dans le Kit de pilotes Windows (WDK).
Syntaxe
__kernel_entry 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] PVOID EaBuffer,
[in] ULONG EaLength
);
Paramètres
[out] FileHandle
Pointeur vers une variable qui reçoit le handle de fichier si l’appel réussit.
[in] DesiredAccess
Valeur ACCESS_MASK qui exprime le type d’accès requis par l’appelant au fichier ou au répertoire. L’ensemble d’indicateurs de DesiredAccess définis par le système détermine les droits d’accès spécifiques suivants pour les objets de fichier.
Les appelants de NtCreateFile peuvent spécifier une ou une combinaison des éléments suivants, éventuellement à l’aide d’un bit-OR avec des indicateurs compatibles supplémentaires provenant de la liste des indicateurs DesiredAccess, pour tout objet de fichier qui ne représente pas un fichier de répertoire.
La valeur FILE_GENERIC_EXECUTE n’est pas pertinente pour les pilotes de périphérique et intermédiaire.
Les STANDARD_RIGHTS_XXX sont des valeurs système prédéfinies utilisées pour appliquer la sécurité sur les objets système.
Pour ouvrir ou créer un fichier de répertoire, comme indiqué avec le paramètre CreateOptions, les appelants d'NtCreateFile peuvent spécifier une ou une combinaison des éléments suivants, éventuellement à l’aide d’un ou plusieurs indicateurs compatibles à partir de la liste des indicateurs DesiredAccess.
[in] ObjectAttributes
Pointeur vers une structure déjà initialisée avec InitializeObjectAttributes. Les membres de cette structure pour un objet de fichier incluent les éléments suivants.
| Valeur | Signification |
|---|---|
|
Spécifie le nombre d’octets de ObjectAttributes données fournies. Cette valeur doit être au moins sizeof(OBJECT_ATTRIBUTES). |
|
Spécifie éventuellement un handle dans un répertoire obtenu par un appel précédent à NtCreateFile. Si cette valeur est |
|
Pointe vers une chaîne Unicode mise en mémoire tampon qui nomme le fichier à créer ou ouvrir. Cette valeur doit être une spécification de fichier complète ou le nom d’un objet d’appareil, sauf s’il s’agit du nom d’un fichier par rapport au répertoire spécifié par RootDirectory. Par exemple, \Device\Floppy1\myfile.dat ou \ ?? \B :\myfile.dat peut être la spécification complète du fichier, à condition que le pilote de floppy et le système de fichiers surchargé soient déjà chargés. Pour plus d’informations, consultez noms de fichiers, chemins d’accès et espaces de noms. |
|
Ensemble d’indicateurs qui contrôlent les attributs de l’objet de fichier. Cette valeur peut être égale à zéro ou OBJ_CASE_INSENSITIVE, ce qui indique que le code de recherche de noms doit ignorer le cas du membre ObjectName plutôt que d’effectuer une recherche exacte-correspondance. La valeur OBJ_INHERIT n’est pas pertinente pour les pilotes de périphérique et intermédiaire. |
|
Spécifie éventuellement un descripteur de sécurité à appliquer à un fichier. Les listes de contrôle d’accès spécifiées par un descripteur de sécurité de ce type sont appliquées au fichier uniquement lors de sa création. Si la valeur est null lorsqu’un fichier est créé, la liste de contrôle d’accès placée sur le fichier dépend du système de fichiers ; la plupart des systèmes de fichiers propagent une partie de cette liste de contrôle d’accès à partir du fichier de répertoire parent combiné à la liste de contrôle d’accès par défaut de l’appelant. Les pilotes de périphérique et intermédiaire peuvent définir ce membre sur NULL. |
|
Spécifie les droits d’accès qu’un serveur doit être donné au contexte de sécurité du client. Cette valeur n’est pasNULL uniquement lorsqu’une connexion à un serveur protégé est établie, ce qui permet à l’appelant de contrôler quelles parties du contexte de sécurité de l’appelant sont mises à la disposition du serveur et si le serveur est autorisé à emprunter l’identité de l’appelant. |
[out] IoStatusBlock
Pointeur vers une variable qui reçoit l’état d’achèvement final et les informations relatives à l’opération demandée. Lors du retour de
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
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 créé, remplacé ou remplacé.
[in] FileAttributes
Attributs de fichier. Les attributs spécifiés explicitement sont appliqués uniquement lorsque le fichier est créé, remplacé ou, dans certains cas, remplacé. Par défaut, cette valeur est un FILE_ATTRIBUTE_NORMAL, qui peut être substitué par une combinaison ORed d’un ou plusieurs indicateurs FILE_ATTRIBUTE_xxxx, qui sont définis dans Wdm.h et NtDdk.h. Pour obtenir la liste des indicateurs qui peuvent être utilisés avec NtCreateFile, consultez CreateFile.
[in] ShareAccess
Type d’accès de partage que l’appelant souhaite utiliser dans le fichier, comme zéro, ou comme une ou une combinaison des valeurs suivantes.
Pour plus d’informations, consultez le Kit de développement logiciel (SDK) Windows.
[in] CreateDisposition
Spécifie ce qu’il faut faire, selon que le fichier existe déjà, comme l’une des valeurs suivantes.
[in] CreateOptions
Options à appliquer lors de la création ou de l’ouverture du fichier, en tant que combinaison compatible des indicateurs suivants.
[in] EaBuffer
Pointeur vers une mémoire tampon EA utilisée pour passer des attributs étendus.
[in] EaLength
Longueur de la mémoire tampon EA.
Valeur de retour
NtCreateFile retourne STATUS_SUCCESS ou un état d’erreur approprié. S’il retourne un état d’erreur, l’appelant peut trouver plus d’informations sur la cause de l’échec en vérifiant le IoStatusBlock. Pour simplifier cette vérification, une application peut utiliser les macros NT_SUCCESS, NT_ERRORet NT_WARNING.
Remarques
Le handle, donné par NtCreateFile, peut être utilisé par des appels suivants pour manipuler des données dans le fichier ou l’état ou les attributs de l’objet fichier.
Il existe deux façons de spécifier le nom du fichier à créer ou ouvrir avec NtCreateFile:
- En tant que nom de chemin complet, fourni dans le ObjectName membre 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 RootDirectory membre de l’entrée ObjectAttributes
Certains indicateurs DesiredAccess et les combinaisons d’indicateurs ont les effets suivants :
- Pour qu’un appelant synchronise une saisie semi-automatique en attendant laFileHandle
retournée, l’indicateur SYNCHRONIZE doit être défini. - Le passage d’un zéro à DesiredFlags n’est pas valide.
- Si seuls les indicateurs FILE_APPEND_DATA et SYNCHRONIZE sont définis, l’appelant ne peut écrire qu’à 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 de FILE_WRITE_DATA pour un fichier permet également aux écritures au-delà de la fin du fichier de se produire. Le fichier est également é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 FileHandleretourné, 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.
Le paramètre ShareAccess détermine si des threads distincts peuvent accéder au même fichier, éventuellement simultanément. À condition que les deux openeurs de fichiers aient le privilège d’accéder à un fichier de la manière spécifiée, le fichier peut être correctement ouvert et partagé. Si l’appelant d’origine de NtCreateFile ne spécifie pas FILE_SHARE_READ, FILE_SHARE_WRITEou 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, le paramètre
La valeur CreateDispositionFILE_SUPERSEDE nécessite que l’appelant ait 'accès DELETE à un objet de fichier existant. Dans ce cas, un appel réussi à NtCreateFile avec FILE_SUPERSEDE sur un fichier existant supprime efficacement 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 le jeu d’indicateurs de FILE_SHARE_DELETE.
Notez que ce type de disposition est cohérent avec le style POSIX de remplacement des fichiers. Les valeurs CreateDispositionFILE_OVERWRITE_IF et FILE_SUPERSEDE sont similaires. Si ZwCreateFile est appelé avec un fichier existant et que 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 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 de FILE_SHARE_WRITE défini dans le paramètre d’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 de FileAttributes existants, mais peut activer des indicateurs supplémentaires pour le même fichier. Notez que ce style de remplacement de fichiers est cohérent avec les systèmes d’exploitation MS-DOS, Windows 3.1 et OS/2.
La valeur CreateOptionsFILE_DIRECTORY_FILE spécifie que le fichier à créer ou ouvert 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 createOptions incohérente ou valeur CreateDisposition, l’appel à NtCreateFile échoue.
L’indicateur CreateOptionsFILE_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 à d’autres routines NtXXXFile, notamment les suivantes :
- Toute ByteOffset facultative
transmise à la fonction NtReadFile ou NtWriteFile doit être intégrale de la taille du secteur. - La Length passée à NtReadFile ou NtWriteFile, doit être intégrale de la taille du secteur. Notez que la spécification d’une opération de lecture dans une mémoire tampon dont la longueur est exactement la taille du secteur peut entraîner un nombre moindre d’octets significatifs transférés vers cette mémoire tampon si la fin du fichier a été atteinte pendant le transfert.
- Les mémoires tampons doivent être ajustées conformément aux exigences d’alignement de l’appareil sous-jacent. Ces informations peuvent être obtenues en appelant NtCreateFile pour obtenir un handle pour l’objet de fichier qui représente l’appareil physique, puis en appelant NtQueryInformationFile avec ce handle. Pour obtenir la liste des valeurs du système FILE_XXX_ALIGNMENT, consultez la documentation du Kit de développement logiciel (SDK) Windows.
- Les appels à NtSetInformationFile avec le paramètre FileInformationClass défini sur FilePositionInformation doivent spécifier un décalage qui est une partie intégrante de la taille du secteur.
Si le paramètre CreateOptions spécifie l’indicateur FILE_OPEN_REPARSE_POINT et NtCreateFile ouvre un fichier avec un point d’analyse, le traitement d’analyse normal n’a pas lieu et NtCreateFile tente d’ouvrir directement le fichier de point d’analyse. Si l’indicateur FILE_OPEN_REPARSE_POINT n’est pas spécifié, le traitement normal du point d’analyse se produit pour le fichier. Dans les deux cas, si l’opération ouverte a réussi, NtCreateFile retourne STATUS_SUCCESS; sinon, un code d’erreur. La fonction NtCreateFile ne retourne jamais STATUS_REPARSE.
L’indicateur
Dans Windows 7, si d’autres handles existent sur le fichier lorsqu’une application utilise cet indicateur, 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 oplock qui existe déjà sur le fichier, la définition de l’indicateur de 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 cet indicateur doit demander un oplock une fois cet appel réussi, ou toutes les tentatives suivantes d’ouverture du fichier seront bloquées sans bénéficier du traitement normal d’oplock. De même, si cet appel réussit mais que la requête oplock suivante échoue, une application qui utilise cet indicateur doit fermer son handle après qu’elle détecte que la demande oplock a échoué.
L’indicateur de
- Émettez une demande de création avec CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess exactement FILE_READ_ATTRIBUTESet ShareAccess de
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)exactement. Les échecs possibles sont les suivants :- S’il existe déjà des handles ouverts, la demande de création échoue avec STATUS_OPLOCK_NOT_GRANTED, et l’oplock demandé suivant échoue également.
- Si vous ouvrez avec plus d’accès que FILE_READ_ATTRIBUTES ou moins de partage que
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE), la requête échoue avec 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.
(FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL) et qui n’interrompt toujours pas un oplock de filtre. Toutefois, toute DesiredAccess supérieure à (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 d’oplocks.
NTFS est le seul système de fichiers Microsoft qui implémente FILE_RESERVE_OPFILTER.
Pour plus d’informations sur les verrous oplocks, consultez verrous opportunistes.
Notez que le fichier d’en-tête WDK NtDef.h est nécessaire pour de nombreuses définitions constantes ainsi que pour la macro InitializeObjectAttributes. Vous pouvez également utiliser les fonctions LoadLibrary et GetProcAddress pour lier dynamiquement à NtDll.dll.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Windows |
| d’en-tête | winternl.h |
| bibliothèque | ntdll.lib |
| DLL | ntdll.dll |