*** UNIX MANUAL PAGE BROWSER ***

ladebug(1) General Commands Manual ladebug(1) NAME ladebug, dxladebug - Invokes the command interface (ladebug) or the graphical user interface (dxladebug) debugger. SYNOPSIS ladebug [-I directory ] [-c file ] [-prompt string] [-nosharedobjs] [-pid process_id] [-rn node_or_address[,udp_port]] [-rfn remote_executable_file] [-ru remote_username] [-rinsist] [-k] [-line serial_line] [-remote] [-rp remote_debug_protocol] [-tty terminal device] [executable_file [core_file]] dxladebug [-iow] [-k|-kernel] [-P program_arguments] DESCRIPTION Ladebug is a symbolic source code debugger that debugs programs com- piled by the DEC C, ACC, DEC C++, DEC Ada, DEC COBOL, DEC Fortran 90, and DEC Fortran 77 compilers. For full source-level debugging, compile the source code with the compiler option that includes the symbol table information in the compiled executable file. Command-Line Options and Parameters Specifies the directory containing the source code for the target pro- gram. Use multiple -I options to specify more than one directory. The debugger searches directories in the order in which they were specified on the command line. Specifies an initialization command file. The de- fault initialization file is By default, Ladebug searches for this file during startup, first in the current directory; if it is not there, Ladebug searches your home directory for the file. Specifies a debug- ger prompt. The default debugger prompt is (ladebug). If the prompt argument contains spaces or special characters, enclose the argument in quotes (" "). Prevents the reading of symbol table information for any shared objects loaded when the program executes. Later in the debug session, the user can enter the readsharedobj command to read in the symbol table information for a specified object. Specifies the process ID of the process to be debugged. This cannot be used with any remote or kernel debugging flags. Specifies the host name or Internet address of the machine on which the remote debugger server is running. Option- ally, this specifies the UDP port on which to connect the server. De- pending on your shell, it may be necessary to use quotation marks to avoid shell command-line interpretation on the local system. With re- mote kernel debugging, the default is localhost. Specifies the file name (or other identifier) of the executable file to be loaded on the remote system. This option defaults to the local executable file name and is passed uninterpreted to the remote systems. When using this op- tion, specify the remote executable file using the syntax of the remote file system; use quotation marks to avoid shell command-line interpre- tation on the local system. Use only with -rn; do not combine with -pid. Specifies the user name to be used on the remote target machine. If the -ru option is not specified, the default is the local user name. Use only with -rn. Connects to a running remote process using the in- sist protocol message instead of the connect protocol message. This option functions as a request to the server to connect to the client, even if another client is already connected. Use only with -rn and -pid. Enables local kernel debugging. Specifies the serial line for remote kernel debugging. Must be used with -remote or -rp kdebug (the default). Enables remote kernel debugging; for use with the kdebug kernel debugger. Specifies the remote debug protocol, either lade- bug_preemptive or kdebug. -rp kdebug enables remote kernel debugging. Specifies the terminal device for remote kernel debugging. This must be used with -remote or -rp kdebug. Specifies the program executable file. If the file is not in the current directory, specify the path- name. Specifies the core file. If the core file is not in the current directory, specify the pathname. GUI Options and Parameters Invokes the graphical user interface to the debugger and displays a separate user program I/O window. Enables local kernel debugging. Specifies the arguments used by the program you are debugging. Ladebug Documentation Ladebug documentation consists of the following: Ladebug Debugger Man- ual Online help Manpage Release notes The Ladebug Debugger Manual is available on the DIGITAL UNIX documentation CD-ROM in Bookreader for- mat. Ladebug contains extensive online help, both in the command in- terface and GUI, and maintains its own release notes and manpage. The release notes are contained in a subset of the Ladebug kit in usr/doc/ladebug. The Ladebug Debugger Manual will be provided in HTML format in a future release. New and Changed Features Key features of Ladebug Version 4.0 include: Multiprocess Application Debugging You can now have multiple processes (zero or more processes) under de- bugger 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. Multithreaded Debugging 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 set $threadlevel command, as follows: set $threadlevel="decthreads" set $threadlevel="native" The default is DECthreads. 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 syntaxes for multithread debugging include stop, trace, when, step, stepi, next, nexti, and cont. See also information about the where, show condition, and show mutex commands. Load/Unload a Process The load command lets you load an image file or core file for debug- ging. The unload command removes the symbol table information that the debugger had associated with the process being debugged. Kernel Debugging Ladebug supports kernel debugging. The functionality is similar to ker- nel debugging using dbx. When you have a problem with a process, you can debug the running ker- nel or examine the values assigned to system parameters. (It is gener- ally 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 com- mand: ladebug -k /vmunix /dev/mem 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 com- mand: ladebug -remote /testdir/vmunix Multilanguage Support Ladebug Version 4.0 enhances language support as follows: C/C++ --- Ladebug fully supports debugging ACC and DEC C programs, and DEC C++ programs. DEC C++ now supports cfront compatibility and the GEM com- piler backend. Ladebug supports C++ names and expressions, including template instantiations and exception handling; and setting breakpoints in member functions, overloaded functions, constructors and destruc- tors, template instantiations, and exception handlers. You can also change the current class scope to set breakpoints and examine members of a class that are not currently in scope. You can debug mixed-lan- guage programs. Fortran --- Ladebug lets you debug DEC Fortran 77 and DEC Fortran 90 programs. You can specify identifiers, program names, subroutine names, and array sections to Ladebug with Fortran language syntax, including case insensitivity. You can display values of vari- ables in a Fortran common block; access Fortran derived-type, record, array, and complex variables; examine Fortran 77 and Fortran 90 data types (with some limitations); and debug mixed-language programs. Ladebug fully supports the debugging of Ada and COBOL programs. Sup- port for these languages is unchanged from the previous release. Graphical User Interface The Ladebug graphical user interface (GUI) supports the major Ladebug command-line functionality. The GUI includes a main window covering the basic debugging and convenience features: optional views windows, vari- ous pop-up menus and dialog boxes, a command-entry prompt within a com- mand window, and quick help panel. Other Ladebug features can be ac- cessed within the GUI from the command-entry prompt. Support for International Users User programs can set different locales in order to interpret text ac- cording to different language and culture-related criteria. In addi- tion, locales can be switched inside a user program. Environment-Manipulation Commands Ladebug provides commands for manipulating the environment of subese- quent debuggees with environment variables. Using the setenv, export, printenv, and unsetenv commands within the debugger, you can set the value of an environment, display the values of environment variables, and remove environment variables. The pop Command The pop command removes execution frames from the call stack. It is useful when execution has passed an error that needs to be corrected. Key Features of Ladebug Version 4.0D Watchpoints In addition to breakpoints and tracepoints, Ladebug now supports watch- points. The watch command suspends program execution, prints the watchpoint event, prints the instruction that accessed the watched mem- ory, displays old and new values, and prints the first line of source code that will be executed when program execution continues. The infor- mation includes the exact address (to the byte) at which the access oc- curred, the disassembled instruction that caused the access and, if available, program source line information about the instruction. New C++ Functionality Displaying Static or Dynamic Type Information When displaying object information for C++ class pointers or refer- ences, the user now has the option of viewing either the static or dy- namic type information. A new debugger variable, $usedynamictypes, en- ables the user to control which form of the type information is dis- played. Displaying Virtual and Inherited Class Information When you use the print command, Ladebug now displays both new class members as well as members from a base class, including multiple inher- ited classes. Thread Local Storage The debugger now supports programs that use Thread Local Storage. This feature provides a way for an application writer to declare that some data is to have multiple instances, one per thread. Refer to DEC- threads documentation and compiler documentation for information on how to use Thread Local Storage. Fortran Support Enhancements The debugger now fully supports the Fortran REAL*16 and C long double datatypes. The debugger also enables users to specify substrings of Fortran character variables in expressions, and supports Fortran PARA- METER constants and arrays up to 31 dimensions. Commands You can enter more than one command on the same line by separating each command with a semicolon. Commands are executed in the same order in which they are entered on the command line. Continue command input to another line by entering a backslash at the end of each line. The maximum command-line length is 100,000 charac- ters. In debugger commands, the words thread, in, at, state, if, policy, pri- ority, and with are Ladebug keywords and must be surrounded by paren- theses in expressions that use them as variables or type names. Task-related Command Sets The following section lists Ladebug commands in task-related sets: Starting and stopping programs in the debugger: attach, detach, kill, load, quit, rerun, run, unload For examples, enter help start. Stopping your program at specific locations: delete, disable, enable, status, stop, stopi, when, wheni For examples, enter help breakpoint. Controlling the execution of your program: call, cont, goto, next, nexti, return, step, stepi For examples, enter help execution. Reading and writing memory, variables, and registers: assign, dump, ex- amine_address, print, printf, printregs, trace, tracei, watch For exam- ples, enter help variable, help memory or help register. Looking at the call stack: down, pop, up, where For examples, enter help stack. Showing the source for the program: /, ?, file, list, unuse, use For examples, enter help listing. Examining or changing the current scope under investigation: class, down, file, func, process, thread. Manipulating processes: attach, detach, kill, process, show process Manipulating threads and thread-specific objects: show condition, show mutex, show thread, thread Learning specifics about program variables: whatis, whereis, which Manipulating shared objects: delsharedobj, listobj, readsharedobj Controlling signal handling: catch, ignore Changing or understanding your Ladebug environment: alias, set, help, unalias, unset For a complete list of debugger variables, enter help $variable. Changing or showing the current system environment: export, printenv, setenv, sh, unsetenv Logging Ladebug results: #, playback, record, source Recalling previously-used commands: !, history Debugging UNIX kernels: kps, patch There are also a number of kernel debugging command aliases such as tlist and tstack available. Enter alias for a complete list of command aliases. Command Descriptions startaddress , endaddress / mode startaddress / count mode You can display stored values as character strings, machine instruc- tions, or decimal, octal, hexadecimal, or real numbers. Specify the ad- dress and the number of words or bytes (count) information in hexadeci- mal, octal, or decimal. The display mode must be specified along with the address range. The modes are: d Print a short word in decimal. u Print a short word in unsigned decimal. D Print a long word in decimal. U Print a long word in unsigned decimal. dd Print a 32-bit (4 byte) decimal display. uu Print a 32-bit (4 byte) unsigned decimal display. o Print a short word in octal. O Print a long word in octal. oo Print a 32-bit (4 byte) octal display. x Print a short word in hexadecimal. X Print a long word in hexadecimal. xx Print a 32-bit (4 byte) hexadecimal display. b Print a byte in hexadecimal. c Print a byte as a character. s Print a string of characters (a C-style string that ends in null). f Print a single-precision real number. g Print a double-precision real number. i Disassemble machine instructions. Note that you must enter a space between "count" and "mode" if the lan- guage of the program being debugged is COBOL. # comment When the debugger encounters the # command, it ignores all inputs until the end of the line. The # command must be the first identifier on the command line. (White space can precede this command.) !! or ![-]integer or !text To repeat the last command line, enter two exclamation points or press the Return key. You can also enter !-1. To repeat a command line entered during the current debugging session, enter an exclamation point followed by the integer associated with the command line. (Use the history command to see a list of commands used.) For example, to repeat the seventh command used in the current debugging session, enter !7. Enter !-3 to repeat the third-to-last command. To repeat the most recent command starting with a string, use the last form of the command. For example, to repeat a command that started with bp, enter !bp. / [string] or ? [string] Use the string search commands / and ? to locate text in the source code. The / character invokes a forward search; the ? character in- vokes a backwards search. Enter / or ? without an argument to find the next location of the previously specified text. The search begins from the current position of the program counter. If no program counter exists for the current source file, the search be- gins after the last source line displayed by the debugger. alias [aliasname ] alias aliasname [(argument)] "string" unalias aliasname Enter the alias command without an argument to display all aliases and their definitions. Specify an alias name to display the definition for that alias. Use the second form to define a new alias or to redefine an existing alias. The definition can contain the name of another alias, if the nested alias is the first identifier in the definition. For example, you can define a nested alias and invoke the alias as follows: (ladebug)alias begin "stop in main; run" (ladebug)alias pv(x) "begin; print(x)" (ladebug)pv(i) The definition can contain a string in quotation marks, specified with backslashes before the quotation marks, as in the following example: (ladebug)alias x "set $lang=\"C++\"#" (ladebug)alias x x set $lang="C++" Invoke the alias by entering the alias name, including any arguments specified in the alias definition. Use the unalias command to delete an alias. Alias commands cannot contain more than 56 arguments. The following predefined aliases are included with the debugger: S next Si nexti W list $curline - 10:20 a assign b stop at bp stop in c cont d delete e file f func g goto h history j status l list li $curpc/10i; set $curpc=$curpc+40 n next ni nexti p print pd printf "%d" pi playback input plist show process all po printf "0%o" pr printregs ps printf "%s" px printf "0x%1x" q quit r rerun ri record input ro record output s step si stepi switch process t where tlist show thread all (show thread when the kernel debugging option is used) tset thread tstack where thread all u list $curline-9:10 w list $curline-5:10 wi ($curpc-20)/10i wm watch memory assign target = expression Use the assign command to change the value of a variable, memory ad- dress, or expression that is accessible according to the scope and vis- ibility rules of the language. The expression can be any expression that is valid in the current context. For C++: assign [classname::]member = ["filename"]`expression assign [object.]member = ["filename"]`expression For C++, use the assign command to modify static and object data mem- bers in a class, and variables declared as reference types, type const, or type static. The address referred to by a reference type cannot be changed, but the value at that address can be changed. attach process_id image_file Use the attach command to connect to a running process. Supply the process ID number and image file name. call function([parameter]) Use the call command to execute a single function. Specify the function as if you were calling it from within the program. If the function has no parameters, specify empty parentheses. You can nest called functions by setting a breakpoint in a function and executing it using the call command. When execution suspends at the breakpoint, use the call command to execute the nested function. For multithreaded applications, the call is made in the context of the current thread. For C++: When you set the $overloadmenu debugger variable to 1 and call an over- loaded function, the debugger lists the overloaded functions and calls the function you specify. catch [signal] Enter the catch command or the ignore command without an argument to see which operating system signals the debugger currently traps or ig- nores. Use the catch command or the ignore command followed by an argu- ment to trap or ignore, respectively, that signal. Only one signal at a time can be added to, or removed from, the list of trapped or ignored signals. The catch and ignore commands operate on a per-program basis; you must first load a program (using the load command) or attach to a process (using the attach command). catch unaligned Enter the catch unaligned command to instruct the debugger to stop when unaligned data access occurs in the debuggee process. The debugger stops at the instruction following the instruction where the unaligned access occurs, and issues a message. The default is ignore unaligned. class [classname] class classname::(type signature) class classname~::(type signature) For C++ only: Use the class command without an argument to display the current class scope. Specify an argument to change the class scope. Once the class scope is set, refer to members of the class omitting the classname:: prefix. Constructors and destructors of nested classes must be accessed with a class command. Use the second syntax form for a constructor, and the third syntax form for a destructor. Setting the class scope nullifies the function scope. cont [signal] [to linenumber] [in function] Use the cont command without a parameter value to resume program execu- tion until a breakpoint, a signal, an error, or the end of the program is encountered. Specify a signal parameter value to send an operating system signal to the program continuing execution. Specify the linenumber argument to halt program execution when that line number is reached. Specify the in function argument to halt the program when the named function is reached. When you use the cont command, Ladebug resumes execution of the entire process. The signal parameter value can be either a signal number or a string name (for example, SIGSEGV). The default is 0, which allows the pro- gram to continue execution without specifying a signal. If you specify a signal parameter value, the program continues execution with that signal. The linenumber argument is used to resume execution and then halt when the specified source line is reached. The form of the optional linenumber argument must be either linenumber, a positive numeric, which indicates the line number of the current source file where execution is to be halted, or "filename":linenumber, which explicitly identifies both the source file and the line number where execution is to be halted. The function argument is used to continue until the named function is reached. If the function name is overloaded and the user does not re- solve the scope of the function in the command line, the debugger prompts the user with the list of overloaded functions bearing that name from which to choose. The form of the optional function argument must be a valid function name. delete integer[,...] delete all delete * Enter the delete command followed by the number or numbers associated with a breakpoint, trace, or watch (as listed by the status command) to remove the specified breakpoint, tracepoint, or watchpoint. Enter the delete all command or the delete * command to remove all breakpoints, tracepoints, or watchpoints. This command operates on a per-program basis; you must first load a program (using the load command) or attach to a process (using the at- tach command). delsharedobj shared_object Use the delsharedobj command to remove the symbol table information for the specified shared object from the debugger. detach [process_id[,...] Use the detach command with process IDs to detach from the specified running process or processes. Use the show process all or show process * command to display a list of processes running under debugger con- trol. If you do not specify a process ID, Ladebug detaches from the current process. Detaching from a process disables your ability to de- bug that process. disable integer[,...] disable all disable * Enter the disable command followed by the number or numbers associated with a breakpoint, trace, or watch (as listed by the status command) to disable the breakpoint, tracepoint, or watchpoint. Enter the disable all command or the disable * command to disable all breakpoints, trace- points, or watchpoints. The disabled breakpoint is displayed in response to the status command, but it is ignored during execution. Disabled breakpoints remain dis- abled until they are explicitly reactivated or deleted. This command operates on a per-program basis; you must first load a program (using the load command) or attach to a process (using the at- tach command). down [number] Use the up command or the down command without an argument to change the function scope to the function located one level up or down the stack. Enter a number argument to change the function scope to the function up or down the specified number of levels. If the number of levels exceeds the number of active functions on the stack, the func- tion scope moves up or down as many levels as possible and the debugger issues a warning message. When the function scope changes, the debugger displays the source line corresponding to the last point of execution in that function. dump [function] dump. Use the dump command without an argument to list the parameters and lo- cal variables in the current function. To list the parameters and local variables in an active function, specify it as an argument. Enter the dump. command (include the dot) to list the parameters and local variables for all functions active on the stack. enable integer[,...] enable all enable * Enter the enable command followed by the number or numbers associated with a breakpoint, trace, or watch (as listed by the status command) to enable a breakpoint, tracepoint, or watchpoint. Enter the enable all command or the enable * command to activate all previously disabled breakpoints, tracepoints, and watchpoints. This command operates on a per-program basis; you must first load a program (using the load command) or attach to a process (using the at- tach command). export [env_variable [=value]] Sets the value of the specified environment variable. If no variable is specified, the command displays the values of all environment vari- ables. If a variable is specified but no value is specified, the vari- able is set to NULL. This command is not for the current debuggee's environment, but for the environment of any debuggees subsequently created with fork(2) or with subsequent run or rerun commands. Note that export and setenv are synonyms. file [filename] Enter the file command without an argument to display the name of the current file scope. Include the filename argument to change the file scope. Change the file scope to set a breakpoint in a function not in the file currently being executed. To see source code for a function not in the file currently being executed, use the file command to set the file scope and the use command to direct the search for the sources of that file. func [function] func [integer] Use the func command without an argument to display the current func- tion scope. To change the function scope to a function currently active on the stack, specify either the name of the function or the number corresponding to the stack activation level. (Enter the where command to display the stack trace.) When the function scope is changed, the debugger displays the source line corresponding to the last point of execution in that function. goto linenumber Use the goto command to branch to a line located in the function where execution is suspended. When you branch to a line, the source code be- tween the line where execution suspended and the specified line is not executed. help [command] [ladebug] Enter the help command without an argument to display a list of debug- ger help topics. Include a command argument to display a description of that command. Include the ladebug argument to display a task-ori- ented list of commands. history [integer] Enter the history command without an argument to display previously ex- ecuted commands. The debugger displays the number of command lines de- fined for the $historylines debugger variable. (The default is 20 lines of user input.) Include an integer argument to display that number of previous commands. ignore [signal] Enter the catch command or the ignore command without an argument to see which operating system signals the debugger currently traps or ig- nores. Use the catch command or the ignore command followed by an argu- ment to trap or ignore, respectively, that signal. Only one signal at a time can be added to, or removed from, the list of trapped or ignored signals. These commands operate on a per-program basis; you must first load a program (using the load command) or attach to a process (using the at- tach command). ignore unaligned Enter the ignore unaligned command (the default) to instruct the debug- ger not to stop when unaligned access occurs. (See also the catch un- aligned command.) kill Use the kill command to terminate the current program process and leave the debugger running. When a process terminates, breakpoints and traces previously set are retained. You can later rerun the program. kps Use the kps command to list all system processes. (This command is valid for local kernel debugging only.) list list startline [,endline ] list startline [:count] list function The list command displays source-code lines beginning with the source line corresponding to the position of the program counter, the last line listed if multiple list commands are issued, or the line number specified as the first argument to the list command. Specify the exact range of source-code lines by including either the endline or the num- ber of lines you want to display. The arguments can be expressions that evaluate to integer values. To display the source code for a particular function, enter the func- tion as an argument. listobj Use the listobj command to list all loaded objects, including the main image and the shared libraries. For each object, the information listed consists of the full object name (with pathname), the starting address for the text, the size of the text region, and whether the sym- bol table information has been read by the debugger. load image_file [core_file] unload process_id[,...] unload image_file The load command loads an image file and optionally a core file. After loading an image file, enter the run command to start program execu- tion. The unload command removes all related symbol table information that the debugger associated with the process being debugged, specified by either a process ID or image file. next [expression] Use the next and the step commands to execute a line of source code. When the next line to be executed contains a function call, the next command executes the function being called and returns to the line im- mediately after the function call. The step command steps into the function and executes only the first line of the function. For multithreaded applications, use these commands to step the current thread while putting all other threads on hold. If the optional expression argument is supplied, Ladebug evaluates the expression as a positive integer that specifies the number of times to execute the command. The expression can be any expression that is valid in the current context. nexti [expression] Use the stepi command and the nexti command to execute a machine in- struction. When the instruction contains a function call, the stepi command steps into the function being called, and the nexti command ex- ecutes the function being called. For multithreaded applications, use these commands to step the current thread while putting all other threads on hold. If the optional expression argument is supplied, Ladebug evaluates the expression as a positive integer that specifies the number of times to execute the command. The expression can be any expression that is valid in the current context. patch expression1 = expression2 Use the patch command to correct bad data or instructions in executable disk files. The text, initialized data, or read-only data areas can be patched. The bss segment, as well as stack and register locations, can- not be patched because they do not exist on disk files. Use this command exclusively when you need to change the ondisk binary. Use the assign command when you need only to modify debuggee memory. If the image is executing when you issue the patch command, the corre- sponding location in the debuggee address space is updated as well. (The debuggee is updated regardless of whether the patch to disk suc- ceeded, as long as the source and destination expressions can be processed by the assign command.) If the user program is loaded but not yet started, the patch to disk is performed without the correspond- ing assign to memory. playback input filename Use the source command and the playback input command to execute debug- ger commands contained within a file. (Note that you can also execute debugger commands when you invoke Ladebug by creating an initialization file named .dbxinit. By default, Ladebug searches for this file during startup, first in the current directory; if it is not there, Ladebug searches your home directory for the file.) Format the commands as if they were entered at the debugger prompt. When a command file is executed, the value of the $pimode debugger variable determines whether the commands are echoed. If the $pimode variable is set to 1, commands are echoed; if $pimode is set to 0 (the default), commands are not echoed. The debugger output resulting from the commands is always echoed. pop [number_of_frames] The pop command removes one or more execution frames from the call stack, undoing the work already done by the removed execution frames. The optional argument is the number of execution frames to remove from the call stack. If you do not specify the argument, one frame is re- moved. If specified, the number must be a positive integer less than or equal to the number of frames currently on the call stack. print expression [,...] print @expression The print command displays the current value of a variable or expres- sion that is visible in the current context, as defined by the scope and visibility rules of the program language. The expression can be any expression that is valid in the current context. The print @linenumber command displays the address of the specified line number. For example, print @10 displays the address of line num- ber 10. For C++: print *this print object print [object.]member print *(derived_class*)object For C++, use the print command to display the value of an object, in- cluding inherited members and the value of data members in an object. Type casts can be used to interpret a base class object as a derived class object, or to interpret a derived class object as a base class object. To interpret a base class type object as the derived type, use the last form of the print command. Set the $usedynamictypes debugger variable to 1 to display dynamic in- formation; set it to 0 to display static information. The default is dynamic. printenv [env_variable] Displays the value of the specified environment variable. If none is specified, the command displays the values of all environment vari- ables. This command is not for the current debuggee's environment, but for the environment of any debuggees subsequently created with fork(2) , or with subsequent run or rerun commands. printf [format [,expression,...]] Use the printf command to format and display a complex structure. The format argument is a string expression of characters and conversion specifications, using the same format specifiers as the printf C func- tion. printregs Use the printregs command to display the contents of all machine regis- ters for the current thread. Register values are given in both decimal and hexadecimal, depending on the value of the $hexints variable. The list of registers displayed by the debugger is machine dependent. process [process_id | image_file | debugger_variable] Specify a specific process using the process ID number or the name of the image. Ladebug sets the current process context to the process ID or the process that runs the binary image. If there is more than one process running the same binary image, Ladebug warns you and leaves the process context unchanged. The debugger variables $childprocess and $parentprocess can also be specified in place of the process ID. (Ladebug automatically sets these variables when an application forks a child process.) quit Use the quit command to end the debugging session and return to the op- erating system prompt. readsharedobj shared_object Use the readsharedobj command to read in the symbol table information for a specified shared object. This object must be a shared library or loadable kernel module. The command can be used only when a debuggee program is specified; that is, either Ladebug has been invoked with it, or the debuggee program was loaded by the load command. record input filename record output filename record io filename Use the record input command to save all the debugger commands to a file. The commands in the file can be executed using the source command or the playback input command. The record output command saves all debugger output to a file. The out- put is simultaneously echoed to the screen. (The program output is not saved.) The record io command saves both input to and output from the debugger. To stop recording debugger input or output, exit the debugger. return [function] Use the return command without an argument to continue execution of the current function until it returns to its caller. If you include a func- tion name, execution continues until control is returned to the speci- fied function. The function must be active on the call stack. run [program arguments] [io_redirection] rerun [program arguments] [io_redirections] Use the run and rerun commands to start program execution. Enter pro- gram flags, options, and input and output redirections as arguments. If the rerun command is specified without arguments, the arguments entered with the previous run command are used. If the last modification time and size of the binary file, or any of the shared objects used by the binary file have changed since the last run command was issued, Ladebug automatically rereads the symbol table information. If this happens, the old breakpoint settings may no longer be valid after the new symbol table information is read. set [variable = definition] unset variable To examine the definitions of all debugger variables, enter the set command without arguments. (Use the print command to display the defi- nition of a single debugger variable.) To define a debugger variable, enter the set command followed by a variable name, an equal sign, and a definition. Enclose string defini- tions in quotes. The definition can be any expression allowed by the language of the program being debugged. Use the unset command to delete a variable. If you want to remove an environment variable, or all environment vari- ables, use the unsetenv command, not the unset command. The debugger contains many predefined variables to describe the current state of the debugger, and to enable you to customize the debugger en- vironment. You can delete and redefine the predefined debugger vari- ables in the same way you define your own variables. If you delete a predefined debugger variable, the debugger uses the default value for that variable. The settings on the predefined variables apply to all debugging processes. The debugger has the following predefined variables: $ascii With the default value of 1, enables the print command to print character-type data as ASCII characters, only when the bit value is that of a printable 7-bit subset ASCII character. (Other bit values are printed as octal numbers.) With a value of 0, all printable ISO Latin-1 characters are printed as characters. $beep With the default value of 1, causes a beep to sound when a user attempts to perform an illegal action while editing the debugger command line (for example, moving the cursor past the end of the line, or "yanking" -- pasting -- from an empty cut buffer). $childprocess Can be specified in place of the process ID. (Ladebug automati- cally sets this variable when an application forks a child process.) $catchexecs When set to 1, instructs the debugger to notify the user and stop the program when a program execs. The default is 0. $catchforks When set to 1, instructs the debugger to notify the user when a program forks a child process. The child process stops and is brought under debugger control. (By default, the parent process is not stopped. See the $stopparentonfork description.) The de- fault is 0. $curevent Sets to the event number of the current event at the start of an event, allowing its use within the expression of an event. $curfile Specifies the current source-code file. $curline Specifies the current line in the source file. $curpc Specifies the current value of the Program Counter (PC). The $curpc variable is used by the wi and li aliases. $cursrcline Specifies the line number of the last line of source code listed, plus one. $curthread Indicates the thread ID of the current thread within the current process. You can change to a different thread by setting $curthread. $decints When set to 1, all integers printed by the debugger are displayed as decimal numbers. The default is 0. $editline With the default of 1, enables the command-line editing features. For backward compatibility, you can set this variable to 0. $eventecho With the default of 1, echoes events (such as breakpoints) with event numbers when executed. $hasmeta For international users. When set to 1, causes any 8-bit character to be interpreted as the corresponding 7-bit character plus the Meta character (which is the ALT key whose MSB bit represents a Meta modifier). This could be used for binding editing functions to ALT plus key sequences. The default depends on several factors, including the locale and whether the terminal has Meta capability. In the United States, the default is usually 0. $hexints When set to 1, all integers are displayed as hexadecimal numbers. The default is 0. $historylines Specifies the number of previously input commands listed in re- sponse to the history command. The default is 20. $indent With the default of 1, specifies that structures will be printed with added indentation to render them more readable. $lang Specifies the programming language used in the program being de- bugged. For mixed-language programs, $lang is set to the language corresponding to the current frame. The variable is updated when the program execution stops. $listwindow Specifies how many lines the list command displays. The default is 20. $main Specifies the name of the function that the debugger enters first. The default is main(), but this can be set to any function. This variable is useful when debugging languages whose primary function is called something other than main(). $maxstrlen Specifies the maximum number of characters to print when the value of a string is printed. The default is 128. $octints When set to 1, the debugger prints all integers as octal numbers. The default is 0. $overloadmenu When debugging C++ programs only, if this variable is set to 1, a menu of overloaded functions is displayed so you can select the desired function from the list of type signatures of the function. When set to 0, no menu is displayed, and you must disambiguate overloaded functions by providing the full type signature. The default is 1. $parentprocess Can be specified in place of the process ID in commands that take a process ID as an argument. (Ladebug automatically sets this variable when an application forks a child process.) $pid Indicates the process ID of the current process. Only for use in kernel debugging (either local or remote). $pimode Specifies whether the playback input command echoes input. If set to 1, commands from the script file are echoed. If set to 0, com- mands are not echoed. The default is 0. $prompt Specifies the debugger prompt. The default is (ladebug). $repeatmode With the default of 1, causes the debugger to repeat the previous command if you press the Return key at the (ladebug) prompt. $stackargs With the default of 1, causes the values of arguments to be in- cluded in the output of the where, up, down, and dump commands. When large or complex values are passed by value, the output can be voluminous. You can set $stackargs to 0 to suppress the output of argument values. $stepg0 With the default of 0, causes the debugger to step over calls to routines that are compiled without symbol information. When set to 1, the debugger will step into these calls. The default is 0. $stoponattach When set to 1, causes the debugger to stop a running process right after attaching to it. When set to 0, causes the debugger to allow the process to run to completion; in this case, to interrupt the process, enter Ctrl/C. The default is 0. $stopparentonfork When set to 1, instructs the debugger to stop the parent process when a program forks a child process. (See also the $catchforks description.) The default is 0. $threadlevel Enables Ladebug to determine whether you are working with DEC- threads or native threads. The default is "decthreads" if the ap- plication is multithreaded and is using DECthreads. Otherwise, the default is "native". You can switch from one mode to another by setting $threadlevel. In kernel mode, $threadlevel is always "native". $tid Indicates the thread ID of the current thread within the current process. You can change to a different thread by setting $tid. Only for use in kernel debugging (either local or remote). $usedynamictypes With the default of 1, instructs the debugger to display dynamic type information. When set to 0, static type information is dis- played. The default is 1. Output of the print, trace, tracei, and whatis commands is affected. $verbose When set to 1, specifies whether debugger output should include all possible program information, including base pointers and vir- tual function pointers (for C++ programs only). The default is 0. setenv [env_variable [value]] Sets the value of the specified environment variable. If no variable is specified, the command displays the values of all the environment variables. If a variable is specified but no value is specified, the variable is set to NULL. This command is not for the current debuggee's environment, but for the environment of any debuggees subsequently created with fork(2) , or with subesquent run or rerun commands. Note that export and setenv are synonyms. sh command Use the sh command to execute a Bourne shell command. Do not enclose the shell command and its arguments in quotations. For example: (ladebug)sh ls -l sample.c show condition [condition_identifier_list] show condition [condition_identifier_list] with state == wait For DECthreads only: Use the show condition command to list informa- tion about currently available DECthreads condition variables. If you supply one or more condition identifiers, the debugger displays infor- mation about the condition variables you specify, provided that the list matches the identity of currently available condition variables. If you omit the condition variable specification, the debugger displays information about all the condition variables currently available. Use the show condition with state == wait command to display informa- tion only for condition variables that have one or more threads wait- ing. If $verbose is set to 1, the sequence numbers of the threads wait- ing on the condition variables are displayed. show mutex utex_identifier_list] show mutex utex_identifier_list] with state == locked For DECthreads only: Use the show mutex command to list information about currently available mutexes. If you specify one or more mutex identifiers, the debugger displays information about only those mutexes you specified, provided that the list matches the identity of currently available mutexes. If you omit the mutex identifier specification, the debugger displays information about all mutexes currently available. Use the show mutex with state == locked command to display information exclusively for locked mutexes. If $verbose is set to 1, the sequence numbers of the threads locking the mutexes are displayed. show process show process * show process all Use the show process command to display information for the current process. The second and third forms of the command display information for all processes. show thread [thread_identifier_list] show thread [thread_identifier_list] with state == ready show thread [thread_identifier_list] with state == blocked show thread [thread_identifier_list] with state == running show thread [thread_identifier_list] with state == terminated show thread [thread_identifier_list] with state == detached show thread [thread_identifier_list] with state == stopped Use the show thread command to list all the threads known to the debug- ger. If you specify one or more thread identifiers, the debugger dis- plays information about the threads you specify, if the thread matches what you specified in the list. If you omit a thread specification, the debugger displays information for all threads. Use the show thread command to list threads that have specific charac- teristics, such as threads that are currently blocked. To display lists of thread characteristics, use one of the alternate syntaxes listed. The valid state values for DECthreads are ready, blocked, running, ter- minated, and detached. The valid state values for native threads are stopped, running, and terminated. source filename Use the source command and the playback input command to execute debug- ger commands contained within a file. (Note that you can also execute debugger commands when you invoke Ladebug by creating an initialization file named .dbxinit. By default, Ladebug searches for this file during startup, first in the current directory; if it is not there, Ladebug searches your home directory for the file.) Format commands as if they were entered at the debugger prompt. When a command file is executed, the value of the $pimode debugger variable determines whether the commands are echoed. If the $pimode variable is set to 1, commands are echoed; if $pimode is set to 0 (the default), commands are not echoed. The debugger output resulting from the commands is always echoed. status The status command lists all breakpoints, tracepoints, and watchpoints, the reference number associated with each, and whether they are dis- abled. All settings are on a per-process basis. step [expression] Use the next and the step commands to execute a line of source code. When the next line to be executed contains a function call, the next command executes the function being called and returns to the line im- mediately after the function call. The step command executes only the first line of the function. For multithreaded applications, use these commands to step the current thread while putting all other threads on hold. If the optional expression argument is supplied, Ladebug evaluates the expression as a positive integer that specifies the number of times to execute the command. The expression can be any expression that is valid in the current context. stepi [expression] Use the stepi command and the nexti command to execute a machine in- struction. When the instruction contains a function call, the stepi command steps into the function being called, and the nexti command ex- ecutes the function being called. For multithreaded applications, use these commands to step the current thread while putting all other threads on hold. If the optional expression argument is supplied. Ladebug evaluates the expression as a positive integer that specifies the number of times to execute the command. The expression can be any expression that is valid in the current context. stop variable stop [variable] if expression stop [variable] at linenumber [if expression] stop [variable] at "filename":linenumber stop [variable] in function [if expression] stop [variable] in "filename"`function [if expression] stop [variable] [thread thread_identifier_list] [at linenumber] [if expression] stop [variable] [thread thread_identifier_list] [at "filename":linenumber] [if expression] stop [variable] [thread thread_identifier_list] [in function] [if expression] stop [variable] [thread thread_identifier_list] [in "filename"`function] [if expression] Enter the stop command without a variable argument to suspend program execution and return to the prompt. (All breakpoint settings are on a per-process basis.) Enter the stop command with a variable argument to suspend program exe- cution when the variable changes. Specify if with an expression to suspend execution when the expression evaluates to true. When you specify both an expression and a variable, execution suspends only if the specified expression evaluates to true and the variable has changed. To suspend execution when a line or function is encountered, use the third, fourth, or fifth syntax form. If you specify a variable, execu- tion suspends only if the variable has changed when the line or func- tion is encountered. If you specify an expression, execution suspends only if the expression evaluates to true when the line or function is encountered. If you specify both a variable and an expression, execu- tion suspends only if the variable has changed and the expression eval- uates to true when the line or function is encountered. Specify a filename and function to instruct Ladebug to stop in a par- ticular function in the specified file, thus eliminating ambiguity. Use syntax forms 7, 8, 9, or 10 for multithreaded applications. The thread_identifier_list parameter identifies one or more threads of the current debugging level (native or DECthreads). If you specify one or more thread identifiers, the breakpoint is set only in those threads. If you do not specify any thread identifier, the breakpoint is set on all threads or at the process level. The following example shows how to suspend program execution when line number 10 is encountered and the variable f is equal to 2: (ladebug)stop at 10 if f==2 For C++: stop in [classname::]function stop in object.function stop in objectprt->function stop in object.function if (&object==this) stop in [classname::]classname[(type signature)] stop in [classname::]~classname stop in [classname::]function(type signature|void) stop in all function The first form of the stop command sets a breakpoint in a member func- tion using the static class type information. This form presumes that run-time information from an object is needed to determine the address of the function at which to set the breakpoint. If you need run-time information to determine the correct virtual func- tion, use the second or third form to qualify the function name with the object when you set the breakpoint. Note that this way of setting the breakpoint causes the debugger to stop at the member function in all objects declared with the same class type as the specified object. To set a breakpoint that stops only in the member function for this specific object and not all instances of the same class type, use the fourth syntax form of the stop command. The fifth and sixth syntax forms set breakpoints in a constructor and destructor, respectively. To set a breakpoint in a specific version of an overloaded function, either set $overloadmenu to 1, enter the command stop in function, and choose the appropriate function from the menu, or specify the function and the type signature as arguments to the command. If the overloaded function has no parameters, void must be explicitly specified. Use the last syntax form to set a breakpoint in all versions of an overloaded function. stopi variable stopi [variable] if expression stopi [variable] at address [if expression] Enter the stopi command with a variable to suspend execution when the variable value changes. Specify if with an expression to suspend execution when the expression evaluates to true. When you specify both a variable and an expression, execution suspends only if the specified expression evaluates to true and the variable has changed. To suspend execution when an address is encountered, use the third syn- tax form. If you specify a variable, execution suspends only if the variable has changed when the address is encountered. If you specify an expression, execution suspends only if the expression evaluates to true when the address is encountered. If you specify both a variable and an expression, execution suspends only if the variable has changed and the expression evaluates to true when the address is encountered. The stopi command is different from the stop command because the debug- ger checks the breakpoint set with the stopi command after executing each machine instruction. Thus, the debugger performance is affected when you use the stopi command. thread [thread_identifier] Use the thread command to identify or set the current thread context. If you supply a thread identifier, the debugger sets the current con- text to the thread you specify. If you omit the thread identification, the debugger displays the current thread context. The debugger interprets the thread identifier as a DECthreads or kernel thread identifier, depending on the value of the debugger variable $threadlevel. trace [variable] [if expression] trace [variable] at linenumber [if expression] trace [variable] in function [if expression] trace [variable] [thread thread_identifier_list] [at linenumber] [if expression] trace [variable] [thread thread_identifier_list] [in function] [if expression] When you use the trace command without an argument, the debugger prints a message, but does not suspend program execution when each function is entered. Specify a variable to print a message when the variable value changes. Specify if with an expression to print a message when an ex- pression evaluates to true. When you specify both a variable and an ex- pression, a message is printed only if the expression evaluates to true and the variable has changed. To print a message when a line or function is encountered, use the sec- ond or third syntax form. If you specify a variable, a message is printed only if the variable has changed when the line or function is encountered. If you specify an expression, a message is printed only if the expression evaluates to true when the line or function is encoun- tered. If you specify both a variable and an expression, a message is printed only if the variable has changed and the expression evaluates to true when the line or function is encountered. The following example traces the variable f when the program is execut- ing the function main: (ladebug)trace f in main Use the trace thread command to set tracepoints in specific threads. If you list one or more thread identifiers, the debugger sets a trace- point only in those threads you specify. If you omit the thread iden- tifier specification, the debugger sets a tracepoint in all the threads of the application. For C++: Use the $usedynamictypes variable to control whether Ladebug displays static (value=0) or dynamic (value=1) information. The de- fault is dynamic. tracei [variable] [if expression] tracei [variable] at address [if expression] tracei [variable] in function [if expression] tracei [variable] [thread thread_identifier_list] [at linenumber] [if expression] tracei [variable] [thread thread_identifier_list] [in function] [if expression] When you use the tracei command, the debugger prints a message, but does not suspend program execution. Specify a variable to print a mes- sage when the variable value changes. Specify an expression to print a message when an expression evaluates to true. When you specify both a variable and an expression, a message is printed only if the expression evaluates to true and the variable has changed. To print a message when an address or function is encountered, use the second or third syntax form. If you specify a variable, a message is printed only if the variable has changed when the address or function is encountered. If you specify an expression, a message is printed only if the expression evaluates to true when the address or function is encountered. If you specify both a variable and an expression, a message is printed only if the variable has changed and the expression evaluates to true when the address or function is encountered. The tracei command differs from the trace command in that the debugger evaluates the tracepoint set with the tracei command after the debugger executes each machine instruction. Thus, when you use the tracei com- mand, the debugger performance is affected. In the following example, a breakpoint is set to print a message every time the function factorial is entered: (ladebug)tracei factorial Use the tracei thread command to set tracepoints in specific threads. If you list one or more thread identifiers, the debugger sets a trace- point only in those threads you specify. If you omit the thread iden- tifier specification, the debugger sets a tracepoint in all threads of the application. For C++: Use the $usedynamictypes variable to control whether Ladebug displays static (value=0) or dynamic (value=1) information. The de- fault is dynamic. unsetenv [env_variable] Removes the specified environment variable. If no variable is speci- fied, all environment variables are removed. This command is not for the current debuggee's environment, but for the environment of any debuggees subsequently created with fork(2), or with subsequent run or rerun commands. up [number] Use the up command or the down command without an argument to change the function scope to the function located one level up or down the stack. Enter a number argument to change the function scope to the function up or down the specified number of levels. If the number of levels exceeds the number of active functions on the stack, the debug- ger issues a warning message. When the function scope changes, the debugger displays the source line corresponding to the last point of execution in that function. use [directory] unuse [directory] unuse * Enter the use command without an argument to list the directories the debugger searches for source-code files. Specify a directory argument to make source-code files in that directory available to the debugger. (You can also use the ladebug command -I option to specify search di- rectories.) Enter the unuse command without an argument to set the search list to the default, the home directory, the current directory, and the direc- tory containing the executable file. Include the name of a directory to remove it from the search list. The asterisk (*) argument removes all directories from the search list. watch emory] start-addr ,[end-addr] | :size-expression] [any | changed | read] [thread id_list] [in function] [if expression] [{command[;...]}] The watch command suspends program execution, prints the watchpoint event, prints the instruction that accessed the watched memory, dis- plays old and new values, and prints the first line of source code that will be executed when program execution continues. Write accesses are detected by default. Use the start_addr [,end-addr] parameter to indicate the address or ad- dress range to be watched. Addresses can be given in any base. If neither the optional end-addr nor size-expression parameters are speci- fied, the debugger defaults to a data size of 8 bytes. The size-ex- pression parameter can be any expression that is valid in the current context and language. To detect accesses other than default write access, use the any, changed, or read options. The any option detects any access. The changed option detects any change in the value of the contents of the watched memory. The read option detects only read access. Use the thread id_list option to suspend execution when access occurs in a certain thread. Use the in function option to suspend execution when access occurs in a certain function. Use the if expression option to suspend execution at the point at which the expression is true. Use the command option to specify command to execute when a watchpoint suspends execution. Commands must be enclosed in braces. Separate multiple commands with semicolons. whatis expression The whatis command prints the type of the specified expression. The ex- pression can be any expression that follows the syntax, scope, and vis- ibility rules of the program language. For C++: whatis classname whatis [classname::]member whatis [classname::]function whatis classname::classname The first syntax form of the whatis command displays the class type. The second syntax form displays the type of a member function or data member. To display all versions of an overloaded function, use the third syntax form. To use this command as a constructor only, use the last syntax form. Use the $usedynamictypes variable to control whether Ladebug displays static (value=0) or dynamic (value=1) information. The default is dy- namic. when {command[;...]} when if expression {command[;...]} when at linenumber [if expression] {command[;...]} when in function [if expression] {command[;...]} when [thread thread_identifier_list] [at linenumber] [if expression] {command[;...]} when [thread thread_identifier_list] [in function] [if expression] {command[;...]} Use the when command to execute the specified command. (The when com- mand does not suspend program execution.) The debugger command must be enclosed in braces. Separate multiple commands with semicolons. To execute a command when an expression evaluates to true, use the sec- ond syntax form. To execute commands when a line or function is encoun- tered, use the third or fourth syntax form. If you specify an expression, the command is executed only if the ex- pression evaluates to true when the line or function is encountered. Example: (ladebug)when at 5 {list;where} Use the when thread command to set tracepoints in specific threads. If you list one or more thread identifiers, the debugger sets a tracepoint only in those threads you specify. If you omit the thread identifier specification, the debugger sets a tracepoint in all the threads of the application. wheni {command[;...]} wheni if expression {command[;...]} wheni at linenumber [if expression] {command[;...]} wheni in function [if expression] {command[;...]} wheni [thread thread_identifier_list] [at linenumber] [if expression] {command[;...]} wheni [thread thread_identifier_list] [in function] [if expression] {command[;...]} Use the wheni command to execute the specified command. (The wheni command does not suspend program execution.) The debugger command must be enclosed in braces. Separate multiple commands with semicolons. To execute a command when an expression evaluates to true, use the sec- ond syntax form. To execute a command when an address or function is encountered, use the third or fourth syntax form. If you specify an expression, the command is executed only if the ex- pression evaluates to true when the address or function is encountered. The wheni command differs from the when command in that the debugger evaluates the tracepoint set with the wheni command after each machine instruction is executed. Thus, using the wheni command affects perfor- mance. For example, the following command stops program execution, lists ten lines of source code, and displays the stack trace when the value of the variable i is equal to 3 in the function main: (ladebug)wheni in main if i == 3 {wi;where} Use the wheni thread command to set tracepoints in specific threads. If you list one or more thread identifiers, the debugger sets a trace- point only in those threads you specify. If you omit the thread iden- tifier specification, the debugger sets a tracepoint in all the threads of the application. where [number] where [number] thread [thread_identifier_list] where [number] thread all where [number] thread * The where command displays the stack trace of currently active func- tions for the current thread. The second form of the command displays the stack traces of the specified threads. The third form and the fourth form of the command are equivalent; they display the stack traces of all threads. Include the optional number argument to list that number of levels at the top of the stack. (Each active function is designated by a number that can be used as an argument to the func command. The top level on the stack is 0; if you enter the command where 3, you will see levels of 0, 1, and 2.) If you do not specify the number argument, you will see all levels. whereis expression The whereis command shows all declarations of the expression. Each dec- laration is fully qualified with scope information. which expression The which command shows the fully qualified scope information for the instance of the specified expression in the current scope. If available to the debugger, the name of the source file containing the function in which the expression is declared, the name of the function, and the name of the expression are included. The syntax of the output is "filename"`function`variable. RESTRICTIONS The maximum command-line length is 100,000 characters. Alias commands cannot contain more than 56 arguments. FILES Default object file name. Default core dump file name. Initialization file. By default, Ladebug searches for this file at startup, first in the current directory; if it is not there, Ladebug searches your home directory. RELATED INFORMATION ada(1) c89(1) cc(1) cxx(1) cobol(1) f77(1) f90(1) printf(1) signal(3) Ladebug Debugger Manual. delim off ladebug(1)