Fungsi SymLoadModuleEx (dbghelp.h)

Artikel
22/02/2025

Memuat tabel simbol untuk modul yang ditentukan.

Sintaksis

DWORD64 IMAGEAPI SymLoadModuleEx(
  [in] HANDLE        hProcess,
  [in] HANDLE        hFile,
  [in] PCSTR         ImageName,
  [in] PCSTR         ModuleName,
  [in] DWORD64       BaseOfDll,
  [in] DWORD         DllSize,
  [in] PMODLOAD_DATA Data,
  [in] DWORD         Flags
);

Parameter

[in] hProcess

Handel ke proses yang awalnya diteruskan ke fungsi SymInitialize.

[in] hFile

Handel ke file untuk gambar yang dapat dieksekusi. Argumen ini sebagian besar digunakan oleh debugger, di mana debugger meneruskan handel file yang diperoleh dari peristiwa penelusuran kesalahan. Nilai NULL menunjukkan bahwa hFile tidak digunakan.

[in] ImageName

Nama gambar yang dapat dieksekusi. Nama ini dapat berisi jalur parsial, jalur lengkap, atau tidak ada jalur sama sekali. Jika file tidak dapat ditemukan dengan nama yang disediakan, jalur pencarian simbol digunakan.

[in] ModuleName

Nama pintasan untuk modul. Jika nilai pointer NULL, pustaka membuat nama menggunakan nama dasar file simbol.

[in] BaseOfDll

Alamat beban modul. Jika nilainya nol, pustaka mendapatkan alamat beban dari file simbol. Alamat beban yang terkandung dalam file simbol belum tentu merupakan alamat beban aktual. Debugger dan aplikasi lain yang memiliki alamat beban aktual harus menggunakan alamat beban nyata saat memanggil fungsi ini.

Jika gambar adalah file .pdb, parameter ini tidak boleh nol.

[in] DllSize

Ukuran modul, dalam byte. Jika nilainya nol, pustaka mendapatkan ukuran dari file simbol. Ukuran yang terkandung dalam file simbol belum tentu ukuran aktual. Debugger dan aplikasi lain yang memiliki ukuran aktual harus menggunakan ukuran nyata saat memanggil fungsi ini.

Jika gambar adalah file .pdb, parameter ini tidak boleh nol.

[in] Data

Penunjuk ke struktur MODLOAD_DATA yang mewakili header selain header PE standar. Parameter ini bersifat opsional dan dapat NULL.

[in] Flags

Parameter ini bisa nol atau satu atau beberapa nilai berikut. Jika parameter ini nol, fungsi memuat modul dan simbol untuk modul.

Nilai	Arti
SLMFLAG_NO_SYMBOLS 0x4	Memuat modul tetapi bukan simbol untuk modul.
SLMFLAG_VIRTUAL 0x1	Membuat modul virtual bernama ModuleName di alamat yang ditentukan dalam BaseOfDll. Untuk menambahkan simbol ke modul ini, panggil fungsi SymAddSymbol.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian adalah alamat dasar modul yang dimuat.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mengambil informasi kesalahan yang diperluas, panggil GetLastError.

Jika modul sudah dimuat, nilai yang dikembalikan adalah nol dan GetLastError mengembalikan ERROR_SUCCESS.

Komentar

Penangan simbol membuat entri untuk modul dan jika opsi pemuatan simbol yang ditangguhkan dimatikan, upaya dilakukan untuk memuat simbol. Jika pemuatan simbol yang ditangguhkan diaktifkan, modul ditandai sebagai ditangguhkan dan simbol tidak dimuat hingga referensi dibuat ke simbol dalam modul. Oleh karena itu, Anda harus selalu memanggil fungsi SymGetModuleInfo64 setelah memanggil SymLoadModuleEx.

Untuk membongkar tabel simbol, gunakan fungsi SymUnloadModule64.

Semua fungsi DbgHelp, seperti yang ini, berutas tunggal. Oleh karena itu, panggilan dari lebih dari satu utas ke fungsi ini kemungkinan akan mengakibatkan perilaku tak terduga atau kerusakan memori. Untuk menghindari hal ini, Anda harus menyinkronkan semua panggilan bersamaan dari lebih dari satu utas ke fungsi ini.

Untuk memanggil versi Unicode dari fungsi ini, tentukan DBGHELP_TRANSLATE_TCHAR.