This manual contains information for debugging programs with the Digital Ladebug debugger. Ladebug is a debugger on the operating system. Digital has changed the name of its UNIX operating system from DEC OSF/1 to Digital UNIX. The new name reflects Digital's commitment to UNIX and its conformance to UNIX standards.
The terms graphical user interface and window interface, as used in this manual, are synonymous. They refer to the window environment available in Digital UNIX.
This manual is intended for programmers with a basic understanding of one of the programming languages that Ladebug supports (C, C++, Ada, COBOL, Fortran, and machine code), and the Digital UNIX operating system.
This manual is organized as follows:
ladebug(1) reference page.
emacs editing environment.
This manual emphasizes debugger usage that is common to all or most supported languages. For more information specific to a particular language, see:
The following documents contain related information:
ladebug(1) , similar to Part V in this manual
cxx(1) for C++
cc(1) for C
ada(1) for Ada
cobol(1) for DEC COBOL
f77(1) for DEC Fortran 77
f90(1) for DEC Fortran 90
The printed version of the Digital UNIX documentation set is color coded to help specific audiences quickly find the books that meet their needs. (You can order the printed documentation from Digital.) This color coding is reinforced with the use of an icon on the spines of books. The following list describes this convention:
| Audience | Icon | Color Code |
|---|---|---|
| General users | G | Blue |
| System and network administrators | S | Red |
| Programmers | P | Purple |
| Device driver writers | D | Orange |
| Reference page users | R | Green |
Some books in the documentation set help meet the needs of several audiences. For example, the information in some system books is also used by programmers. Keep this in mind when searching for information on specific topics.
The Documentation Overview, Glossary, and Master Index provides information on all of the books in the Digital UNIX documentation set.
Digital welcomes any comments and suggestions you have on this and other Digital UNIX manuals. You can send your comments in the following ways:
A Reader's Comment form is located on line in the following location:
/usr/doc/readers_comment.txt
Please include the following information along with your comments:
The Digital UNIX Publications group cannot respond to system problems or technical support inquiries.
Information provided with the software media explains how to send problem reports to Digital. If you need to report a software problem with the Ladebug debugger, contact your local Digital Customer Support Center. Please include as much information as possible to help diagnosis and resolution of the problem. Useful information includes the following:
.i or .ixx file (if the
executable program is compiled with a compiler that supports the
"-P" option)
This manual has been revised to document all of the Ladebug changes that are part of the current release (Version 4.0). They are described in the following sections.
Multiprocess Application Debugging
You can now have multiple processes (zero or more processes) under
debugger control. You can keep track of the processes using the
show process command and switch between them using
the process command, and debug nonrelated processes
simultaneously.
Ladebug supports the debugging of DECthreads and native threads (for
example, Digital UNIX kernel (machine) level threads). You specify
whether you are working with DECthreads or native threads with the
debugger command set $threadlevel , as follows:
(ladebug) set $threadlevel="decthreads" (ladebug) set $threadlevel="native"
The thread command lets you identify or set the current
thread context. The show thread command lists all
threads known to the debugger.
Other commands with enhanced syntax for multithread debugging include:
stop
trace
when
step (and stepi )
next (and nexti )
cont
See the information on each of these commands. See also information
about the where, show condition, and
show mutex commands.
The load command lets you load an image file or core
file for debugging. The unload command removes the
symbol table information that the debugger had associated with the
process being debugged.
Ladebug supports kernel debugging. The functionality is equivalent to kernel debugging using dbx.
When you have a problem with a process, you can debug the running kernel or examine the values assigned to system parameters. (It is generally recommended that you avoid modifying the value of the parameters, which can cause problems with the kernel.) Kernel debugging requires superuser privilege.
To debug a kernel locally, invoke the debugger with the following command:
# ladebug -k
The -k flag maps virtual to physical addresses to
enable local kernel debugging. The /vmunix and
/dev/mem parameters cause the debugger to operate on the
running kernel. Use Ladebug commands to display the current process
identification numbers (pid) and trace the execution of processes.
To debug a remote kernel, invoke the debugger with the following command:
# ladebug -remote /testdir/vmunix
Refer to Chapter 22 for more information about kernel debugging.
Ladebug Version 4.0 enhances language support as follows:
Ladebug's window interface supports the major Ladebug command-line functionality. Other features can be accessed within the window interface from a command window. The window interface includes a main window covering the basic debugging and convenience features; optional views windows, various pop-up menus and dialog boxes, and a command-entry prompt.
Ladebug's window interface is documented in this revised manual. Earlier versions of this manual documented only the command interface.
Support for International Users
User programs may set different locales in order to interpret text according to different language/culture-related criteria. In addition, locales may be switched inside a user program.
Ladebug can follow the debugged program so that its interpretation of program data is identical to that of the debugged user program.
Your Digital UNIX system needs to have the worldwide (WW) subsets installed. This is standard procedure and the WW subsets are available on the base system CD-ROM. You can then set your locale to a special locale (such as a Japanese locale) and input characters which are multibytes. These characters can come from a script or entered from a VT terminal using compose sequences.
Wide characters (type wchar_t) and wide strings (type wchar_t *) are used in international applications as run-time representation of multibyte character data. Ladebug supports input of multibyte characters that are regarded as components of symbol literals, string literals or wide character literals. Ladebug's basic support for wide characters (wchars) and wide strings (wstrings) is as follows:
Environment-Manipulation Commands
Ladebug provides commands for manipulating the environment
of subsequent debuggees with environment variables. With the
setenv, export, printenv, and unsetenv
commands, used within the debugger, you can set the value of
an environment variable, display the values of environment
variables, and remove environment variables. See Chapter 9 for more information.
The pop command removes execution frames from the
call stack. It is useful when execution has passed an error that
needs to be corrected. See Chapter 9 for more
information.
Table 1 lists the conventions used in this manual.
| Convention | Meaning |
|---|---|
| # | A pound sign (#) is the default superuser prompt. |
| [Return] | In examples, a boxed symbol indicates that you must press the named key on the keyboard. |
| Ctrl/C | This symbol indicates that you must press the Ctrl key while you simultaneously press another key (in this case, C). |
user input | In interactive examples, this typeface indicates input entered by the user. |
filesystem
| In text, this typeface indicates the exact name of a command, routine, partition, pathname, directory, or file. This typeface is also used in interactive examples and other screen displays. |
| UPPERCASE lowercase | The Digital UNIX operating system differentiates between lowercase and uppercase characters. On the operating system level, examples, syntax descriptions, function definitions, and literal strings that appear in text must be typed exactly as shown. |
setld(8) | Cross-
references to online reference pages include the appropriate
section number in parentheses. For example, setld(8)
indicates that you can find the material on the setld
command in Section 8 of the reference pages. |
[y] | In a prompt, square
brackets indicate that the enclosed item is the default response.
For example, [y] means the default response
is Yes. |
| file | Italic type indicates variable values, placeholders, function argument names, and names in examples. |
| Actions:Create Group... | Indicates an item on a menu. In this example, you would choose the Create Group... item on the Actions menu. |
| [|] {|} | In syntax definitions, brackets indicate items that are optional and braces indicate items that are required. Vertical bars separating items inside brackets or braces indicate that you choose one item from among those listed. |
| . . . | In syntax definitions, an ellipsis indicates that the preceding item can be repeated one or more times. |
| Meta+x | This symbol indicates that you hold down the first named key while pressing the key or mouse button that follows the plus sign. |