Fungsi SymInitialize (dbghelp.h)

Artikel
03/11/2023

Menginisialisasi penangan simbol untuk sebuah proses.

Sintaks

BOOL IMAGEAPI SymInitialize(
  [in]           HANDLE hProcess,
  [in, optional] PCSTR  UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

Parameter

[in] hProcess

Handel yang mengidentifikasi penelepon. Nilai ini harus unik dan bukan nol, tetapi tidak perlu menjadi handel proses. Namun, jika Anda menggunakan handel proses, pastikan untuk menggunakan handel yang benar. Jika aplikasi adalah debugger, gunakan handel proses untuk proses yang sedang di-debug. Jangan gunakan handel yang dikembalikan oleh GetCurrentProcess. Handel yang digunakan harus unik untuk menghindari berbagi sesi dengan komponen lain, dan menggunakan GetCurrentProcess dapat memiliki hasil yang tidak terduga ketika beberapa komponen mencoba menggunakan dbghelp untuk memeriksa proses saat ini. Menggunakan GetCurrentProcess saat men-debug proses lain juga akan menyebabkan fungsi seperti SymLoadModuleEx memiliki hasil yang tidak terduga.

Parameter ini tidak boleh NULL.

[in, optional] UserSearchPath

Jalur, atau rangkaian jalur yang dipisahkan oleh titik koma (;), yang digunakan untuk mencari file simbol. Jika parameter ini NULL, pustaka mencoba membentuk jalur simbol dari sumber berikut:

Direktori kerja aplikasi saat ini
Variabel lingkungan _NT_SYMBOL_PATH
Variabel lingkungan _NT_ALTERNATE_SYMBOL_PATH

Perhatikan bahwa jalur pencarian juga dapat diatur menggunakan fungsi SymSetSearchPath .

[in] fInvadeProcess

Jika nilai ini TRUE, menghitung modul yang dimuat untuk proses dan secara efektif memanggil fungsi SymLoadModule64 untuk setiap modul.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah TRUE.

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

Keterangan

Fungsi SymInitialize digunakan untuk menginisialisasi penangan simbol untuk proses. Dalam konteks penangan simbol, proses adalah objek yang nyaman digunakan saat mengumpulkan informasi simbol. Biasanya, penangan simbol digunakan oleh debugger dan alat lain yang perlu memuat simbol untuk proses yang sedang di-debug.

Handel yang diteruskan ke SymInitialize harus berupa nilai yang sama yang diteruskan ke semua fungsi handler simbol lainnya yang dipanggil oleh proses. Ini adalah handel yang digunakan fungsi untuk mengidentifikasi pemanggil dan menemukan informasi simbol yang benar. Setelah Anda selesai menggunakan informasi simbol, panggil fungsi SymCleanup untuk membatalkan alokasi semua sumber daya yang terkait dengan proses yang simbolnya dimuat.

Pencarian file simbol dilakukan secara rekursif untuk semua jalur yang ditentukan dalam parameter UserSearchPath . Oleh karena itu, jika Anda menentukan direktori akar dalam pencarian, seluruh drive dicari, yang dapat memakan waktu signifikan. Perhatikan bahwa direktori yang berisi file yang dapat dieksekusi untuk proses ini bukan bagian otomatis dari jalur pencarian. Untuk menyertakan direktori ini di jalur pencarian, panggil fungsi GetModuleFileNameEx , lalu tambahkan jalur yang dikembalikan ke UserSearchPath.

Proses yang memanggil SymInitialize tidak boleh memanggilnya lagi kecuali memanggil SymCleanup terlebih dahulu. Jika panggilan ke SymInitialize mengatur fInvadeProcess ke TRUE dan Anda hanya perlu memuat ulang daftar modul, gunakan fungsi SymRefreshModuleList .

Semua fungsi DbgHelp, seperti ini, adalah utas 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, panggil SymInitialize hanya ketika proses Anda dimulai dan SymCleanup hanya ketika proses Anda berakhir. Tidak perlu bagi setiap utas dalam proses untuk memanggil fungsi-fungsi ini.

Untuk memanggil versi Unicode dari fungsi ini, tentukan DBGHELP_TRANSLATE_TCHAR.