Tru64 UNIX

Order Number: AA-RH9QA-TE

This manual describes how to use the Ladebug debugger (both the graphical user interface and the command-line interface) to debug applications written in the programming languages Ada, C, C++, COBOL, and Fortran, on the Tru64 UNIX operating system.

The Ladebug debugger was formerly called DECladebug.

Revision/Update Information: This is a revised manual.

Product Version: Tru64 UNIX Version 5.0 or higher
Ladebug Version 5.0 or higher

Compaq Computer Corporation
Houston, Texas

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

(c) Copyright 1996, 1999. Digital Equipment Corporation. All rights reserved.

COMPAQ, the Compaq logo, and the Digital logo are registered in the U. S. Patent and Trademark Office.

The following are trademarks of Compaq Computer Corporation: ALPHA, AlphaServer, DEC Ada, DEC Fortran, DEC FUSE, DECladebug, DECthreads, DIGITAL, and Ladebug.

Open Software Foundation, OSF, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd.

All other trademarks and registered trademarks are the property of their respective holders.

Restricted Rights: Use, duplication, or disclosure by the U. S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii).

ZK6488

This document is available on CD-ROM.

Contents

Index

This manual contains information for debugging programs with the Ladebug debugger. Ladebug is a debugger on the Tru64 UNIX (formerly known as DIGITAL UNIX) operating system.

Intended Audience

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 Tru64 UNIX operating system.

Structure of this Document

This manual is organized as follows:

• Part 1 contains an overview of the debugger.
  • Chapter 1 contains an introduction to debugging concepts, key features of the debugger, an overview of the debugger interfaces, information on how to start the debugger, and a sample debugging session.
  
  
• Part 2 discusses basic debugging techniques.
  • Chapter 2 explains how to examine program information.
  • Chapter 3 explains how to control program execution.
  • Chapter 4 explains how to customize the debugger.
  
  
• Part 3 presents the following language-specific topics:
  • Chapter 5 describes the debugger support for DEC C++.
  • Chapter 6 describes the debugger support for DIGITAL Fortran.
  • Chapter 7 describes the debugger support for DEC Ada.
  • Chapter 8 describes the debugger support for DEC COBOL.
  
  
• Part 4 describes advanced debugging techniques. Part 4 includes the following chapters:
  • Chapter 9 explains how to attach, detach, and terminate processes and debug multiprocess applications.
  • Chapter 10 explains how to debug multithreaded applications.
  • Chapter 11 describes some techniques for debugging core files.
  • Chapter 12 explains how to use debugger scripts.
  • Chapter 13 explains how to debug programs with shared libraries.
  • Chapter 14 explains how to debug programs with limited symbolic information.
  • Chapter 15 describes machine-level debugging.
  • Chapter 16 describes remote debugging.
  • Chapter 17 describes kernel debugging.
  
  
• Part 5 contains the Ladebug Command Reference:
  • Part 5, the Command Reference, presents the debugger commands alphabetically and fully describes them, along with the commands and options for invoking the debugger.
  
  
• The appendixes are as follows:
  • Appendix A describes Ladebug menus.
  • Appendix B describes how to use the debugger from within the DEC FUSE Environment.
  • Appendix C describes how to write a remote debugger server.

Programming Languages

This manual emphasizes debugger usage that is common to all or most supported languages. For more information specific to a particular language, see:

• The debugger's online help system
• The documentation supplied with that language, particularly regarding compiling and linking the program for debugging

Related Documents

The following documents contain related information:

• DIGITAL UNIX Programmer's Guide
• DIGITAL UNIX Motif User's Guide
• CDE User's Guide
• Developing Ada Programs on DIGITAL UNIX Systems
• The Annotated C++ Reference Manual (Ellis and Stroustrup, 1990, Addison-Wesley)
• DEC COBOL User Manual
• DEC Fortran 90 User Manual for DEC OSF/1 Systems
• Release Notes for Ladebug Version 4.0
• <REFERENCE>(FUSE_HAND)
• Reference pages:
  • ladebug(1)
  • 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 Tru64 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 Compaq.) 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 Tru64 UNIX documentation set.

Reader's Comments

DIGITAL welcomes any comments and suggestions you have on this and other Tru64 UNIX manuals. You can send your comments in the following ways:

