Fungsi VirtualFree (memoryapi.h)

Artikel
02/05/2024

Merilis, menonaktifkan, atau merilis dan menonaktifkan wilayah halaman dalam ruang alamat virtual proses panggilan.

Untuk membebaskan memori yang dialokasikan dalam proses lain oleh fungsi VirtualAllocEx , gunakan fungsi VirtualFreeEx .

Sintaks

BOOL VirtualFree(
  [in] LPVOID lpAddress,
  [in] SIZE_T dwSize,
  [in] DWORD  dwFreeType
);

Parameter

[in] lpAddress

Penunjuk ke alamat dasar wilayah halaman yang akan dibebaskan.

Jika parameter dwFreeTypeMEM_RELEASE, parameter ini harus menjadi alamat dasar yang dikembalikan oleh fungsi VirtualAlloc saat wilayah halaman dicadangkan.

[in] dwSize

Ukuran wilayah memori yang akan dibebaskan, dalam byte.

Jika parameter dwFreeTypeMEM_RELEASE, parameter ini harus 0 (nol). Fungsi ini membebaskan seluruh wilayah yang dicadangkan dalam panggilan alokasi awal ke VirtualAlloc.

Jika parameter dwFreeTypeMEM_DECOMMIT, fungsi akan menonaktifkan semua halaman memori yang berisi satu atau beberapa byte dalam rentang dari parameter lpAddress ke (lpAddress+dwSize). Ini berarti, misalnya, bahwa wilayah memori 2-byte yang melekat pada batas halaman menyebabkan kedua halaman dinonaktifkan. Jika lpAddress adalah alamat dasar yang dikembalikan oleh VirtualAlloc dan dwSize adalah 0 (nol), fungsi akan menonaktifkan seluruh wilayah yang dialokasikan oleh VirtualAlloc. Setelah itu, seluruh wilayah berada dalam status cadangan.

[in] dwFreeType

Jenis operasi gratis. Parameter ini harus menjadi salah satu nilai berikut.

Nilai	Makna
MEM_DECOMMIT 0x00004000	Menonaktifkan wilayah halaman yang diterapkan yang ditentukan. Setelah operasi, halaman berada dalam status dicadangkan. Fungsi tidak gagal jika Anda mencoba untuk menonaktifkan halaman yang tidak dikomit. Ini berarti Anda dapat menonaktifkan rentang halaman tanpa terlebih dahulu menentukan status komitmen saat ini. Nilai MEM_DECOMMIT tidak didukung ketika parameter lpAddress menyediakan alamat dasar untuk enklave. Ini berlaku untuk enklave yang tidak mendukung manajemen memori dinamis (yaitu SGX1). Enklave SGX2 mengizinkan MEM_DECOMMIT di mana saja di enklave.
MEM_RELEASE 0x00008000	Merilis wilayah halaman yang ditentukan, atau tempat penampung (untuk tempat penampung, ruang alamat dirilis dan tersedia untuk alokasi lain). Setelah operasi ini, halaman berada dalam status bebas. Jika Anda menentukan nilai ini, dwSize harus 0 (nol), dan lpAddress harus menunjuk ke alamat dasar yang dikembalikan oleh fungsi VirtualAlloc saat wilayah dicadangkan. Fungsi gagal jika salah satu kondisi ini tidak terpenuhi. Jika ada halaman di wilayah yang diterapkan saat ini, fungsi pertama kali dinonaktifkan, lalu merilisnya. Fungsi ini tidak gagal jika Anda mencoba merilis halaman yang berada di status yang berbeda, beberapa dicadangkan dan beberapa diterapkan. Ini berarti Anda dapat merilis rentang halaman tanpa terlebih dahulu menentukan status komitmen saat ini.

Nilai

Makna

MEM_DECOMMIT
0x00004000

Menonaktifkan wilayah halaman yang diterapkan yang ditentukan. Setelah operasi, halaman berada dalam status dicadangkan.

Fungsi tidak gagal jika Anda mencoba untuk menonaktifkan halaman yang tidak dikomit. Ini berarti Anda dapat menonaktifkan rentang halaman tanpa terlebih dahulu menentukan status komitmen saat ini.

Nilai MEM_DECOMMIT tidak didukung ketika parameter lpAddress menyediakan alamat dasar untuk enklave. Ini berlaku untuk enklave yang tidak mendukung manajemen memori dinamis (yaitu SGX1). Enklave SGX2 mengizinkan MEM_DECOMMIT di mana saja di enklave.

MEM_RELEASE
0x00008000

Merilis wilayah halaman yang ditentukan, atau tempat penampung (untuk tempat penampung, ruang alamat dirilis dan tersedia untuk alokasi lain). Setelah operasi ini, halaman berada dalam status bebas.

Jika Anda menentukan nilai ini, dwSize harus 0 (nol), dan lpAddress harus menunjuk ke alamat dasar yang dikembalikan oleh fungsi VirtualAlloc saat wilayah dicadangkan. Fungsi gagal jika salah satu kondisi ini tidak terpenuhi.

