Tru64 UNIX

Tru64 UNIX

Ladebug Debugger Manual

Order Number: AA-RH9QA-TE


July 1999

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


July 1999

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


Preface

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:

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:

Related Documents

The following documents contain related information:

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:

Please include the following information along with your comments:

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:

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.


Part 1
Overview of the Debugger

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.


Chapter 1
Introduction to Debugging

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:

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:

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.

1.3 Key Features of the Ladebug Debugger

Key features of the debugger allow you to:

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

1.4 User Interface Options

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

1.5 Ladebug Commands Summary

Table 1-1 lists and describes the Ladebug commands, organized in functionally related sets:

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.


Next Contents Index