CreateHardLinkA 函式 (winbase.h)

發行項
06/02/2023

建立現有檔案與新檔案之間的硬式連結。只有 NTFS 檔案系統才支援此函式，而且僅適用于檔案，而非目錄。

若要以交易作業的形式執行此作業，請使用 CreateHardLinkTransacted 函式。

語法

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

參數

[in] lpFileName

新檔案的名稱。

此參數可能包含路徑，但無法指定目錄的名稱。

根據預設，名稱限制為MAX_PATH個字元。若要將此限制延伸至 32，767 寬字元，請在路徑前面加上「\\？\」。如需詳細資訊，請參閱命名檔案、路徑與命名空間。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上「\\？\」。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[in] lpExistingFileName

現有檔案的名稱。

此參數可能包含路徑無法指定目錄的名稱。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上「\\？\」。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

lpSecurityAttributes

保留;必須是 Null。

傳回值

如果函式成功，則傳回非零的值。

如果函式失敗，傳回值會是零 (0) 。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

使用此函式建立的硬式連結數目上限為每一個檔案 1023。如果為檔案建立超過 1023 個連結，則會產生錯誤。

如果您將名稱超過MAX_PATH字元傳遞至此函式 ANSI 版本的 lpFileName 或 lpExistingFileName 參數，或傳遞至此函式的 Unicode 版本，而不需在路徑前面加上「\\？\」，函式會傳回ERROR_PATH_NOT_FOUND。

備註

使用 CreateFile 或 CreateHardLink 建立之檔案的任何目錄專案都是相關聯檔案的硬式連結。使用 CreateHardLink 函式建立的其他硬式連結可讓您擁有檔案的多個目錄專案，也就是相同檔案的多個硬式連結，這可以是相同目錄中的不同名稱，或不同目錄中的相同或不同名稱。不過，檔案的所有硬式連結都必須位於相同的磁片區上。

由於硬式連結只是檔案的目錄專案，因此透過參考檔案的硬式連結，存取該檔案的應用程式會立即看到該檔案的許多變更。不過，目錄專案大小和屬性資訊只會針對進行變更的連結進行更新。

安全性描述項屬於硬式連結所指向的檔案。連結本身只是目錄專案，而且沒有安全性描述元。因此，當您變更硬式連結的安全性描述元時，您會變更基礎檔案的安全性描述元，以及指向該檔案的所有硬式連結都允許新指定的存取。您無法為每個硬式連結提供檔案不同的安全性描述元。

此函式不會修改要連結之檔案的安全性描述元，即使安全性描述項資訊是在 lpSecurityAttributes 參數中傳遞也一樣。

使用 DeleteFile 刪除硬式連結。不論建立順序為何，您都可以依任何順序刪除它們。

CreateFile中指定的旗標、屬性、存取和共用會以個別檔案為基礎運作。也就是說，如果您開啟不允許共用的檔案，另一個應用程式就無法藉由建立檔案的新硬式連結來共用檔案。

當您在 NTFS 檔案系統上建立硬式連結時，只有在開啟檔案時，才會重新整理目錄專案中的檔案屬性資訊，或是使用特定檔案的控制碼呼叫 GetFileInformationByHandle 時。

符號連結行為：如果路徑指向符號連結，函式會建立符號連結的硬式連結。

在Windows 8和Windows Server 2012中，下列技術支援此函式。

技術	支援
伺服器訊息區 (SMB) 3.0 通訊協定	Yes
SMB 3.0 透明容錯移轉 (TFO)	No
具有向外延展檔案共用的 SMB 3.0 (SO)	No
叢集共用磁片區檔案系統 (CsvFS)	Yes
彈性檔案系統 (ReFS)	No

請注意，SMB 3.0 不支援在具有持續可用性功能的共用上建立硬式連結。

範例

下列程式碼片段示範如何呼叫 CreateHardLink ，使其不會修改檔案的安全性描述元。 pszExistingFileName參數可以是原始檔案名稱，或任何檔案的現有連結。執行此程式碼之後， pszNewLinkName 會參考檔案。

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

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

注意

winbase.h 標頭會將 CreateHardLink 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll