DosDebug

From EDM2
Jump to: navigation, search

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;
    }