• Fax: 603-884-0120 Attn: Tru64 UNIX Publications, ZK03-3/Y32
• Internet electronic mail: readers_comment@zk3.dec.com
  A Reader's Comment form is located on line in the following location:
  /usr/doc/readers_comment.txt
• Mail:
  Compaq Computer Corporation
  Tru64 UNIX Publications Manager
  ZK03-3/Y32
  110 Spit Brook Road
  Nashua, NH 03062-2698

Please include the following information along with your comments:

• The full title of the book and the order number. (The order number is printed on the title page of this book and on its back cover.)
• The section numbers and page numbers of the information on which you are commenting.
• The version of Tru64 UNIX that you are using, for example, Tru64 UNIX Version 4.0.
• If known, the type of processor that is running the Tru64 UNIX software, for example, AlphaServer 2000.

The Tru64 UNIX Publications group cannot respond to system problems or technical support inquiries.

Reporting Software Problems

Information provided with the software media explains how to send problem reports to Compaq. If you need to report a software problem with the Ladebug debugger, contact your local Compaq Customer Support Center. Please include as much information as possible to help diagnosis and resolution of the problem. Useful information includes the following:

• The Ladebug version number as reported in the "Welcome" banner
• The source code of a sample program or an executable binary
• The system configuration
• The exact steps used to reproduce the problem
• The .i or .ixx file (if the executable program is compiled with a compiler that supports the "-P" option)
• The core file, if available

Conventions

Table 1 lists the conventions used in this manual.

Table 1 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 Tru64 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.

This part contains an overview of debugging concepts, key features of the debugger, an overview of the user interfaces, how to start and run a debugging session, and a sample debugging session.

This chapter introduces some fundamental debugging concepts, and describes some key Ladebug features and methods for accessing the debugger. It also contains lists of Ladebug commands and a sample debugging session.

For more information on the Ladebug commands mentioned in this chapter, see Part 5.

1.1 Overview of Debugging Concepts

The debugger helps you locate run-time programming or logic errors. You use the debugger with a program that has been compiled and linked successfully, but does not run correctly. For example, the program might give incorrect output, go into an infinite loop, or terminate prematurely.

You locate errors with the debugger by observing and manipulating your program interactively as it executes. The debugger lets you:

• Display your program's source code and browse through the code to locate points of interest where you might test for certain conditions
• Set breakpoints to suspend program execution or enter command sequences at such points and set watchpoints and tracepoints that notify you of certain conditions
• Execute your program, including stepping through one source line or machine instruction at a time and restarting from the beginning of the program
• Display, monitor, and change the values of program variables and data structures and examine their types
• Examine and manipulate the currently active routines on the call stack
• Examine and manipulate processes and threads in the program
• Disassemble and examine machine code; examine and modify machine-register values
• Customize the debugging environment
• Intercept software signals sent to the program by the operating system

As you use the debugger and its documentation, you will discover variations on the basic techniques. You can also customize the debugger to meet your own needs.

Because the debugger is a symbolic debugger, you can specify variable names, routine names, and so on, precisely as they appear in your source code. You can also optionally specify memory addresses or registers when referring to program locations.

You can use the debugger with programs written in any of the supported languages:

• C
• C++
• Fortran
• Ada
• COBOL
• Machine code

See your compiler documentation for information about the current extent of support for your language.

1.2 Basic Debugging Technique

Programmers use debuggers most often to extract important pieces of information during program execution. A simple debugging procedure might include these steps:

1. Compile and link the program. (See Section 1.6.1.) Your program must compile and link without any errors; the debugger only operates on programs that successfully compile into executable files.
2. Invoke the debugger on your program.
3. Set a breakpoint at the line number or function suspected to be at fault.
4. Run the program from the debugger prompt.
5. Examine the values of program variables.
   When program execution suspends at the specified breakpoint, examine the values of program variables. If the variables do not provide you with any clues, try setting other breakpoints, executing program statements line by line, or tracing a variable's value during program execution.

Key features of the debugger allow you to:

• Perform source-level debugging
• Debug programs written in the supported languages
• Attach to a running process
• Debug programs with shared libraries
• Debug multithreaded applications
• Debug more than one program at a time (multiprocess applications)
• Perform remote client/server debugging
• Perform kernel debugging
• Use local language characters
• Debug via a graphical user interface

You can customize the debugger environment or a core file debugging session by using:

• Graphical user interface customization features
• Scripts containing debugger commands
• Aliases for frequently used debugger command sequences
• Variables to store information

The debugger has three different user interface options to accommodate users with varying equipment and debugging styles:

• Graphical user interface (GUI)
  Users with workstations can access the debugger GUI to display and manipulate the application being debugging ed through a Motif windows interface. Paned debugger windows and expandable data views efficiently display program execution and data. Pulldown and pop-up menus provide logical and convenient access to debugging functions. A customizable pushbutton panel accommodates individual debugging styles. Process and thread menus provide access to multiple processes and threads.
  See Section 1.6 for information on how to access the GUI.
• Emacs interface
  You can use either a terminal or workstation to control the debugger process entirely through the Emacs GUD (Grand Unified Debugger) buffer, which is a variant of Shell mode. All the Ladebug commands are available, and you can use shell mode history commands to repeat them. You can streamline your debugging sessions by editing, recompiling, and rerunning applications without leaving the Emacs working environment.
  For more information on how to use Emacs to access the debugger, see Section 1.6.3. For more information on creating an Emacs working environment, see the Emacs documentation.
• Command interface
  Users with terminals and workstations can use the debugger command interface to use dbx-like functions and syntax.

1.5 Ladebug Commands Summary

Table 1-1 Functionally Related Sets of Ladebug Commands

#	Enter a comment.
alias, unalias	Define, view, or delete a debugger command alias.
assign	Change value of a variable, memory address, or expression.
attach, detach	Attach or detach from a running process.
catch, ignore	Examine and change the list of operating system signals trapped by the debugger.
catch unaligned, ignore unaligned	Trap programs immediately after unaligned data access occurs or instruct the debugger not to do so (the default).
class	Change or display the class scope.
history, !	Repeat and list previously used commands.
file	Set (display) the file scope.
kps	List all system processes; for local kernel debugging only.
list, use, unuse, /, ?	Select and view program source code.
listobj	List all loaded objects, including the main image and shared libraries.
readsharedobj, delsharedobj	Read or delete symbol table information for the specified shared object.
load, unload	Load or unload an image file, core file, and symbolic information.
print, printf, dump, assign, whatis, which, whereis	Examine program expressions and change their values.
process, show process	Display information for current process(es) and change the current process.
pop	Remove execution frame(s) from the call stack.
quit, help	Exit and get help about the debugger.
run, rerun, cont, next, step, return, call, goto, kill	Execute or terminate a program under debugger control.
sh	Execute a Bourne shell command.
set, unset	Define, view, or delete a debugger variable.
source, playback input, record input, record output, record io	Read in or save a file containing debugger input data or output data.
stop, when, trace, status, delete, enable, disable, watch	Set, list, delete, enable, and disable program breakpoints, tracepoints, and watchpoints.
stopi, tracei, wheni, nexti, stepi, printregs	Machine-code level commands.
stop thread, when thread, wheni thread, trace thread, tracei thread	Control execution of one or more threads in a process.
thread, show thread, show condition, show mutex	View information available from the debugger about threads in your application.
where, where thread, up, down, func	Examine the stack trace and change the function scope.
setenv, export, printenv, unsetenv	Manipulate subsequent debuggee environments with environment variables .

Table 1-2 gives a quick summary of the function of each individual Ladebug command:

Table 1-2 Ladebug Commands: Individual Summary

