DBG C Attach: Difference between revisions

Latest revision as of 04:31, 16 May 2025

Debug Attach Command. Attach to a Process Command.

Parameters

Addr Possible values are shown in the list below:
- 0x00000000 The default action is to sever the connection between the debugger and the program being debugged, if a system resource is being held.
- 0x00000001 The sever action is not wanted between the debugger and the program being debugged.
Pid Process ID of debuggee
Tid Reserved, must be zero
Cmd DBG_C_Attach
Value Debugging Level Number

The only permitted debugging level number is shown in the following list:

1 = DBG_L_386

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 to have 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/debuggee 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 Thread owning semaphore
Cmd DBG_N_Error
Value ERROR_EXCL_SEM_ALREADY_OWNED

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_N_ModuleLoad, DBG_N_ThreadCreate, etc, just as they do with the DBG_C_Connect command.

@@ Line 1: / Line 1: @@
 {{DISPLAYTITLE:DBG_C_Attach}}
 Debug Attach Command. Attach to a Process Command.
-'''Parameters'''
+;Parameters
 * '''Addr''' Possible values are shown in the list below:
@@ Line 18: / Line 17: @@
 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'''
+;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.
@@ Line 30: / Line 29: @@
 The only DosDebug notifications that are returned by this command are DBG_N_Success and DBG_N_Error.
-'''Restrictions'''
+;Restrictions
 This DBG_C_Attach command does not require that the session for the program being debugged to have been started with EXEC_TRACE, or SSF_TRACEOPT_XXX option by DosExecPgm or DosStartSession, as DBG_C_Connect requires.
@@ Line 36: / Line 35: @@
 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'''
+;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 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/debuggee rule.
+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/debuggee 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''' Thread owning semaphore
-* '''Cmd''' DBG_N_Error
+* '''Cmd''' [[DBG_N_Error]]
 * '''Value''' ERROR_EXCL_SEM_ALREADY_OWNED
 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.
+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_N_ModuleLoad]], [[DBG_N_ThreadCreate]], etc, just as they do with the [[DBG_C_Connect]] command.
 [[Category:Debug Command]]