CreateHardLinkA, fonction (winbase.h)

Article
03/03/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, et non pour les répertoires.

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

Syntaxe

BOOL CreateHardLinkA(
  [in] LPCSTR                lpFileName,
  [in] LPCSTR                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 de large, 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 de MAX_PATH sans précédencer « \ ?\ ». Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans 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 être 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 physiques pouvant être créés avec cette fonction est de 1 023 par fichier. Si plus de 1 023 liens sont créés pour un fichier, une erreur se produit.

Si vous transmettez un nom de plus de 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 physique vers un fichier associé. Un lien physique 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 physiques 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 physiques 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 physiques 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 physiques 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 lien physique.

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

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

Les indicateurs, attributs, accès et partage spécifiés dans CreateFile fonctionnent 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 physique 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 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 physique 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 en tant qu’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. La combinaison 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