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.
Tru64 UNIX Version 5.0 or higher
Ladebug Version 5.0 or higher
Compaq Computer Corporation
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).
This document is available on CD-ROM.
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.
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.
This manual is organized as follows:
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:
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:
|System and network administrators||S||Red|
|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.
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.
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:
Table 1 lists the conventions used in this manual.
|#||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.|
|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:
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:
Key features of the debugger allow you to:
You can customize the debugger environment or a core file debugging session by using:
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:
|#||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:
|#||Causes debugger to ignore all input until end of marked line.|
Without argument, repeats previous command line (use
With argument, repeats specified command line.
|/||Invokes forward search in source program.|
|?||Invokes backward search in source program.|
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.|
Without argument, shows which operating system signals debugger
With argument, traps specified operating system signal.
|catch unaligned||Traps program immediately after unaligned data access occurs.|
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.|
Without argument, changes function one level down stack.
With argument, changes function specified number of levels down stack.
Without argument, lists parameters and local variables in current
With argument, lists parameters and local variables in specified active function.
|enable||Enables specified breakpoint or tracepoint.|
|export||Synonym for setenv.|
Without argument, displays name of current file scope.
With argument, changes specified file scope.
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.|
Without argument, displays list of debugger commands.
With argument, displays description of specified command.
Without argument, displays default number of previously executed
With argument, displays specified number of previously executed commands.
With argument, shows which operating system signals debugger currently
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).|
Depending on argument, displays source code lines beginning with line
corresponding to any of following:
|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.|
Without argument, removes removes one execution frame from the call
With argument, removes the specified number of execution frames from the call stack.
|Displays current value of a variable or expression visible in current context.|
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.|
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.|
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.|
Without argument, examines definitions of all debugger variables.
With argument, defines specified debugger variable.
Without argument, displays values of all environment variables.
With argument, sets value of specified environment variable.
|sh||Executes Bourne shell command.|
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.|
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.|
Without variable argument, suspends program execution and returns to
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.|
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.
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:
|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.|
Without argument, removes all environment variables.
With argument, removes specified environment variable.
Without argument, sets search list to default, home directory, current
directory, or directory containing executable file.
With argument, removes specified directory from search list.
Without argument, changes function scope one level up stack.
With argument, changes function scope specified number of levels up function scope.
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.|