CreateHardLinkW, fonction (winbase.h)

Article
03/06/2024

Établit un lien physique 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, pas les répertoires.

Pour effectuer cette opération en tant qu’opération traitée, 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 de fichiers, de chemins et d’espaces de noms.

Conseil

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précédencer « \\ ?\ ». Pour plus d’informations, consultez la section « Limitation maximale de la longueur du chemin d’accès » de Naming Files, Paths et Namespaces .

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

Conseil

lpSecurityAttributes

Réservés au; doit avoir la valeur NULL.

Valeur retournée

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étaillées sur l’erreur, 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 transmettez un nom plus long que MAX_PATH caractères au paramètre lpFileName ou lpExistingFileName de la version ANSI de cette fonction ou à la version Unicode de cette fonction sans précédencer « \ ?\ » 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, c’est-à-dire plusieurs liens durs vers le même fichier, qui peuvent être des noms différents dans le même répertoire, ou des noms identiques ou différents 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 physiques ne sont que des entrées de répertoire pour un fichier, de nombreuses modifications apportées à ce fichier sont instantanément visibles pour les applications qui y accèdent via les liens durs qui le référencent. Toutefois, les informations d’attribut et de taille d’entrée de répertoire sont mises à jour uniquement pour le lien par le biais duquel une modification a été apportée.

Le descripteur de sécurité appartient au fichier vers lequel pointe un lien physique. 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 physique, 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 des descripteurs de sécurité différents par liaison matérielle.

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.

Les indicateurs, les attributs, l’accès et le partage spécifiés dans CreateFile fonctionnent sur une base 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 physique sur le système de fichiers NTFS, les informations d’attribut de fichier dans l’entrée du 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 du 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	Prise en charge
Protocole Server Message Block (SMB) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	No
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	No
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	No

Notez que SMB 3.0 ne prend pas en charge la création de liens physiques sur les partages avec une fonctionnalité 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
   }

Notes

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll