Fungsi StackWalk (dbghelp.h)

Artikel
08/23/2023

Mendapatkan jejak tumpukan.

Sintaks

BOOL IMAGEAPI StackWalk(
  [in]           DWORD                          MachineType,
  [in]           HANDLE                         hProcess,
  [in]           HANDLE                         hThread,
  [in, out]      LPSTACKFRAME                   StackFrame,
  [in, out]      PVOID                          ContextRecord,
  [in, optional] PREAD_PROCESS_MEMORY_ROUTINE   ReadMemoryRoutine,
  [in, optional] PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
  [in, optional] PGET_MODULE_BASE_ROUTINE       GetModuleBaseRoutine,
  [in, optional] PTRANSLATE_ADDRESS_ROUTINE     TranslateAddress
);

Parameter

[in] MachineType

Jenis arsitektur komputer yang jejak tumpukannya 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 secara konsisten sama untuk semua panggilan ke fungsi StackWalk64 . Jika penangan simbol digunakan dengan StackWalk64, gunakan handel proses yang sama untuk panggilan ke setiap fungsi.

[in] hThread

Handel ke utas yang jejak tumpukannya dihasilkan. Jika penelepon 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 secara konsisten sama untuk semua panggilan ke fungsi StackWalk64 .

[in, out] StackFrame

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

[in, out] ContextRecord

Penunjuk ke struktur CONTEXT . Parameter ini diperlukan hanya ketika parameter MachineType tidak IMAGE_FILE_MACHINE_I386. Namun, disarankan agar parameter ini berisi rekaman konteks yang valid. Ini memungkinkan StackWalk64 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 StackWalk64 perlu membaca memori dari ruang alamat proses, 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 bukan NULL, aplikasi harus mengimplementasikan 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 StackWalk64 tidak memiliki akses ke tabel fungsi run-time proses. Untuk informasi selengkapnya, lihat FunctionTableAccessProc64.

Penangan 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.

Penangan 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 StackWalk64 dapat dengan aman melewati NULL untuk parameter ini.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah TRUE.

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

Keterangan

Fungsi StackWalk64 menyediakan metode portabel untuk mendapatkan jejak tumpukan. Menggunakan fungsi StackWalk64 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 sebagai pengkompilasi dan perubahan sistem operasi.

Panggilan pertama ke fungsi ini akan gagal jika anggota AddrPC, AddrFrame, dan 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.

Fungsi ini menggantikan fungsi StackWalk . Untuk informasi selengkapnya, lihat Dukungan Platform yang Diperbarui. StackWalk didefinisikan sebagai berikut dalam DbgHelp.h.

#if !defined(_IMAGEHLP_SOURCE_) && defined(_IMAGEHLP64)
#define StackWalk StackWalk64
#else
BOOL
IMAGEAPI
StackWalk(
    DWORD MachineType,
    __in HANDLE hProcess,
    __in HANDLE hThread,
    __inout LPSTACKFRAME StackFrame,
    __inout PVOID ContextRecord,
    __in_opt PREAD_PROCESS_MEMORY_ROUTINE ReadMemoryRoutine,
    __in_opt PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
    __in_opt PGET_MODULE_BASE_ROUTINE GetModuleBaseRoutine,
    __in_opt PTRANSLATE_ADDRESS_ROUTINE TranslateAddress
    );

#endif