CreateHardLinkA-Funktion (winbase.h)

Artikel
03/13/2024

Erstellt eine feste Verknüpfung zwischen einer vorhandenen Datei und einer neuen Datei. Diese Funktion wird nur im NTFS-Dateisystem und nur für Dateien und nicht für Verzeichnisse unterstützt.

Um diesen Vorgang als transaktionierten Vorgang auszuführen, verwenden Sie die CreateHardLinkTransacted-Funktion .

Syntax

BOOL CreateHardLinkA(
  [in] LPCSTR                lpFileName,
  [in] LPCSTR                lpExistingFileName,
       LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parameter

[in] lpFileName

Der Name der neuen Datei.

Dieser Parameter kann den Pfad enthalten, aber nicht den Namen eines Verzeichnisses angeben.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um diesen Grenzwert auf 32.767 Breitzeichen zu erweitern, stellen Sie dem Pfad "\\?\" voran. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Tipp

Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung aufheben, ohne "\\?\" vorab ausstehen zu müssen. Ausführliche Informationen finden Sie im Abschnitt "Maximale Längenbeschränkung für Pfade" unter Benennen von Dateien, Pfaden und Namespaces .

[in] lpExistingFileName

Der Name der vorhandenen Datei.

Dieser Parameter kann den Pfad enthalten, der den Namen eines Verzeichnisses nicht angeben kann.

Tipp

lpSecurityAttributes

Reserviert; muss NULL sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (null). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Die maximale Anzahl harter Links, die mit dieser Funktion erstellt werden können, beträgt 1023 pro Datei. Wenn für eine Datei mehr als 1023 Links erstellt werden, tritt ein Fehler auf.

Wenn Sie einen Namen, der länger als MAX_PATH Zeichen ist, an den lpFileName - oder lpExistingFileName-Parameter der ANSI-Version dieser Funktion oder an die Unicode-Version dieser Funktion übergeben, ohne dass "\\?\" an den Pfad aussteht, gibt die Funktion ERROR_PATH_NOT_FOUND zurück.

Hinweise

Jeder Verzeichniseintrag für eine Datei, die mit CreateFile oder CreateHardLink erstellt wird, ist ein harter Link zu einer zugeordneten Datei. Ein zusätzlicher harter Link, der mit der CreateHardLink-Funktion erstellt wird, ermöglicht es Ihnen, mehrere Verzeichniseinträge für eine Datei zu haben, d. h. mehrere feste Links zu derselben Datei, die unterschiedliche Namen im selben Verzeichnis oder den gleichen oder unterschiedlichen Namen in verschiedenen Verzeichnissen sein können. Alle harten Links zu einer Datei müssen sich jedoch auf demselben Volume befinden.

Da feste Links nur Verzeichniseinträge für eine Datei sind, sind viele Änderungen an dieser Datei sofort für Anwendungen sichtbar, die über die harten Links darauf zugreifen, die darauf verweisen. Die Verzeichniseintragsgröße und die Attributinformationen werden jedoch nur für den Link aktualisiert, über den die Änderung vorgenommen wurde.

Der Sicherheitsdeskriptor gehört zu der Datei, auf die ein harter Link verweist. Der Link selbst ist nur ein Verzeichniseintrag und verfügt nicht über einen Sicherheitsdeskriptor. Wenn Sie also den Sicherheitsdeskriptor einer harten Verknüpfung ändern, ändern Sie den Sicherheitsdeskriptor der zugrunde liegenden Datei, und alle harten Links, die auf die Datei verweisen, ermöglichen den neu angegebenen Zugriff. Sie können einer Datei nicht pro Hartlink andere Sicherheitsbeschreibungen geben.

Diese Funktion ändert den Sicherheitsdeskriptor der Zu verknüpfenden Datei nicht, auch wenn Sicherheitsdeskriptorinformationen im lpSecurityAttributes-Parameter übergeben werden.

Verwenden Sie DeleteFile , um feste Links zu löschen. Sie können sie unabhängig von der Reihenfolge, in der sie erstellt werden, in beliebiger Reihenfolge löschen.

Flags, Attribute, Zugriff und Freigabe, die in CreateFile angegeben sind, werden auf Dateibasis ausgeführt. Das heißt, wenn Sie eine Datei öffnen, die die Freigabe nicht zulässt, kann eine andere Anwendung die Datei nicht freigeben, indem sie eine neue feste Verknüpfung mit der Datei erstellt.

Wenn Sie eine feste Verknüpfung im NTFS-Dateisystem erstellen, werden die Dateiattributeinformationen im Verzeichniseintrag nur aktualisiert, wenn die Datei geöffnet wird oder wenn GetFileInformationByHandle mit dem Handle einer bestimmten Datei aufgerufen wird.

Verhalten symbolischer Verknüpfungen: Wenn der Pfad auf eine symbolische Verknüpfung verweist, erstellt die Funktion eine feste Verknüpfung mit der symbolischen Verknüpfung.

Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Unterstützt
SMB 3.0-Protokoll (Server Message Block)	Ja
SMB 3.0 Transparent Failover (TFO)	No
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	No
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	No

Beachten Sie, dass SMB 3.0 die Erstellung von harten Links auf Freigaben mit Continuous Availability-Funktion nicht unterstützt.

Beispiele

Der folgende Codeausschnitt zeigt, wie Sie CreateHardLink aufrufen, damit der Sicherheitsdeskriptor einer Datei nicht geändert wird. Der Parameter pszExistingFileName kann der ursprüngliche Dateiname oder ein beliebiger vorhandener Link zu einer Datei sein. Nachdem dieser Code ausgeführt wurde, bezieht sich pszNewLinkName auf die Datei.

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

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

Hinweis

Der winbase.h-Header definiert CreateHardLink als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll