Export (0) Print
Expand All

WaitForDebugEvent function

Waits for a debugging event to occur in a process being debugged.

Syntax


BOOL WINAPI WaitForDebugEvent(
  _Out_  LPDEBUG_EVENT lpDebugEvent,
  _In_   DWORD dwMilliseconds
);

Parameters

lpDebugEvent [out]

A pointer to a DEBUG_EVENT structure that receives information about the debugging event.

dwMilliseconds [in]

The number of milliseconds to wait for a debugging event. If this parameter is zero, the function tests for a debugging event and returns immediately. If the parameter is INFINITE, the function does not return until a debugging event has occurred.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Only the thread that created the process being debugged can call WaitForDebugEvent.

When a CREATE_PROCESS_DEBUG_EVENT occurs, the debugger application receives a handle to the image file of the process being debugged, a handle to the process being debugged, and a handle to the initial thread of the process being debugged in the DEBUG_EVENT structure. The members these handles are returned in are u.CreateProcessInfo.hFile (image file), u.CreateProcessInfo.hProcess (process), and u.CreateProcessInfo.hThread (initial thread). If the system previously reported an EXIT_PROCESS_DEBUG_EVENT debugging event, the system closes the handles to the process and thread when the debugger calls the ContinueDebugEvent function. The debugger should close the handle to the image file by calling the CloseHandle function.

Similarly, when a CREATE_THREAD_DEBUG_EVENT occurs, the debugger application receives a handle to the thread whose creation caused the debugging event in the u.CreateThread.hThread member of the DEBUG_EVENT structure. If the system previously reported an EXIT_THREAD_DEBUG_EVENT debugging event, the system closes the handles to the thread when the debugger calls the ContinueDebugEvent function.

When a LOAD_DLL_DEBUG_EVENT occurs, the debugger application receives a handle to the loaded DLL in the u.LoadDll.hFile member of the DEBUG_EVENT structure. This handle should be closed by the debugger application by calling the CloseHandle function.

Warning  Do not queue an asynchronous procedure call (APC) to a thread that calls WaitForDebugEvent.

Examples

For an example, see Writing the Debugger's Main Loop.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

WinBase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

ContinueDebugEvent
DebugActiveProcess
DebugBreak
DEBUG_EVENT
Debugging Events
Debugging Functions
OutputDebugString

 

 

Community Additions

ADD
Show:
© 2014 Microsoft