Fungsi StackWalk2 (dbghelp.h)

Artikel
02/05/2025

Mendapatkan jejak tumpukan.

Sintaksis

BOOL IMAGEAPI StackWalk2(
  [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, optional] PGET_TARGET_ATTRIBUTE_VALUE64    GetTargetAttributeValue,
  [in]           DWORD                            Flags
);

Parameter

[in] MachineType

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

Nilai	Arti
IMAGE_FILE_MACHINE_I386 0x014c	Intel x86
IMAGE_FILE_MACHINE_IA64 0x0200	Intel Itanium
IMAGE_FILE_MACHINE_AMD64 0x8664	x64 (AMD64 atau EM64T)
IMAGE_FILE_MACHINE_ARM64 0xaa64	ARM64

[in] hProcess

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

[in] hThread

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

[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 ARM64_NT_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 StackWalk2 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 StackWalk2 perlu membaca memori dari ruang alamat proses, fungsi panggilan balik 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 tidak NULL, aplikasi harus menerapkan dan mendaftarkan fungsi panggilan balik penangan 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 StackWalk2 tidak memiliki akses ke tabel fungsi run-time proses. Untuk informasi selengkapnya, lihat fungsi panggilan balik FunctionTableAccessProc64.

Handler simbol menyediakan fungsi yang memuat dan mengakses tabel run-time. Jika fungsi-fungsi ini digunakan, fungsi 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 fungsi panggilan balik PGET_MODULE_BASE_ROUTINE64.

Handler simbol menyediakan fungsi yang memuat dan memelihara informasi modul. Jika fungsi-fungsi ini digunakan, fungsi 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 fungsi panggilan balik PTRANSLATE_ADDRESS_ROUTINE64.

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

[in, optional] GetTargetAttributeValue

Rutinitas panggilan balik yang menyediakan nilai atribut target yang diperlukan untuk berjalan di tumpukan. Untuk informasi selengkapnya, lihat fungsi panggilan balik PGET_TARGET_ATTRIBUTE_VALUE64.

Banyak penelepon StackWalk2 dapat dengan aman melewati NULL untuk parameter ini. Penelepon pada platform ARM64 yang dapat menggunakan autentikasi pointer harus menyediakan panggilan balik.

[in] Flags

Kombinasi bendera nol atau lebih.

SYM_STKWALK_DEFAULT (0)

SYM_STKWALK_FORCE_FRAMEPTR (1)

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian TRUE.

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

Komentar

Fungsi StackWalk2 menyediakan metode portabel untuk mendapatkan jejak tumpukan. Menggunakan fungsi StackWalk2 direkomendasikan untuk 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 AddrStack anggota struktur STACKFRAME64 yang diteruskan dalam parameter StackFrame tidak diinisialisasi.

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.