Fungsi StackWalkEx (dbghelp.h)

Artikel
02/26/2024

Mendapatkan jejak tumpukan.

Sintaks

BOOL IMAGEAPI StackWalkEx(
  [in]           DWORD                            MachineType,
  [in]           HANDLE                           hProcess,
  [in]           HANDLE                           hThread,
  [in, out]      LPSTACKFRAME_EX                  StackFrame,
  [in, out]      PVOID                            ContextRecord,
  [in, optional] PREAD_PROCESS_MEMORY_ROUTINE64   ReadMemoryRoutine,
  [in, optional] PFUNCTION_TABLE_ACCESS_ROUTINE64 FunctionTableAccessRoutine,
  [in, optional] PGET_MODULE_BASE_ROUTINE64       GetModuleBaseRoutine,
  [in, optional] PTRANSLATE_ADDRESS_ROUTINE64     TranslateAddress,
  [in]           DWORD                            Flags
);

Parameter

[in] MachineType

Jenis arsitektur komputer tempat jejak tumpukan dihasilkan. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
IMAGE_FILE_MACHINE_I386 0x014c	Intel x86
IMAGE_FILE_MACHINE_IA64 0x0200	Intel Itanium
IMAGE_FILE_MACHINE_AMD64 0x8664	x64 (AMD64 atau EM64T)

[in] hProcess

Handel ke proses yang jejak tumpukannya dihasilkan. Jika penelepon menyediakan penunjuk panggilan balik yang valid untuk parameter ReadMemoryRoutine , maka nilai ini tidak harus menjadi handel proses yang valid. Ini bisa menjadi token yang unik dan konsisten sama untuk semua panggilan ke fungsi StackWalkEx . Jika handler simbol digunakan dengan StackWalkEx, gunakan handel proses yang sama untuk panggilan ke setiap fungsi.

[in] hThread

Handel ke utas tempat jejak tumpukan dihasilkan. Jika pemanggil menyediakan penunjuk panggilan balik yang valid untuk parameter ReadMemoryRoutine , maka nilai ini tidak harus menjadi handel utas yang valid. Ini bisa menjadi token yang unik dan konsisten sama untuk semua panggilan ke fungsi StackWalkEx .

[in, out] StackFrame

Penunjuk ke struktur STACKFRAME_EX . Struktur ini menerima informasi untuk bingkai berikutnya, jika panggilan fungsi berhasil.

[in, out] ContextRecord

Penunjuk ke struktur CONTEXT . Parameter ini hanya diperlukan ketika parameter MachineType tidak IMAGE_FILE_MACHINE_I386. Namun, disarankan agar parameter ini berisi rekaman konteks yang valid. Ini memungkinkan StackWalkEx untuk menangani berbagai situasi yang lebih besar.

Konteks ini dapat dimodifikasi, jadi jangan meneruskan rekaman konteks yang tidak boleh dimodifikasi.

[in, optional] ReadMemoryRoutine

Rutinitas panggilan balik yang menyediakan layanan baca memori. Ketika fungsi StackWalkEx perlu membaca memori dari ruang alamat proses, callback ReadProcessMemoryProc64 digunakan.

Jika parameter ini NULL, maka fungsi menggunakan rutinitas default. Dalam hal ini, parameter hProcess harus merupakan handel proses yang valid.

Jika parameter ini bukan NULL, aplikasi harus mengimplementasikan dan mendaftarkan fungsi panggilan balik handler simbol yang menangani CBA_READ_MEMORY.

[in, optional] FunctionTableAccessRoutine

Rutinitas panggilan balik yang menyediakan akses ke tabel fungsi run-time untuk proses tersebut. Parameter ini diperlukan karena fungsi StackWalkEx tidak memiliki akses ke tabel fungsi run-time proses. Untuk informasi selengkapnya, lihat FunctionTableAccessProc64.

Handler simbol menyediakan fungsi yang memuat dan mengakses tabel run-time. Jika fungsi-fungsi ini digunakan, maka SymFunctionTableAccess64 dapat diteruskan sebagai parameter yang valid.

[in, optional] GetModuleBaseRoutine

Rutinitas panggilan balik yang menyediakan basis modul untuk alamat virtual tertentu. Parameter ini diperlukan. Untuk informasi selengkapnya, lihat GetModuleBaseProc64.

Handler simbol menyediakan fungsi yang memuat dan memelihara informasi modul. Jika fungsi-fungsi ini digunakan, maka SymGetModuleBase64 dapat diteruskan sebagai parameter yang valid.

[in, optional] TranslateAddress

Rutinitas panggilan balik yang menyediakan terjemahan alamat untuk alamat 16-bit. Untuk informasi selengkapnya, lihat TranslateAddressProc64.

Sebagian besar penelepon StackWalkEx dapat dengan aman meneruskan NULL untuk parameter ini.

[in] Flags

Kombinasi bendera nol atau lebih.

SYM_STKWALK_DEFAULT (0)

SYM_STKWALK_FORCE_FRAMEPTR (1)

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah TRUE.

Jika fungsi gagal, nilai yang dikembalikan adalah FALSE. Perhatikan bahwa StackWalkEx umumnya tidak mengatur kode kesalahan terakhir.

Keterangan

Fungsi StackWalkEx menyediakan metode portabel untuk mendapatkan jejak tumpukan. Menggunakan fungsi StackWalkEx disarankan daripada menulis fungsi Anda sendiri karena semua kompleksitas yang terkait dengan tumpukan berjalan di platform. Selain itu, ada opsi pengkompilasi yang menyebabkan tumpukan muncul secara berbeda, tergantung pada bagaimana modul dikompilasi. Dengan menggunakan fungsi ini, aplikasi Anda memiliki jejak tumpukan portabel yang terus berfungsi saat kompilator dan sistem operasi berubah.

Panggilan pertama ke fungsi ini akan gagal jika AddrPC,
AddrFrame, dan anggota AddrStack dari struktur STACKFRAME64 yang diteruskan dalam parameter StackFrame tidak diinisialisasi.

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, Anda harus menyinkronkan semua panggilan bersamaan dari lebih dari satu utas ke fungsi ini.