Command	Function
#	Causes debugger to ignore all input until end of marked line.
!	Without argument, repeats previous command line (use !! or !-1 ). With argument, repeats specified command line.
/	Invokes forward search in source program.
?	Invokes backward search in source program.
alias	Without argument, displays all aliases and their definitions. With argument, displays definition for specified alias.
assign	Changes value of variable, memory address, or expression.
attach	Attaches to a specified running process.
call	Executes specified function.
catch	Without argument, shows which operating system signals debugger currently traps. With argument, traps specified operating system signal.
catch unaligned	Traps program immediately after unaligned data access occurs.
class	For C++ only. Without argument, displays current class scope. With argument, changes class scope.
cont	Resumes program execution.
delete	Removes specified breakpoint or tracepoint.
delsharedobj	Removes symbol table information for specified shared object.
detach	Detaches from a specified running process.
disable	Disables specified breakpoint or tracepoint.
down	Without argument, changes function one level down stack. With argument, changes function specified number of levels down stack.
dump	Without argument, lists parameters and local variables in current function. With argument, lists parameters and local variables in specified active function.
enable	Enables specified breakpoint or tracepoint.
export	Synonym for setenv.
file	Without argument, displays name of current file scope. With argument, changes specified file scope.
func	Without argument, displays current function scope. With argument, changes function scope to function currently active on stack.
goto	Branches to specified line in function where execution is suspended.
help	Without argument, displays list of debugger commands. With argument, displays description of specified command.
history	Without argument, displays default number of previously executed commands. (20). With argument, displays specified number of previously executed commands.
ignore	With argument, shows which operating system signals debugger currently ignores. With argument, ignores specified operating system signal.
ignore unaligned	Instructs debugger not to stop when unaligned access occurs (default).
kill	Terminates debugger process while leaving debugger running.
kps	Lists all system processes (valid for local kernel debugging only).
list	Depending on argument, displays source code lines beginning with line corresponding to any of following: Line designating position of program counter Last line listed, if multiple list commands are entered Line number specified as first argument
listobj	Lists all loaded objects, including main image and shared libraries.
load	Loads image file or core file.
next	When next line of code to be executed contains a function call, executes function and returns to line immediately after function call.
nexti	When machine instruction contains a function call, executes function being called.
patch	Corrects bad data or instructions in executable disk files.
playback input	Executes debugger commands contained within a file.
pop	Without argument, removes removes one execution frame from the call stack. With argument, removes the specified number of execution frames from the call stack.
print	Displays current value of a variable or expression visible in current context.
printenv	Without argument, displays values of all environment variables. With argument, displays value of specified environment variable.
printf	Formats and displays a complex structure.
printregs	Displays contents of all machine registers.
process	Without argument, displays current process. With argument, switches to specified process.
quit	Ends debugging session and returns to operating system prompt.
readsharedobj	Reads in symbol table information for specified shared library or loadable kernel module.
record input	Saves all debugger commands to a file.
record io	Saves both debugger input and debugger output to a file.
record output	Saves debugger output to a file.
rerun	Restarts program execution.
return	Without argument, continues execution of current function until control is returned to caller. With argument, execution continues until control is returned to specified function.
run	Starts program execution.
set	Without argument, examines definitions of all debugger variables. With argument, defines specified debugger variable.
setenv	Without argument, displays values of all environment variables. With argument, sets value of specified environment variable.
sh	Executes Bourne shell command.
show condition	For DECthreads only. Without argument, displays information about all condition variables currently available. With argument, displays information about condition variables specified.
show mutex	Lists information about currently available mutexes.
show process	Displays information for current process.
show thread	Without argument, lists all threads known to debugger. With argument, displays information about specified thread.
source	Executes debugger commands contained within a file.
status	Lists all breakpoints and tracepoints, reference number associated with each, and whether breakpoint is disabled.
step	Steps into and executes first line of function.
stepi	Steps into and executes next machine instruction. If function call, steps into and executes first instruction in function.
stop	Without variable argument, suspends program execution and returns to prompt. With variable argument, suspends program execution when variable changes.
stopi	Suspends program execution when specified variable value changes.
thread	Identifies or sets current thread context.
trace	Without argument, causes debugger to print message when each function is entered, but does not suspend program execution. With argument, causes debugger to print message when specified variable value changes, but does not suspend program execution.
tracei	Without argument, prints message but does not suspend program execution. With argument, prints message when any of following occur, but does not suspend program execution: Value of specified variable changes. Specified expression evaluates to true. Both.
unalias	Deletes specified alias.
unload	Removes all related symbol table information that debugger associates with process being debugged, specified by either a process ID or image file.
unset	Deletes debugger variable.
unsetenv	Without argument, removes all environment variables. With argument, removes specified environment variable.
unuse	Without argument, sets search list to default, home directory, current directory, or directory containing executable file. With argument, removes specified directory from search list.
up	Without argument, changes function scope one level up stack. With argument, changes function scope specified number of levels up function scope.
use	Without argument, lists directories searched for source-code files. With argument, makes source-code files in specified directory available.
watch	Suspends program execution when specified memory address or variable is accessed.
whatis	Prints type of specified expression.
when	Executes specified command.
wheni	Executes specified command without suspending program execution.
where	Displays stack trace of currently active functions for current thread.
whereis	Shows all declarations of expression.
which	Shows fully qualified scope information when instance of specified expression occurs within current scope.