msos2.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.
PTRACEBUF (1.2)
Changes                                             Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSTRACE
 
typedef struct _PTRACEBUF {    /* ptrcbf */
    PID    pid;
    TID    tid;
    USHORT cmd;
    USHORT value;
    USHORT offv;
    USHORT segv;
    USHORT mte;
    USHORT rAX;
    USHORT rBX;
    USHORT rCX;
    USHORT rDX;
    USHORT rSI;
    USHORT rDI;
    USHORT rBP;
    USHORT rDS;
    USHORT rES;
    USHORT rIP;
    USHORT rCS;
    USHORT rF;
    USHORT rSP;
    USHORT rSS;
} PTRACEBUF;
 
The PTRACEBUF structure contains various debugging information.
 
Field  Description
────────────────────────────────────────────────────────────────────────────
 
pid    Specifies the process identifier of the program being debugged.
 
tid    Specifies the thread identifier of the program being debugged.
 
cmd    Specifies the command to carry out. It can be one of the following
       values:
 
       Value   Meaning
       ─────────────────────────────────────────────────────────────────────
       0x0001  Read memory instruction space (I-space).
 
       0x0002  Read memory data space (D-space).
 
       0x0003  Read registers.
 
       0x0004  Write memory I-space.
 
       0x0005  Write memory D-space.
 
       0x0006  Write registers.
 
       0x0007  Begin execution.
 
       0x0008  Terminate child process.
 
       0x0009  Single step.
 
       0x000A  Suspend child process.
 
       0x000B  Freeze child process.
 
       0x000C  Resume child process.
 
       0x000D  Convert segment number to selector.
 
       0x000E  Get floating-point registers. The segv and offv fields must
               specify the address of a 94-byte buffer that receives the
               floating-point register values.
 
       0x000F  Set floating-point registers. The segv and offv fields must
               specify the address of a 94-byte buffer that contains the
               floating-point register values.
 
       0x0010  Get library-module name. The value field must contain the
               handle of the library module. The segv and offv fields must
               contain the address of the buffer that receives the name.
               This command should be used instead of the DosGetModHandle
               and DosGetModName functions to verify the name of a library
               loaded by the program being debugged.
 
       0x0011  Get the thread identifier of the next thread. This field is
               circular; to read the registers of all threads in the
               process, use this value until a thread identifier is
               repeated. For more information about this value, see the
               "Comments" section.
 
       When the command identified in the cmd field returns, it copies a
       code to the value field that specifies the result of the command. The
       return code can be one of the following values:
 
       Value   Meaning
       ─────────────────────────────────────────────────────────────────────
       0x0000  Success return code.
 
       0xFFFF  Error. The error code is in the value field.
 
       0xFFFE  About to receive signal.
 
       0xFFFD  Single-step interrupt.
 
       0xFFFC  Hit break point.
 
       0xFFFB  Parity error.
 
       0xFFFA  Process dying.
 
       0xFFF9  General protection fault. The fault type is in the value
               field. The segv and offv fields contain the address that
               caused the fault.
 
       0xFFF8  Library module has just been loaded. The value field contains
               the library-module handle.
 
       0xFFF7  Process has not used 287 yet.
 
       0xFFF6  Thread ending.
 
       0xFFF5  Asynchronous stop.
 
value  Specifies the value to be used for a given command or a return value
       from a command. If an error occurs, this field is set to one of the
       following values:
 
       Value   Meaning
       ─────────────────────────────────────────────────────────────────────
       0x0001  Bad command.
 
       0x0002  Child process not found.
 
       0x0005  Child process untraceable.
 
offv   Specifies the offset from the given segment.
 
segv   Specifies the segment selector.
 
mte    Identifies the handle of the module that contains the segment.
 
rAX    Specifies the ax register.
 
rBX    Specifies the bx register.
 
rCX    Specifies the cx register.
 
rDX    Specifies the dx register.
 
rSI    Specifies the si register.
 
rDI    Specifies the di register.
 
rBP    Specifies the bp register.
 
rDS    Specifies the ds register.
 
rES    Specifies the es register.
 
rIP    Specifies the ip register.
 
rCS    Specifies the cs register.
 
rF     Specifies flags.
 
rSP    Specifies the sp register.
 
rSS    Specifies the ss register.
 
Comments
 
The 0x0011 value in the cmd field causes a thread identifier to be
retrieved. The status of this thread is returned in a ThreadStatus buffer
pointed to by the segv and offv fields. The format of the ThreadStatus
buffer is as follows:
 
struct ThreadStatus {
    UCHAR  fDebugState;
    UCHAR  fThreadState;
    USHORT usThreadPriority;
    };
 
The DebugState field contains one of the following values:
 
Value  Meaning
────────────────────────────────────────────────────────────────────────────
0      Thread not frozen by debugger.
1      Thread frozen by debugger.
 
The ThreadState field contains one of the following:
 
Value  Meaning
────────────────────────────────────────────────────────────────────────────
0      Thread can be run.
1      Thread is suspended.
2      Thread is blocked.
3      Thread state is a critical section.
 
The ThreadPriority field receives the priority of the specified thread. The
high byte receives the priority class, and the low byte receives the
priority level.
 
See Also
 
DosGetModHandle, DosGetModName, DosPTrace