DosDebug
Enables the calling application to control another application for debugging purposes.
Syntax
DosDebug(pdbgbuf)
Parameters
- pdbgbuf (PVOID) - input
- Address of a DosDebug Buffer.
Return Code
ulrc (APIRET) - returns
DosDebug returns one of the following values:
- 0 NO_ERROR
- 87 ERROR_INVALID_PARAMETER
- 95 ERROR_INTERRUPT
- 115 ERROR_PROTECTION_VIOLATION
- 328 ERROR_SYS_INTERNAL (this error code applies to PowerPC only)
Remarks
DosDebug maintains a list of system semaphores which it checks before sending any debug notifications to the debugger. DosDebug allows one process (the debugger) to control the execution of another process that is being debugged (the debuggee).
A process must be selected for debugging when it is started. See DosExecPgm or DosStartSession for how this is done. Once a process has been selected for debugging, you must use DosDebug to control and examine its execution.
If no error is returned, a notification resides in the DosDebug Buffer structure. The Cmd field of the DosDebug Buffer structure determines which notification is set. The data returned with the notification varies, depending on the command passed in the Cmd field of the DosDebug Buffer structure.
If the return code is set to ERROR_INTERRUPT, a debug notification might have been lost, depending on the command that was interrupted.
DosDebug can also return with a return value set by another function.
DosDebug allows you to view and modify EXE and DLL code and data objects (those objects defined in the EXE header and loaded by the OS/2 program loader).
In addition to the EXE and DLL code and data objects, DosDebug allows you to view objects allocated dynamically using DosAllocMem. Code or data objects created by other methods may not be accessible.
For details about the commands that are available with DosDebug, see DosDebug Commands.
For details about the notifications that are available with DosDebug, see DosDebug Notifications.
Example Code
The following is NOT a complete C program. It is intended to provide an idea of how to use DosDebug to control another process.
This example illustrates how to modify a word in the process being controlled. It assumes that all the steps have been taken so that the caller controls the other process. It also assumes that the TargetPID, TargetAddr, and NewValue fields have been set appropriately for the operation.
#define INCL_DOSPROCESS /* Process and thread values */ #define INCL_DOSERRORS /* Error values */ #include <os2.h> #include <stdio.h> uDB_t DebugBuf = {0}; /* Debug buffer */ ULONG TargetPID = 0; /* Process ID of controlled process */ ULONG TargetAddr = 0; /* Address within the controlled process */ LONG NewValue = 0; /* Value to be substituted */ APIRET rc = NO_ERROR; /* Return code */ DebugBuf.Cmd = DBG_C_WriteMem; /* Perform WRITE WORD command */ DebugBuf.Pid = TargetPID; /* Target process to control */ DebugBuf.Addr = TargetAddr; /* Target address for command */ DebugBuf.Value = NewValue; /* Value to change in other process */ rc = DosDebug ( &DebugBuf ); if (rc != NO_ERROR) { printf("DosDebug error: return code = %u\n", rc); return 1; }