Fungsi LockFile (fileapi.h)

Artikel
08/23/2023

Mengunci file yang ditentukan untuk akses eksklusif oleh proses panggilan.

Untuk menentukan opsi tambahan, misalnya membuat kunci bersama atau untuk operasi block-on-fail, gunakan fungsi LockFileEx .

Sintaks

BOOL LockFile(
  [in] HANDLE hFile,
  [in] DWORD  dwFileOffsetLow,
  [in] DWORD  dwFileOffsetHigh,
  [in] DWORD  nNumberOfBytesToLockLow,
  [in] DWORD  nNumberOfBytesToLockHigh
);

Parameter

[in] hFile

Handel ke file. Handel file harus dibuat dengan hak akses GENERIC_READ atau GENERIC_WRITE . Untuk informasi selengkapnya, lihat Keamanan File dan Hak Akses.

[in] dwFileOffsetLow

Urutan rendah 32 bit dari offset byte awal dalam file tempat kunci harus dimulai.

[in] dwFileOffsetHigh

Urutan tinggi 32 bit dari offset byte awal dalam file tempat kunci harus dimulai.

[in] nNumberOfBytesToLockLow

Urutan rendah 32 bit dari panjang rentang byte yang akan dikunci.

[in] nNumberOfBytesToLockHigh

Panjang 32 bit urutan tinggi dari rentang byte yang akan dikunci.

Menampilkan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).

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

Keterangan

Jika panggilan ke LockFile selesai secara sinkron, entri penyelesaian mungkin tidak diantrekan ketika port penyelesaian dikaitkan dengan handel file.

Fungsi UnlockFile membuka kunci wilayah file yang dikunci oleh LockFile.

Mengunci wilayah file memberikan utas proses penguncian akses eksklusif ke wilayah yang ditentukan menggunakan handel file ini. Jika handel file diwariskan oleh proses yang dibuat oleh proses penguncian, proses anak tidak diberikan akses ke wilayah terkunci. Jika proses penguncian membuka file untuk kedua kalinya, proses penguncian tidak dapat mengakses wilayah yang ditentukan melalui handel kedua ini hingga membuka kunci wilayah.

Mengunci wilayah file tidak mencegah pembacaan atau penulisan dari tampilan file yang dipetakan.

Anda dapat mengunci byte yang berada di luar akhir file saat ini. Ini berguna untuk mengoordinasikan penambahan rekaman ke akhir file.

Kunci eksklusif tidak dapat tumpang tindih dengan wilayah terkunci file yang ada. Untuk informasi selengkapnya, lihat LockFileEx.

Jika LockFile tidak dapat mengunci wilayah file, maka akan segera mengembalikan nol. Ini tidak memblokir. Untuk mengeluarkan permintaan kunci file yang akan memblokir hingga kunci diperoleh, gunakan LockFileEx tanpa bendera LOCKFILE_FAIL_IMMEDIATELY .

Jika proses berakhir dengan sebagian file terkunci atau menutup file yang memiliki kunci yang luar biasa, kunci tidak terkunci oleh sistem operasi. Namun, waktu yang diperlukan sistem operasi untuk membuka kunci ini tergantung pada sumber daya sistem yang tersedia. Oleh karena itu, disarankan agar proses Anda secara eksplisit membuka kunci semua file yang telah dikuncinya saat dihentikan. Jika ini tidak dilakukan, akses ke file-file ini dapat ditolak jika sistem operasi belum membukanya.

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)	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Contoh

Misalnya, lihat Menambahkan Satu File ke File Lain.

Persyaratan


Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	fileapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll