tutorial 28: win32 debug api part 1
in this tutorial, you'll learn what win32 offers to developers regarding debugging primitives. you'll know how to debug a process when you're finished with this tutorial.
theory:
win32 has several apis that allow programmers to use some of the powers of a debugger. they are called win32 debug apis or primitives. with them, you can:
- load a program or attach to a running program for debugging
- obtain low-level information about the program you're debugging, such as process id, address of entrypoint, image base and so on.
- be notified of debugging-related events such as when a process/thread starts/exits, dlls are loaded/unloaded etc.
- modify the process/thread being debugged
in short, you can code a simple debugger with those apis. since this subject is vast, i divide it into several managable parts: this tutorial being the first part. i'll explain the basic concepts and general framework for using win32 debug apis in this tutorial.
the steps in using win32 debug apis are:
- create a process or attach your program to a running process. this is the first step in using win32 debug apis. since your program will act as a debugger, you need a program to debug. the program being debugged is called a debuggee. you can acquire a debuggee in two ways:
- you can create the debuggee process yourself with createprocess. in order to create a process for debugging, you must specify the debug_process flag. this flag tells windows that we want to debug the process. windows will send notifications of important debugging-related events (debug events) that occur in the debuggee to your program. the debuggee process will be immediately suspended until your program is ready. if the debuggee also creates child processes, windows will also send debug events that occur in all those child processes to your program as well. this behavior is usually undesirable. you can disable this behavior by specifying debug_only_this_process flag in combination of debug_process flag.
- you can attach your program to a running process with debugactiveprocess.
- wait for debugging events. after your program acquired a debuggee, the debuggee's primary thread is suspended and will continue to be suspended until your program calls waitfordebugevent. this function works like other waitforxxx functions, ie. it blocks the calling thread until the waited-for event occurs. in this case, it waits for debug events to be sent by windows. let's see its definition:
waitfordebugevent proto lpdebugevent:dword, dwmilliseconds:dword
lpdebugevent is the address of a debug_event structure that will be filled with information about the debug event that occurs within the debuggee.
dwmilliseconds is the length of time in milliseconds this function will wait for the debug event to occur. if this period elapses and no debug event occurs, waitfordebugevent returns to the caller. on the other hand, if you specify infinite constant in this argument, the function will not return until a debug event occurs.
now let's examine the debug_event structure in more detail.
debug_event struct
dwdebugeventcode dd ?
dwprocessid dd ?
dwthreadid dd ?
u debugstruct <>
debug_event endsdwdebugeventcode contains the value that specifies what type of debug event occurs. in short, there can be many types of events, your program needs to check the value in this field so it knows what type of event occurs and responds appropriately. the possible values are:
value meanings create_process_debug_event a process is created. this event will be sent when the debuggee process is just created (and not yet running) or when your program just attaches itself to a running process with debugactiveprocess. this is the first event your program will receive. exit_process_debug_event a process exits. create_thead_debug_event a new thread is created in the debuggee process or when your program first attaches itself to a running process. note that you'll not receive this notification when the primary thread of the debuggee is created. exit_thread_debug_event a thread in the debuggee process exits. your program will not receive this event for the primary thread. in short, you can think of the primary thread of the debuggee as the equivalent of the debuggee process itself. thus, when your program sees create_process_debug_event, it's actually the create_thread_debug_event for the primary thread. load_dll_debug_event the debuggee loads a dll. you'll receive this event when the pe loader first resolves the links to dlls (you call createprocess to load the debuggee) and when the debuggee calls loadlibrary. unload_dll_debug_event a dll is unloaded from the debuggee process. exception_debug_event an exception occurs in the debuggee process. important: this event will occur once just before the debuggee starts executing its first instruction. the exception is actually a debug break (int 3h). when you want to resume the debuggee, call continuedebugevent with dbg_continue flag. don't use dbg_exception_not_handled flag else the debuggee will refuse to run under nt (on win98, it works fine). output_debug_string_event this event is generated when the debuggee calls debugoutputstring function to send a message string to your program. rip_event system debugging error occurs dwprocessid and dwthreadid are the process and thread ids of the process that the debug event occurs. you can use these values as identifiers of the process/thread you're interested in. remember that if you use createprocess to load the debuggee, you also get the process and thread ids of the debuggee in the process_info structure. you can use these values to differentiate between the debug events occurring in the debuggee and its child processes (in case you didn't specify debug_only_this_process flag).
u is a union that contains more information about the debug event. it can be one of the following structures depending on the value of dwdebugeventcode above.
value in dwdebugeventcode interpretation of u create_process_debug_event a create_process_debug_info structure named createprocessinfo exit_process_debug_event an exit_process_debug_info structure named exitprocess create_thread_debug_event a create_thread_debug_info structure named createthread exit_thread_debug_event an exit_thread_debug_event structure named exitthread load_dll_debug_event a load_dll_debug_info structure named loaddll unload_dll_debug_event an unload_dll_debug_info structure named unloaddll exception_debug_event an exception_debug_info structure named exception output_debug_string_event an output_debug_string_info structure named debugstring rip_event a rip_info structure named ripinfo