Jika ada halaman di wilayah yang diterapkan saat ini, fungsi pertama kali dinonaktifkan, lalu merilisnya.

Fungsi ini tidak gagal jika Anda mencoba merilis halaman yang berada di status yang berbeda, beberapa dicadangkan dan beberapa diterapkan. Ini berarti Anda dapat merilis rentang halaman tanpa terlebih dahulu menentukan status komitmen saat ini.

Saat menggunakan MEM_RELEASE, parameter ini juga dapat menentukan salah satu nilai berikut.

Nilai	Makna
MEM_COALESCE_PLACEHOLDERS 0x00000001	Untuk menggabungkan dua tempat penampung yang berdekatan, tentukan `MEM_RELEASE \| MEM_COALESCE_PLACEHOLDERS`. Ketika Anda menyatukan tempat penampung, lpAddress dan dwSize harus sama persis dengan rentang keseluruhan tempat penampung yang akan digabungkan.
MEM_PRESERVE_PLACEHOLDER 0x00000002	Membebaskan alokasi kembali ke tempat penampung (setelah Anda mengganti tempat penampung dengan alokasi privat menggunakan VirtualAlloc2 atau Virtual2AllocFromApp). Untuk membagi tempat penampung menjadi dua tempat penampung, tentukan `MEM_RELEASE \| MEM_PRESERVE_PLACEHOLDER`.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

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

Keterangan

Setiap halaman memori dalam ruang alamat virtual proses memiliki Status Halaman. Fungsi VirtualFree dapat menonaktifkan rentang halaman yang berada dalam status yang berbeda, beberapa diterapkan dan beberapa tidak diterapkan. Ini berarti Anda dapat menonaktifkan rentang halaman tanpa terlebih dahulu menentukan status komitmen saat ini dari setiap halaman. Menonaktifkan halaman akan merilis penyimpanan fisiknya, baik dalam memori atau di file halaman pada disk.

Jika halaman dinonaktifkan tetapi tidak dirilis, statusnya berubah menjadi dicadangkan. Selanjutnya, Anda dapat memanggil VirtualAlloc untuk menerapkannya, atau VirtualFree untuk merilisnya. Upaya untuk membaca dari atau menulis ke halaman yang dipesan menghasilkan pengecualian pelanggaran akses.

Fungsi VirtualFree dapat merilis berbagai halaman yang berada di berbagai status, beberapa dicadangkan dan beberapa berkomitmen. Ini berarti Anda dapat merilis rentang halaman tanpa terlebih dahulu menentukan status komitmen saat ini dari setiap halaman. Seluruh rentang halaman yang awalnya dicadangkan oleh fungsi VirtualAlloc harus dirilis secara bersamaan.

Jika halaman dirilis, statusnya berubah menjadi gratis, dan tersedia untuk operasi alokasi berikutnya. Setelah memori dirilis atau dinonaktifkan, Anda tidak pernah dapat merujuk ke memori lagi. Setiap informasi yang mungkin ada dalam memori itu hilang selamanya. Mencoba membaca dari atau menulis ke halaman gratis menghasilkan pengecualian pelanggaran akses. Jika Anda perlu menyimpan informasi, jangan nonaktifkan atau kosongkan memori yang berisi informasi tersebut.

Fungsi VirtualFree dapat digunakan pada wilayah memori AWE, dan membatalkan pemetaan halaman fisik apa pun di wilayah tersebut saat membebaskan ruang alamat. Namun, halaman fisik tidak dihapus, dan aplikasi dapat menggunakannya. Aplikasi harus secara eksplisit memanggil FreeUserPhysicalPages untuk membebaskan halaman fisik. Ketika proses dihentikan, semua sumber daya dibersihkan secara otomatis.

Windows 10, versi 1709 dan yang lebih baru dan Windows 11: Untuk menghapus enklave saat Anda selesai menggunakannya, panggil DeleteEnclave. Anda tidak dapat menghapus enklave VBS dengan memanggil fungsi VirtualFree atau VirtualFreeEx . Anda masih dapat menghapus enklave SGX dengan memanggil VirtualFree atau VirtualFreeEx.

Windows 10, versi 1507, Windows 10, versi 1511, Windows 10, versi 1607 dan Windows 10, versi 1703: Untuk menghapus enklave saat Anda selesai menggunakannya, panggil fungsi VirtualFree atau VirtualFreeEx dan tentukan nilai berikut:

Alamat dasar enklave untuk parameter lpAddress .
0 untuk parameter dwSize .
MEM_RELEASE untuk parameter dwFreeType .

Contoh

Misalnya, lihat Menyimpan dan Menerapkan Memori.

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	memoryapi.h (termasuk Windows.h, Memoryapi.h)
Pustaka	onecore.lib
DLL	Kernel32.dll

Lihat juga

Fungsi Manajemen Memori

Fungsi Memori Virtual

VirtualFreeEx

API Vertdll tersedia di enklave VBS