Debug Command 33 Debug Attach Command
Parameters
Addr
0x00000000
The only permitted debugging level number is shown in the following list
This must be the first DosDebug command called when dynamically attaching to a process. No other DosDebug command will be accepted until the debugging connection has been established except for DBG_C_RegDebug to register a JIT (Just-in-time) debugger on a per-process basis and DBG_C_QueryDebug to query the JIT debug information. See DBG_C_RegDebug and DBG_C_QueryDebug for more information.
Returns
This command establishes a debugging connection. It must be the initial command, since it verifies the buffer format for the rest of the connection.
Because DosDebug usually cannot be ported to new machines without changing the format of the buffer, this command is needed to establish that the debugger is capable of handling the desired buffer format.
If the requested debugging level is not supported, an error is returned, and the connection is not made. This gives the debugger a chance to try again or to start automatically a different debugger process that uses a different buffer format.
For this command, the machine-independent and PID portion of the buffer is examined. This portion includes the Pid, Tid, Cmd, and Value fields. This makes it possible to port the DosDebug buffer from one machine to another without returning an error to the debugger on the initial DosDebug command.
The only DosDebug notifications that are returned by this command are DBG_N_Success and DBG_N_Error.
Restrictions
This DBG_C_Attach command does not require that the session for the program being debugged tohave been started with EXEC_TRACE, or SSF_TRACEOPT_XXX option by DosExecPgm or DosStartSession, as DBG_C_Connect requires.
If a connection to the program being debugged is established by a debugger, then another debug session cannot attach to the program being debugged while the first debugger is attached.
Remarks
If Addr is not 0, the connection between the debugger and the program being debugged is not severed. If any threads of the program being debugged, other than the thread that encountered the debug event, are holding system semaphores, they will be allowed to run until they release the semaphores. They will then be stopped, and the notification will be delivered.
If the thread encountering the debug event is holding a system semaphore, the connection between the debugger and the program being debugged is severed by terminating the program being debugged and returning a DBG_N_Error notification to the debugger with the value field set to 0 and the register set filled in. No further DosDebug commands will be accepted by the program being debugged, nor will it generate any other notifications.
If a DBG_C_Stop is issued, and a thread owning a system semaphore is about to generate a DBG_N_AsyncStop notification, it will be allowed to continue execution until it releases the semaphore. It will then be stopped, and the notification will be delivered. This is the only exception to the severing of the debugger/debugbee rule.
If Addr is set to 0, the connection between the debugger and the program being debugged is severed if a system resource is being held, in which case DosDebug returns
Tid
If the debugger needs to present some information to the user or use the thread holding the system resource, the debugger must terminate the program being debugged. Any other action might result in a system halt.
Upon attach to a process, a series of notifications will occur. The notifications include the current EXE module notification, thread (all that exist in the debuggee) create notifications, and currently loaded modules (DLLs) notifications. The notifications occur as DBG_NPModuleLoad, DBG_N_ThreadCreate, etc, just as they do with the DBG_C_Connect command.