Fungsi CreateHardLinkA (winbase.h)

Artikel
03/13/2024

Membuat tautan keras antara file yang ada dan file baru. Fungsi ini hanya didukung pada sistem file NTFS, dan hanya untuk file, bukan direktori.

Untuk melakukan operasi ini sebagai operasi yang ditransaksikan, gunakan fungsi CreateHardLinkTransacted .

Sintaks

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

Parameter

[in] lpFileName

Nama file baru.

Parameter ini dapat mencakup jalur tetapi tidak dapat menentukan nama direktori.

Secara default, nama terbatas pada MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Menamai File, Jalur, dan Namespace.

Tip

Dimulai dengan Windows 10, Versi 1607, Anda dapat ikut serta untuk menghapus batasan MAX_PATH tanpa menambahkan awalan "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" dari Penamaan File, Jalur, dan Namespace untuk detailnya.

[in] lpExistingFileName

Nama file yang ada.

Parameter ini mungkin mencakup jalur tidak dapat menentukan nama direktori.

Tip

lpSecurityAttributes

Dipesan; harus NULL.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol (0). Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Jumlah maksimum tautan keras yang dapat dibuat dengan fungsi ini adalah 1023 per file. Jika lebih dari 1023 tautan dibuat untuk file, hasil kesalahan.

Jika Anda meneruskan nama yang lebih panjang dari MAX_PATH karakter ke parameter lpFileName atau lpExistingFileName dari versi ANSI fungsi ini atau ke versi Unicode fungsi ini tanpa menambahkan "\\?\" ke jalur, fungsi mengembalikan ERROR_PATH_NOT_FOUND.

Keterangan

Setiap entri direktori untuk file yang dibuat dengan CreateFile atau CreateHardLink adalah tautan keras ke file terkait. Tautan keras tambahan yang dibuat dengan fungsi CreateHardLink memungkinkan Anda memiliki beberapa entri direktori untuk file, yaitu, beberapa tautan keras ke file yang sama, yang dapat menjadi nama yang berbeda dalam direktori yang sama, atau nama yang sama atau berbeda di direktori yang berbeda. Namun, semua tautan keras ke file harus berada pada volume yang sama.

Karena tautan keras hanya entri direktori untuk file, banyak perubahan pada file tersebut langsung terlihat oleh aplikasi yang mengaksesnya melalui tautan keras yang mereferensikannya. Namun, ukuran entri direktori dan informasi atribut diperbarui hanya untuk tautan tempat perubahan dilakukan.

Deskriptor keamanan milik file tempat hard link menunjuk. Tautan itu sendiri hanya entri direktori, dan tidak memiliki deskriptor keamanan. Oleh karena itu, ketika Anda mengubah pendeskripsi keamanan dari tautan keras, Anda mengubah pendeskripsi keamanan file yang mendasar, dan semua tautan keras yang menunjuk ke file memungkinkan akses yang baru ditentukan. Anda tidak dapat memberikan pendeskripsi keamanan yang berbeda pada file berdasarkan per tautan keras.

Fungsi ini tidak mengubah pendeskripsi keamanan file yang akan ditautkan, bahkan jika informasi deskriptor keamanan diteruskan dalam parameter lpSecurityAttributes .

Gunakan DeleteFile untuk menghapus tautan keras. Anda dapat menghapusnya dalam urutan apa pun terlepas dari urutan pembuatannya.

Bendera, atribut, akses, dan berbagi yang ditentukan dalam CreateFile beroperasi per file. Artinya, jika Anda membuka file yang tidak mengizinkan berbagi, aplikasi lain tidak dapat berbagi file dengan membuat tautan keras baru ke file.

Saat Anda membuat tautan keras pada sistem file NTFS, informasi atribut file dalam entri direktori disegarkan hanya ketika file dibuka, atau ketika GetFileInformationByHandle dipanggil dengan handel file tertentu.

Perilaku tautan simbolis—Jika jalur menunjuk ke tautan simbolis, fungsi akan membuat tautan keras ke tautan simbolis.

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
SMB 3.0 Transparent Failover (TFO)	Tidak
SMB 3.0 dengan Scale-out File Shares (SO)	Tidak
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Tidak

Perhatikan bahwa SMB 3.0 tidak mendukung pembuatan tautan keras pada berbagi dengan kemampuan ketersediaan berkelanjutan.

Contoh

Cuplikan kode berikut menunjukkan cara memanggil CreateHardLink sehingga tidak mengubah pendeskripsi keamanan file. Parameter pszExistingFileName dapat menjadi nama file asli, atau tautan apa pun yang ada ke file. Setelah kode ini dijalankan, pszNewLinkName mengacu pada file .

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

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

Catatan

Header winbase.h mendefinisikan CreateHardLink sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll