Fungsi LocalAlloc (winbase.h)

Artikel
03/03/2024

Mengalokasikan jumlah byte yang ditentukan dari tumpukan.

Catatan Fungsi lokal memiliki overhead yang lebih besar dan menyediakan lebih sedikit fitur daripada fungsi manajemen memori lainnya. Aplikasi baru harus menggunakan fungsi heap kecuali dokumentasi menyatakan bahwa fungsi lokal harus digunakan. Untuk informasi selengkapnya, lihat Fungsi Global dan Lokal.

Sintaks

DECLSPEC_ALLOCATOR HLOCAL LocalAlloc(
  [in] UINT   uFlags,
  [in] SIZE_T uBytes
);

Parameter

[in] uFlags

Atribut alokasi memori. Defaultnya adalah nilai LMEM_FIXED . Parameter ini bisa menjadi satu atau beberapa nilai berikut, kecuali untuk kombinasi yang tidak kompatibel yang secara khusus dicatat.

Nilai	Makna
LHND 0x0042	Menggabungkan LMEM_MOVEABLE dan LMEM_ZEROINIT.
LMEM_FIXED 0x0000	Mengalokasikan memori tetap. Nilai yang dikembalikan adalah penunjuk ke objek memori.
LMEM_MOVEABLE 0x0002	Mengalokasikan memori yang dapat di-movable. Blok memori tidak pernah dipindahkan dalam memori fisik, tetapi dapat dipindahkan dalam tumpukan default. Nilai yang dikembalikan adalah handel ke objek memori. Untuk menerjemahkan handel ke penunjuk, gunakan fungsi LocalLock . Nilai ini tidak dapat digabungkan dengan LMEM_FIXED.
LMEM_ZEROINIT 0x0040	Menginisialisasi konten memori ke nol.
LPTR 0x0040	Menggabungkan LMEM_FIXED dan LMEM_ZEROINIT.
NONZEROLHND	Sama seperti LMEM_MOVEABLE.
NONZEROLPTR	Sama seperti LMEM_FIXED.

Nilai berikut kedaluarsa, tetapi disediakan untuk kompatibilitas dengan Windows 16-bit. Mereka diabaikan.

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

[in] uBytes

Jumlah byte yang akan dialokasikan. Jika parameter ini nol dan parameter uFlags menentukan LMEM_MOVEABLE, fungsi mengembalikan handel ke objek memori yang ditandai sebagai dibuang.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke objek memori yang baru dialokasikan.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Manajemen memori Windows tidak menyediakan timbunan lokal dan timbunan global yang terpisah. Oleh karena itu, fungsi LocalAlloc dan GlobalAlloc pada dasarnya sama.

Bendera memori bergerak LHND, LMEM_MOVABLE, dan NONZEROLHND menambahkan overhead yang tidak perlu dan memerlukan penguncian untuk digunakan dengan aman. Mereka harus dihindari kecuali dokumentasi secara khusus menyatakan bahwa mereka harus digunakan.

Aplikasi baru harus menggunakan fungsi heap kecuali dokumentasi secara khusus menyatakan bahwa fungsi lokal harus digunakan. Misalnya, beberapa fungsi Windows mengalokasikan memori yang harus dibebaskan dengan LocalFree.

Jika tumpukan tidak berisi ruang kosong yang cukup untuk memenuhi permintaan, LocalAlloc mengembalikan NULL. Karena NULL digunakan untuk menunjukkan kesalahan, alamat virtual nol tidak pernah dialokasikan. Oleh karena itu, mudah untuk mendeteksi penggunaan pointer NULL .

Jika fungsi LocalAlloc berhasil, fungsi tersebut mengalokasikan setidaknya jumlah yang diminta. Jika jumlah yang dialokasikan lebih besar dari jumlah yang diminta, proses dapat menggunakan seluruh jumlah. Untuk menentukan jumlah byte aktual yang dialokasikan, gunakan fungsi LocalSize .

Untuk membebaskan memori, gunakan fungsi LocalFree . Tidak aman untuk membebaskan memori yang dialokasikan dengan LocalAlloc menggunakan GlobalFree.

Contoh

Kode berikut menunjukkan penggunaan sederhana LocalAlloc dan LocalFree.

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

void _cdecl _tmain()
{
    LPTSTR pszBuf=NULL;

    pszBuf = (LPTSTR)LocalAlloc(
              LPTR,
              MAX_PATH*sizeof(TCHAR));

    // Handle error condition
    if( pszBuf == NULL )
    {
       _tprintf(TEXT("LocalAlloc failed (%d)\n"), GetLastError());
       return;
    }

    //see how much memory was allocated
    _tprintf(TEXT("LocalAlloc allocated %d bytes\n"), LocalSize(pszBuf));

    // Use the memory allocated

    // Free the memory when finished with it
    LocalFree(pszBuf);
}

Persyaratan

Persyaratan	Nilai
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	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll