CreateHardLinkW, fonction (winbase.h)

Article
11/20/2024

Établit un lien dur entre un fichier existant et un nouveau fichier. Cette fonction est uniquement prise en charge sur le système de fichiers NTFS, et uniquement pour les fichiers, et non pour les répertoires.

Pour effectuer cette opération en tant qu’opération transactionnelle, utilisez la fonction CreateHardLinkTransacted.

Syntaxe

BOOL CreateHardLinkW(
  [in] LPCWSTR               lpFileName,
  [in] LPCWSTR               lpExistingFileName,
       LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Paramètres

[in] lpFileName

Nom du nouveau fichier.

Ce paramètre peut inclure le chemin d’accès, mais ne peut pas spécifier le nom d’un répertoire.

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 des fichiers, des chemins d’accès et des espaces de noms.

Pourboire

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précéder « \\ ?\ ». Pour plus d’informations, consultez la section « Limite maximale de longueur de chemin » de noms, fichiers, chemin s et espaces de noms.

[in] lpExistingFileName

Nom du fichier existant.

Ce paramètre peut inclure le chemin d’accès ne peut pas spécifier le nom d’un répertoire.

Pourboire

lpSecurityAttributes

Réservé; doit être NULL .

Valeur de retour

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro (0). Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Le nombre maximal de liens durs qui peuvent être créés avec cette fonction est de 1023 par fichier. Si plus de 1023 liens sont créés pour un fichier, une erreur se produit.

Si vous passez un nom plus long que MAX_PATH caractères aux lpFileName ou paramètre lpExistingFileName de la version ANSI de cette fonction ou à la version Unicode de cette fonction sans prédéfini « \\ ?\ » au chemin d’accès, la fonction retourne ERROR_PATH_NOT_FOUND.

Remarques

Toute entrée de répertoire pour un fichier créé avec CreateFile ou CreateHardLink est un lien dur vers un fichier associé. Un lien dur supplémentaire créé avec la fonction CreateHardLink vous permet d’avoir plusieurs entrées de répertoire pour un fichier, autrement dit, plusieurs liens durs vers le même fichier, qui peuvent être différents noms dans le même répertoire, ou les mêmes ou différents noms dans différents répertoires. Toutefois, tous les liens durs vers un fichier doivent se trouver sur le même volume.

Étant donné que les liens durs ne sont que des entrées de répertoire pour un fichier, de nombreuses modifications apportées à ce fichier sont instantanément visibles par les applications qui y accèdent via les liens durs qui le référencent. Toutefois, la taille et les informations d’attribut d’entrée de répertoire sont mises à jour uniquement pour le lien par lequel la modification a été apportée.

Le descripteur de sécurité appartient au fichier auquel un lien dur pointe. Le lien lui-même n’est qu’une entrée de répertoire et n’a pas de descripteur de sécurité. Par conséquent, lorsque vous modifiez le descripteur de sécurité d’un lien dur, vous modifiez le descripteur de sécurité du fichier sous-jacent et tous les liens durs qui pointent vers le fichier autorisent l’accès nouvellement spécifié. Vous ne pouvez pas donner à un fichier différents descripteurs de sécurité sur une base par lien dur.

Cette fonction ne modifie pas le descripteur de sécurité du fichier à lier, même si les informations de descripteur de sécurité sont transmises dans le paramètre lpSecurityAttributes.

Utilisez deleteFile pour supprimer des liens durs. Vous pouvez les supprimer dans n’importe quel ordre, quel que soit l’ordre dans lequel ils sont créés.

Indicateurs, attributs, accès et partage spécifiés dans CreateFile fonctionner par fichier. Autrement dit, si vous ouvrez un fichier qui n’autorise pas le partage, une autre application ne peut pas partager le fichier en créant un lien dur vers le fichier.

Lorsque vous créez un lien dur sur le système de fichiers NTFS, les informations d’attribut de fichier dans l’entrée de répertoire sont actualisées uniquement lorsque le fichier est ouvert ou lorsque GetFileInformationByHandle est appelé avec le handle d’un fichier spécifique.

Comportement de lien symbolique : si le chemin pointe vers un lien symbolique, la fonction crée un lien dur vers le lien symbolique.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Supporté
Protocole SMB (Server Message Block) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Non
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Non
Cluster Shared Volume File System (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Non

Notez que SMB 3.0 ne prend pas en charge la création de liens durs sur des partages avec une capacité de disponibilité continue.

Exemples

L’extrait de code suivant vous montre comment appeler CreateHardLink afin qu’il ne modifie pas le descripteur de sécurité d’un fichier. Le paramètre pszExistingFileName peut être le nom de fichier d’origine ou tout lien existant vers un fichier. Une fois ce code exécuté, pszNewLinkName fait référence au fichier.

  BOOL fCreatedLink = CreateHardLink( pszNewLinkName, 
                                      pszExistingFileName, 
                                      NULL ); // reserved, must be NULL

  if ( fCreatedLink == FALSE )
   {
    ;// handle error condition
   }

Note

L’en-tête winbase.h définit CreateHardLink comme 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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll