DBG_C_Connect

Debug Command 21 - Connect To Debuggee Command

Parameters

Addr= Possible values are shown in the list below:
0x00000000The default action is to sever the connection between the debugger and the program being debugged if a system resource is being held.

0x00000001The 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_Connect
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. No other DosDebug command will be accepted until the debugging connection has been established.

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 automatically start a different debugger process that uses a different buffer format.

For this command, only the machine-independent 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

If the connection to the debuggee is not established within a reasonable amount of time, it is assumed that the connection will never be established, and the debuggee process is terminated automatically.

The current format level may or may not be supported in future versions. This is due to the machine dependence of the DosDebug function.

Remarks

If Addr is set to 0, the connection between the debugger and the program being debugged is not severed. If any debuggee threads, 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 debugger/debuggee connection is severed by terminating the debuggee, 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 debuggee, 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 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 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.