Table of Contents

Although WinGDB offers a comprehensive and easy user interface, you sometimes might want to access GDB directly through its command interface. This chapter describes several ways to do it. These are:

Debugger command shell window

This is a window which allows you to enter commands for GDB and read their results. You can enter most commands and they will behave just as typed during GDB text interaction session -- with some exceptions decribed below.

Virtualization and command categories

These exceptions are the result of virtualization of the console. In fact, there is a group of commands which is not being sent to GDB directly. Instead they are interpreted on WinGDB side and executed "through" Visual Studio, so that VS GUI gets updated correctly. It concerns all commands which alter state of the debugger: change breakpoints or current frame, step, run, etc.

The second problem the virtualization solves is the fact that WinGDB uses GDB/MI interface to communicate with GDB. This is alternative command syntax, designed for unambiguous communication with front-ends (like WinGDB). However, the command shell window accepts CLI commands (traditional syntax for humans) and these commands are translated internally to MI. There is also small fraction of CLI commands which have no MI counterparts -- they are not supported in the console. All such commands are redundant and rarely used.

Another group of commands are "harmless" ones. They do not change anything but only query for some information. WinGDB passes them directly to GDB. All info and show commands belong to this category, as well as some others.

The final category are the commands that WinGDB just do not recognize. They are also passed directly (so you can use them), but WinGDB displays a warning that result might be unpredictable. Use such commands at your own risk!

Using the shell window

To display the shell window, use Show debugger command window option from WinGDB menu. The window is a text console in which you can type the commands and view the results.

There are also several buttons:

The Raw mode button can be useful when you really want to give GDB some command directly. WinGDB will not alter what you type. This is potentially dangerous. Use this mode only when you know what you are doing. It is meant for GDB experts only. Since WinGDB does not touch your commands, no behavior occurring in this mode is considered as a bug in WinGDB!

In the console, you can type help wingdb to get a list of virtualized, safe and unsupported commands.

Command context

Commands which are recognized by WinGDB work in current program context (thread and stack frame) as selected in Visual Studio. Unrecognized and raw mode commands do not give such guarantee.

Old Visual Studio versions

The command console relies on some Visual Studio functionality which is available only in VS 2008 SP1 and newer. This should be not much problem, as VS 2005 is really ancient and SP1 is freely available for VS 2008 users. If you use such an old version and encounter a message from the console regarding it, please consider upgrading your Visual Studio.

Debugger log window

It is sometimes desirable to view actual communication between WinGDB and GDB -- due to curiosity or diagnostic purposes. WinGDB offers the file-based logging facility for that, but also there is special window which shows the command and responses in real time.

To display the log window, use Show debugger log window option from WinGDB menu.

The window is a read-only text console in which you can view the commands sent to GDB and results.

Note that the window has different purpose from the command shell window described in previous section. The log window is not virtualized, it shows actual communication as is. You can view what's going on behind the scenes. Also, by comparing what is typed in the shell window with actual commands in the log window, you can see how complex the translation is. The complexity arises because of two things: usage of the machine interface (MI) in GDB and Visual Studio GUI queries occurring in real time.

The debugger log window can wrap long lines. This feature is controlled by the Wrap button, you can turn it on or off.

Also note that the log window is intentionally read-only. This is not a bug. In order to type GDB commands directly, please use the Command shell window described in previous section.

Custom initialization scripts

Sometimes it is necessary to run some commands just after debugger has been started. WinGDB supports such case through custom initialization scripts. User can provide path to script in dialog Launch Process, Attach Process or Examine Core Dump in field 'Custom initialization script'.

Syntax of script is simple. Single line may contain only one gdb command or comment, eventually it is empty. Line is treated as comment if it begins with two slashes (//) or hash (#). Blank characters at the beginning of line are ignored. There is no limit for number of lines.

Sample of script (there are two empty lines intentionally):
Output generated by script is redirected into Visual Studio console (pane "Debug").

CAUTION!
All commands are allowed to run through custom initialization script, but please proceed with them carefully, because they may change the way GDB bahaves and introduce negative side-effects for WinGDB operations. Custom scripts are currently not virtualized (as opposed to the debugger command console, described above).

All breakpoints set through custom initialization script are not visible in Visual Studio environment, but GDB sees them and reacts as usually.


Currently WinGDB supports scripts which are located on local file system only. If there is need to run scripts which are located on remote machine, then please let us know about it. The same if you have any problems with custom initialization scripts.

Custom runtime scripts

In addition to initialization scripts, WinGDB supports execution of custom GDB scripts at arbitrary moments during debugging (however the debugger must be stopped). These scripts may be bound to menu commands for convenience. This way, you can use some extended features of GDB even though WinGDB does not support them directly. This can be especially useful on embedded systems.

Defining scripts

In order to define a custom script, open the User scripts submenu from WinGDB menu.

The first option opens the Custom script manager window, which allows you to define up to eight scripts and bind them to commands in the menu. Remaining options are corresponding commands which have been bound. After selecting the first option, the following dialog appears:

Click on one of the rows on the left side. You will be able to edit a script which is bound to that particular command. Enter the name of the command in User command name field and the contents of the script below. After clicking OK or Apply your script will be saved. You may edit an existing script as well.

Executing scripts

In order to execute as script, just select corresponding option from the User scripts menu. The debugging session must be active and the debugger must be stopped, otherwise the command will be disabled.

Limitations and warnings

The following limitations and warnings apply to custom scripts.

Table of Contents


Copyright (C) 2008-2016 SOFT-ERG. All rights reserved.