Loading Executable
  Running Processes
  Run Options
    Static Init
  Source Files
  GUI Display
    Source File List
    Call Frame
    Function Name
  Remote Debugging
    Auto Startup
    Manual Startup
  Multi-Language Programs
  Command Line Options
Tech Support
What's New?
Price List
Tech Support
Who We Are
What We Offer
What's New @ KAI
Tech Support
Contact KAI
Online Documentation

General Instructions for KAI C++ Debugger
Version 3.4, June, 1999

How the KAI C++ Debugger works

The KAI C++ Debugger has two parts, a graphic user interface and the debugger kernel. These two parts communicate through a socket and need not run on the same computer. The kdb command launches the debugger kernel, which in turn starts the GUI. The debugger kernel selects an open port for communication between the kernel and the GUI.

The GUI can run on any machine that has a fairly recent version of the Java Development Kit (JDK 1.1.5 or later) and the Swing support library.

Starting the debugger

Start the debugger with

kdb [executable]

The executable to be loaded can be given on the kdb command line or through the Edit...Options menu. Command line arguments for the program being debugged can be set via the Edit...Options menu. Occasionally, it is necessary to use some command line options for kdb as well.

For best results, compile the program to be debugged with

KCC +K0 --no_kdebug.

To begin execution of the program being debugged, click on Run, Step, Step In or Continue buttons, or select an option from the Debug menu list.

Stdin, stdout and stderr will remain directed to the window where you started the debugger with the kdb command. Starting and terminating an execution of the debugged program will be marked in that window also. All other debugger output is directed through the debugger's own windows

To set a breakpoint, click on the desired line in the Source Window

Loading the executable

The executable to be loaded can be given on the kdb command line or through the Edit...Options menu item.

Command line arguments for the program being debugged can be set via the Edit...Options menu item.

To start the program being debugged, click on "Run", "Step", "Step In" or "Continue" buttons, or select an option from the Debug menu list.

To restart the program from the beginning choose click on the "Run" button or choose the "Run from Beginning" option from the Debug menu. This will restart the program even if an image is already loaded and running.

Stdin, stdout and stderr will remain directed to the window where you start the debugger. This allows the usual interaction with the program being debugged, while the GUI handles the debugging functions in its own windows.

Accelerator keys have been defined for most operations such as run, step, step-in, continue, etc.. The drop-down menues describe available keys.

Debugging an existing process

Attaching to an existing process

The debugger can attach to a currently running process. To do this, start the debugger as if you were debugging the executable, that is "kdb ", where is the name of the program that is running. Then, instead of clicking "Run", choose menu item Debug..Attach_to_Running_Process. You will be prompted for the PID of the process.

It is often the case the when you attach to a process, the process is executing I/O in the C library. If this happens there might not be much debug information available for the debugger and consequently the GUI may be lacking source files, call stack and so on. This varies from platform to platform, and is especially a problem with HP-UX. In any case, clicking "Step" will catch the program when it returns to user code. If the program is waiting for input, however, "Step" will simply allow it to continue waiting in the I/O routines.

Detaching a process

When a program is loaded and stopped, it is possible to disengage the KAI Debugger from that process and leave it running. To do this choose menu item Debug..Detach.

This may be useful if you have a long-running program that you do not wish to start and stop frequently. In this case Attach/Detach will allow you to find the state of the program as it runs.

Another use for detach is if you wish to use other tools to display the state of your program, for instance to see machine registers or disassembly. Since the KAI Debugger is intentionally a high-level C++ debugger, this method is provided to use other analysis tools such as gdb, with complementary functionality.

Program run options

The following commands are available as menu options, keyboard shortcuts and/or GUI buttons:

Normal program I/O will appear in the window where the debugger was started. Starting and terminating an execution of the debugged program will be marked in that window.

If a new executable is detected before a Continue, Step, Step In, or Step Out instruction, a dialog box will appear asking if you want to continue running the same executable or load the new one. When re-running an executable the newest one is automatically loaded.

Setting Breakpoints

The simplest way to set a breakpoint is to find the line in the source window and click in the gray space immediately to the right of the line number.

A red indicator spot should appear by the line number when there is a breakpoint set for that line.

You can also select a line in the source window and use the "Debug...Set Breakpoint on Selection" menu option.

To clear a breakpoint, click on the red indicator by the line number or select the line and clear it using the Debug menu.

Breakpoints in Static Initialization Code

C++ global objects that require initialization cause code to be executed as the program is loaded, i.e. before the first line of main() is executed. You can set breakpoints in static initialization code just like you would in any other part of your program. When the breakpoint is encountered, the call stack will show a call frame with the name "()", and show the file and line number where the initialization is taking place.

It is not possible to breakpoint in static initialization code that is executed in the course of loading a shared librray.

Source file navigation

The source window should display the file that contains the main() routine. The source files window lists the files used by the program. Selecting a line from the source files window will display that file in the main debugger window.

When the program is stopped, selecting different call stack frames will bring up the source window that contains the execution point of the selected function.

See section on specifying alternate source file directories under Debugging Environment.


The debugger will, by default, stop when an exception is being thrown. It can also stop when the exception is caught. Automatic breakpoint at throw and catch can be set in the Debug...Options menu.

When the debugger stops the condition of the throw and the object being caught can be examined through the Expression Window.

Debugging Environment

The Debug..Options... menu item allows you to modify various parameters of the debugging session:

Some aspects of the debug environment are preserved from one kdb invocation to the next. This information is saved in a user preferences file .KDBPrefs, in your home directory. The preserved informations includes the following:

GUI Display

The top-level debugger window has 4 main sub-windows:

In addition, a Function Name Window displays the names of functions found in the program (not including shared libraries).

The subwindows can be resized and rearranged to meet the needs of a particular debugging session. The window ordering is preserved from one invocation of the debugger to the next.

A default horizontal or vertical tiling of the windows can be selected from the Windows menu. The initial gui state is a horizontal tiling.

Specific windows can also be enabled or disabled using the Windows menu.

GUI Fonts

The fonts used in different display windows can be controlled through the Debug...Options menu. If a part of the display is hard to see, you should change the font for that window to get one that displays better on your monitor.

Source File List Window

The source files window lists the files used by the program. Clicking on a line in this window brings up that source file in the Source Window.

This window may display the full file path or just the file name, depending on the configuration selected under Edit..Options..Misc. On some platforms the file path is relative to the current directory, on other platforms the path is absolute. When the path is relative, alternate search paths can be given under the Edit..Options..Program menu item. (See Debugging Environment)

Source Window

Initially, the source window should display the file that contains the main() routine. A blue arrow indicates the current execution location in the program. Outlined blue arrows indicate function call sites leading to the current execution location.

There are several actions that switch files displayed and automatically position the source window to the appropriate line:

Call Frame Window

The call frame stack is displayed whenever the program is stopped. Each line should correspond to one function on the call stack. Clicking on a call frame line will display that call site in the source window.

A button to the left of a call frame line means that the function has local variables that can be displayed. Clicking on this button will display the local variables. All local variables in the function are displayed, even if they belong to a nested lexical scope.

The local variable display works like the general expression window described below. All expressions are initially "locked" to call stack context where they belong.

Expression Window

The Expression Window displays the current value of variables and expressions in the program. It is updated whenever the program stops.

You can adjust the width of the fields in the display by dragging the field separators.

If a round button appears to the left of the expression, the expression can be expanded to show class members or dereferenced pointers. This allows you to navigate down a data structure without typing new expressions.

Expressions can be locked to a specific call frame or float in the current context. The green "U" and red "L" indicate the current state of an expression. A locked expression is always interpreted as if the locked stack frame were on the top of the stack. A floating or unlocked expression is interpreted in the current context where the program is stopped.

Functions can be called from the expression window. At present only non-overloaded non-virtual functions can be called. Any output from a called function will appear in the window that started the debugger, together with all other program output. When calling a global function use the unmangled name and enter the function call as you would in the current program context.

The interface supports a collection of useful operators. These operators include arithmetic, post/pre-inc/decrement, pointer deference (*), address-of, direct and indirect member selection, cast, function call and subscript operators. A more complete list of operator limitations listed in the known problems section.

Function Name Window

The Function Name Window displays a list of functions defined in the application. The "Show Source" button will display the source to the function in the Source Window. The "Set Breakpoint" will set a breakpoint at the beginning of the function.

This window is now shown until requested. To display the Functions Window, click menu option Windows..Show_Functions_Window. The window is initially empty, because it could contain a very large number of very long function names. As you type in the name of the function you are looking for, the functions that match the prefix you have entered will appear in the window. You can then click on the complete function name to select it.

Remote Debugging

Automatic startup of debugger and gui on separate machines

Starting with version 1.1e, the kdb command supports debugging on a remote host with the graphic display on your local host. The debug session is started by a command on the remote host.

Requirements for remote debugging:

To start a remote debug session with a local gui display enter this command on the remote system.

kdb -gh {gui_host} {program}.
where {gui_host} is your local host, and {program} is the program to be debugged.

Manually startup of debugger and gui on separate machines

On the remote machine where the debugging is to take place, start the debugger kernel with the command
If the bin/ directory for the KAI C++ Debugger is not on your path, you may need to specify the full path to the executable kdb_kernel. This command will print a message saying it is waiting for a connection (from a graphic user interface), and stating the host and port number on which it is expecting to connect.

On the local machine where you want the gui to run, start the gui with this command

kdb -guionly -dh host -dp port progname
where host and port are the host name and port number given by the kdb_kernel command, above, and progname is the name of the executable to debugged.

Multi-language programs

Under Linux with version 1.1b, it is possible to view Fortran routines called from a C/C++ program. The Fortran source will be displayed, allowing you to set breakpoints, step through the program, etc.. The expression window will use C/C++ syntax to access the Fortran data, so, for instance, C array syntax must be used to access Fortran arrays.

Command Line Options

Under normal operating conditions, there should be no need to specify any command line options to kdb.

The following command line options are provided in case particular situations require them.

If your environment requires you to set these one or more of these options on a regular basis, we would appreciate it if you would contact and explain your situation so that we could understand why the options are necessary for you.


-prog <pathname>

   The path of the program to debug. This can also be set with the Edit...Options menu entry.

-pid <process_id>

   A process to which the debugger should attach. See notes below on interaction with -prog. Attaching to a process can also be done after the GUI has started, with the Debug..Attach menu entry.

-dh <host_name>

  The host name of the machine where the debugger kernel will be running. This is the machine where the application runs. Normally this option is only used in conjunction with -guionly

-dp <port_number>

  The port number used to communicate between the GUI and the debugger. The port number is normally selected automatically.

-gh <gui_host>

  The host name where the gui should be run when remote debugging.

-guidir <pathname>

  The path to an alternate graphic user interface


  Starts only the graphic interface for the debugger. Normally only used for remote debugging

-debugdir <pathname>

  The path to an alternate debugger kernel



Any command line argument other than the above is assumed to be the program name. Thus the -prog keyword is optional. The command

kdb prog_name
is equivalent to
kdb -prog prog_name

When -prog and -pid are both specified, the debugger does not verify that the executable matches the actual process executing. When using -pid alone, the debugger attempts to find the executable file but may not be successful. -pid can generally be used alone (without -prog) when the debugger is run in the same directory where the executable file exists.

Version 3.4 limitations


Copyright © 1999 by Kuck & Associates, Inc. All rights reserved.