dos12.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
DosPTrace (1.2)
                                                      Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSTRACE
 
USHORT DosPTrace(pvPtraceBuf)
PVOID pvPtraceBuf;    /* pointer to structure receiving register values */
 
The DosPTrace function provides access to the MS OS/2 debugging functions.
These debugging functions are available to any process that starts a
protected-mode child process by using the DosExecPgm function with the
fExecFlags parameter set to EXEC_TRACE.
 
Parameter    Description
────────────────────────────────────────────────────────────────────────────
 
pvPtraceBuf  Points to the PTRACEBUF structure that receives the current
             values of the child process's registers and a code that
             indicates the reason for returning.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_ACCESS_DENIED
     ERROR_INVALID_FUNCTION
     ERROR_INVALID_PROCID
 
Comments
 
To use the DosPTrace function, you need to provide the following function
prototype in your source file:
 
    USHORT DosPTrace(PVOID);
 
The DosPTrace function lets a parent process control the execution of the
child process and access the child process's memory directly to insert break
points or change data.
 
The parent process starts the child process to be debugged, then stops the
child process by using the DosPTrace function with the cmd field of the
PTRACEBUF structure set to 0x000A. The parent process can then insert break
points or change memory in the child process by using DosPTrace and the cmd
field values. Next, the parent process can start execution by setting the
cmd field to 0x0007 (go until break point) or 0x0009 (single step). The
parent process can set initial register values by setting cmd to 0x0006.
After it is started, the child process returns control to the parent process
if it encounters a break point, a non-maskable interrupt, a single-step
interrupt, or the end of the program.
 
The DosPTrace function can be used to debug a process with multiple threads
by setting the tid field of the PTRACEBUF structure to the identifier of the
thread to be debugged. Other threads in the process are suspended. (The
address space is the same for all threads in a process.) Commands to read
from or write to memory locations or set break points affect all threads in
the process, even if the command is issued with a specific thread
identifier. If the parent process uses the 0x000B command, a selected thread
or group of threads can keep running while others are suspended. This allows
only the selected threads to be affected by the break points and
manipulated.
 
See Also
 
DosExecPgm, DosGetInfoSeg, PTRACEBUF